graviti

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds substantial behavioral meaning beyond the annotations: it explains info_quality semantics (0–100 disclosure completeness, transparency not rank factor, absent means not yet assessed), evidence_state tiers and their ranking implications, and attribution URL behavior. These details materially shape how an agent should interpret and use results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: it states the core view, clarifies ranking-related caveats, defines evidence states, and explains URL attribution. The most important purpose is front-loaded, and no content is redundant with the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining what the tool returns, and it does so thoroughly: rows, verification status, info_quality, evidence_state, and URL fields are all covered. It also addresses subtle behavioral traps such as not treating absent info_quality as zero and not ranking catalog_only entries, making it complete for correct agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already fully documents the optional category parameter with examples and the omit-for-all behavior. The tool description does not need to add parameter detail, and it does not, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: a comparison-table view of every brand in a category across disclosed attributes, with verification status marked per entry. This clearly distinguishes it from sibling tools like get_ledger or get_verified_claims, which target different resources and formats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: when an agent wants a category-level brand comparison table. However, it does not explicitly name alternatives or state when-not-to-use conditions, leaving the agent to infer routing from sibling names and general context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint:false, and the description goes well beyond them. It discloses that the log is public and machine-readable, that confirmation asks are visible but 'never a penalty,' that payment status is disclosed but 'findings and rank never affected,' and that roster changes are permanently recorded. These are meaningful behavioral guarantees an agent needs to understand trust and side-effect semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the central concept ('Public, machine-readable log of every seal lifecycle change') and then groups related event types. It is longer than strictly necessary and includes one mostly rhetorical sentence ('a pulled seal is the loudest proof it means something'), but most clauses carry useful operational meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, the description ably covers what the log contains and its behavioral guarantees. It does not specify pagination or output shape, but for an unfiltered public log with rich annotations, the description is sufficiently complete for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add about parameters. The description indirectly affirms the unfiltered nature by saying 'every seal lifecycle change' and 'every future change,' which supports the baseline of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource ('Public, machine-readable log') and enumerates its exact scope: seal lifecycle changes, confirmation-loop events, claim removals, gap report deliveries, and roster events. This makes the tool's purpose unambiguous and clearly distinguishes it from sibling getters by content coverage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly tells an agent when to use this tool by listing what it returns, but it never explicitly contrasts it with get_ledger, get_verified_claims, or get_gap_report. There are no when-to-use/when-not-to-use guidelines or named alternatives, so the agent must infer selection criteria from content rather than receive direct guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as read-only, idempotent, and non-destructive; the description goes further by disclosing that it is a demo of a paid product, computed deterministically from the index, and in production uses consented/compensated cohort signals without profiles leaving the user's agent. It also discloses a clear fallback for catalog-only brands, adding substantial behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and front-loaded with the core purpose, and every clause adds meaningful behavioral or scoping detail. It loses one point for being a single long paragraph with a slightly idiosyncratic aside ('publishing more truth, not paying Graviti') rather than clearly separated purpose, behavior, and fallback sections.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, read-only report with no output schema, the description is nearly complete: it enumerates the report contents, notes the deterministic computation, explains production data sources and privacy constraints, and covers the insufficient-evidence fallback. It only stops short of describing the exact response structure or field names an agent would need for programmatic parsing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter `brand` is already fully documented in the schema with type and an example, and schema coverage is 100%. The description adds no brand-specific parameter nuance, but none is needed given the schema's completeness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the deliverable: a brand gap report showing attribute gaps vs. the category leader, open flags, cohort blind spots, disclosure dimensions, and an info_quality score with publishable fixes. It distinguishes this from sibling tools by focusing on brand-vs-leader gap analysis and evidence sufficiency, not category landscape, ledger, or conversion reporting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for assessing a brand's competitive gap and mentions the catalog-only fallback, but it does not explicitly state when to use this tool instead of siblings like category_landscape or match_intent. Some situational guidance is present, but no exclusions or alternative-selection rules are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses substantial behavioral detail: append-only semantics, hash-chained rewriting consequences, Ed25519 signatures, OpenTimestamps anchoring, and the strong immutability claim that 'even Graviti cannot rewrite the record.' This adds real value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, front-loaded with the tool's core purpose, and every sentence adds meaningful information. It avoids fluff while covering behavior, output, and security properties.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only tool, the description is nearly complete: it explains what is returned and why the data is trustworthy. The lack of an output schema means entry structure is not detailed, but that is a minor gap given the simple invocation and rich behavioral context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and schema coverage is 100%, so there are no parameter semantics for the description to augment. With no parameters, the baseline of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies a specific verb and resource: 'get' + an append-only version history of the index. It clearly conveys the tool's identity through hash-chaining, Ed25519 signing, and Bitcoin anchoring. However, it does not explicitly contrast with closely related siblings such as get_accountability_log.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool—when tamper-evident, verifiable history is needed—and notes that verification instructions are returned. It does not provide any explicit when-not-to-use guidance or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description goes well beyond this by explaining that 'verified' means the brand pays for auditing, that info_quality never influences ranking, that Graviti does not assess efficacy, and that awaiting_brand_confirmation claims should be treated as unconfirmed rather than violations. These are non-obvious behavioral details an agent cannot infer from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

