graviti

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

Exceeds annotation coverage by explaining the semantics of output fields (info_quality, evidence_state, attributed_url, offers) and clarifying that certain data is for transparency/disclosure only and never a ranking input. Also discloses attribution behavior and absence 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?

Purpose is front-loaded in the first sentence, and subsequent sentences each add meaningful field-level context. Minor redundancy in repeated 'never a rank/ranking factor' phrasing prevents a 5.

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?

Without an output schema, the description effectively conveys the output structure and special field semantics. It does not mention pagination, sorting, or response format, but for a read-only landscape view this is unlikely to be required.

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 'category' parameter is fully described in the schema (with examples and omit behavior), so schema coverage is 100%. The description adds no additional parameter details beyond the schema, aligning with the baseline score of 3.

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?

Clearly states a specific verb ('view') and resource ('comparison-table of every brand in a category'), distinguishing it from sibling get_* tools and match/report tools. The scope is unambiguous.

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?

Provides clear context that the tool returns a brand comparison table for a category, with explicit instructions on omitted category meaning 'all categories'. Does not explicitly mention alternatives, but the purpose is distinct enough to infer when to use it.

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?

The annotations already indicate read-only, idempotent, and non-destructive behavior, so the description does not need to repeat that. It adds useful transparency about provenance, verification meanings, the fact that verification never influences ranking, and that efficacy is not assessed, which clarifies the tool's data 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 grammatically organized but somewhat repetitive, with 'never influences ranking' and 'never a ranking input' conveying the same idea twice. It also uses parenthetical asides that could be tightened, though the main points remain clear.

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?

Because there is no output schema, the description should compensate by specifying the response shape, but it only lists conceptual fields (provenance URLs, freshness timestamps, corroboration counts) without indicating whether the result is a single object or a list. It also omits error cases and pagination, leaving some operational context unspecified.

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 brand parameter is fully documented in the schema with an example ('bioptimizers'), and the description reiterates that it is a brand id or name. The description adds no additional detail about expected format, case sensitivity, or error behavior, so it meets the baseline but does not exceed it.

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 title and description clearly state the tool retrieves structured claims for a single brand, with a specific noun phrase ('claims with provenance') and a required brand parameter. However, it does not contrast itself with sibling tools like get_gap_report or get_ledger, so some sibling differentiation is left to the agent.

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 does not state when to prefer this tool over the sibling tools, nor does it mention typical use cases or prerequisites. It explains internal semantics of verification statuses and ranking, but not the conditions that should trigger a call to get_verified_claims.

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 discloses extensive behavioral traits beyond the annotations: ranking is purely by fit score, verification status never affects rank, out-of-scope questions return explicit in_index:false, catalog_only brands are never recommended, URL attribution details (utm_source and signed token), and offers never affect ranking. This far exceeds the annotations and gives the agent deep insight into side effects and edge cases.

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 long but well-structured and front-loaded with purpose. It covers many edge cases and output details in a logical order. While it could be tightened, every sentence adds useful information and avoids redundancy.

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 complexity of the tool and the absence of an output schema, the description fully explains the return format: ranked recommendations, out-of-scope handling, catalog_only placement, URL fields, and offers block. It covers all critical aspects an agent needs to correctly invoke and interpret results.

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 input schema already documents both parameters thoroughly (100% coverage). The description adds little beyond what the schema provides, mostly repeating the optional nature of intent_profile and the natural-language phrasing of question. No new semantic meaning is introduced for parameters.

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 action (match) on a clear resource (buyer intent to brands) and explains the output (recommendations ranked by fit score). It is clearly distinct from sibling tools like category_landscape or get_verified_claims, which serve different functions.

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 provides rich context on when this tool is appropriate (for matching buyer questions to brands) but does not explicitly compare it to alternatives or state exclusions. It implies usage but leaves the selection decision to the agent without direct guidance on when not to use it.

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 only provide readOnlyHint=false, destructiveHint=false, etc., which are minimal. The description goes far beyond by detailing side effects: it moves no money, calls no external service, never deletes or overwrites, and the response reports persistence status. It also discloses that conversions are recorded as 'reported' and never affect rank, and that gvt tokens are cryptographically verified. This is exemplary behavioral disclosure with no contradiction to 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 a single dense paragraph but is efficiently written. The core action is front-loaded, and every sentence adds relevant context (safety, optional parameters, verification). It could be split into bullet points for easier scanning, but it contains no filler or repetition. It is more verbose than necessary but earns its length.

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 mutation tool with no output schema, the description covers all essential aspects: what the tool does, its side effects, how to attribute correctly, and what the response conveys. It explains the demo-stub nature and the distinction between reported vs. rank input. Given the moderate complexity and available schema descriptions, nothing critical is missing for correct invocation.

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 schema already documents most parameters with descriptions (gvt, offer_code, agent_platform, conversation_id, order_value_usd). The description adds meaningful context for the optional parameters: gvt is verified against the Ed25519 key and provides provenance, and offer_code attributes the conversion to a captured deal. It does not add new semantics for required parameters like brand_id, but it compensates well for the optional ones, exceeding the schema's coverage.

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 begins with a precise action ('Appends one attributed-transaction event to a log'), identifies the resource (a log) and the domain (attributed conversions), and further clarifies it is a demo stub of a pay-on-real-acquisition loop. This clearly distinguishes it from sibling read/get tools like get_ledger or match_intent, making the purpose unmistakable.

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 (to report a real, attributed conversion) but does not explicitly contrast it with alternatives. It states payment flows only on real transactions and never on impressions or rank, which guides correct usage, but it never says 'use this when...' or names sibling alternatives. The context is clear from the sibling list, but the guidance is implicit rather than explicit.

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