All four sentences add substantive context and the main purpose is front-loaded. The description is dense but not padded; minor tightening of the nested parentheticals could improve readability, but every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining return content, and it covers the main fields, block semantics, and status caveats. It stops short of specifying the exact container structure or behavior for unknown brands, but for a single-parameter read tool this is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, brand, is already fully documented in the schema with a type, description, and example. The description refers to 'one brand' and claims for a brand but does not add new syntax or constraints, so with 100% schema coverage the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Structured claims for one brand' and enumerates the distinctive content: provenance URLs, freshness timestamps, corroboration counts, and verification status. This clearly identifies a read-only retrieval tool for per-brand claims and differentiates it from siblings such as get_gap_report or get_ledger by scope and content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It specifies that the tool operates on a single brand and gives important interpretive context about verification status and the info_quality score. It does not explicitly name sibling alternatives or state when not to use it, but the usage context is clear enough to select this tool appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the annotations, revealing that verification status is disclosed but never affects rank, out-of-scope questions return in_index:false instead of guesses, and catalog_only brands are never scored or recommended. It also explains the URL attribution behavior and explicitly notes that no user data is included, giving an agent a strong mental model of the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the primary purpose and then adds dense, high-value behavioral detail without filler. Every sentence provides actionable information for selecting or invoking the tool correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description covers key return fields and edge cases: in_index, in_landscape_not_evidenced, site_url, attributed_url, and recommendation ranking behavior. This is sufficient context for an agent to understand what the tool returns and how to handle the two main non-standard cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds minimal extra parameter meaning beyond clarifying that the question is natural language and the intent profile is optional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's verb and resource: it takes a natural-language buyer question and returns brand recommendations ranked by fit score. It doesn't explicitly differentiate from sibling tools by name, but the behavior described is distinct enough to make the tool's purpose clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: the tool should be used when you have a natural-language buyer question and want brand recommendations ranked by fit score. However, it never explicitly states when to prefer this tool over alternatives or mentions any of the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses critical non-obvious behaviors: it moves no money, calls no external service, never deletes or overwrites anything, and the response states where and whether the event was persisted. This substantially exceeds the annotation signals and gives an agent a safe, accurate mental model of the operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a focused three-sentence paragraph with the core behavior front-loaded. Every sentence earns its place: what it does, what it does not do, and how to use the optional attribution token. There is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, no output schema, and the presence of a safety-relevant annotation set, the description is complete. It clarifies persistence behavior, response intent, financial safety, and the optional verification flow, which is more than enough for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 60%, and the description adds real meaning for the gvt parameter by explaining its provenance and Ed25519 verification. It does not deeply elaborate brand_id or order_value_usd, but those are reasonably self-descriptive, and the gvt guidance goes well beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Appends one attributed-transaction event to a log.' It clearly identifies this as the conversion-reporting tool and differentiates itself from the get_* sibling tools, which are read-only and have no mutation role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description conveys that this tool is for reporting real attributed conversions, explicitly stating 'Payment only ever flows on real transactions, never on impressions or rank.' It does not name alternative tools, but the contrast with all-getter siblings makes the intended use clear enough without explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.