ChainChoice published rankings

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value by enumerating the returned content (per-criterion weights, quoted passages, source URLs, retrieval dates), which matters because no output schema exists.

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?

A single dense sentence with no filler, front-loading the scope (one category, optionally one product) before the returned fields. The phrasing 'the day it was read' and the compressed list of outputs read slightly awkwardly but stay economical.

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 does the necessary work of describing the return shape, and it covers both parameters' roles. It is silent on volume (how many criteria/products come back) and any pagination, which is a minor remaining gap for a two-parameter read tool.

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 coverage is 100% and both parameters are already documented with their source of valid ids, so the baseline is 3. The description contributes only the confirmation that the product filter is optional and narrows the per-product detail rather than the category itself.

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 names the resource precisely (per criterion: weight, score, quoted passage, source URL, read date) scoped to one category and optionally one product, which is clearly distinct from get_ranking's aggregate view. It never states the verb outright (implied by the 'Get' title) and does not name siblings, so it stops short of a 5.

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 only implied: the agent can infer this is the drill-down behind a category's scores, and the schema hints that ids come from list_categories and get_ranking. There is no explicit when-to-use, when-not-to-use, or alternative-naming guidance in the description itself.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the exact return payload and a reproducibility guarantee — the order matches what the category page and rankings.json publish — though it says nothing about behavior for an invalid or unranked category.

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?

Two tight sentences, front-loaded with the resource and immediately followed by the payload contents; nothing is padding. The repeated 'publish/published' wording is slightly redundant but minor.

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 only two parameters, no nested objects, no output schema and rich annotations, the description is nearly sufficient — it compensates for the missing output schema by listing the fields returned. The remaining gap is sibling disambiguation against get_ranking_for_country, which a mature definition would resolve.

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%, and the category parameter's example ids and the limit's 1-50 range with default 10 are already fully documented in the schema. The description adds only the framing 'one category' and does not clarify ordering or what happens when limit exceeds the ranking length, so baseline 3 applies.

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 names the resource ('the published order of one category') and enumerates the payload fields (rank, product id, name, ChainChoice Score, methodology version, dimension weights, assessment), so an agent knows exactly what it gets back. It stops short of differentiating itself from the sibling get_ranking_for_country, which an agent could easily confuse with a category-only ranking.

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?

There is no when-to-use or when-not-to-use guidance at all; the description only says what the tool returns. The most likely misuse case, calling this instead of get_ranking_for_country, is never addressed, and no prerequisites (e.g. resolving a category id first) are stated in prose.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real behavioral context: an availability filter is applied and, when nothing passes it, resultMode becomes 'fallback' and rows are the unconfirmed published order. That is exactly the non-obvious edge case an agent would otherwise misread as confirmed data. It does not mention ordering stability or what limit truncation does to the response.

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?

Two sentences, both earning their place: the first establishes the return semantics, the second front-loads the fallback edge case. No redundancy with the title or schema, and 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?

With no output schema, the description carries the burden of explaining return values, and it does so by naming score, rank, order, and the resultMode fallback state. Coverage is nearly complete for a three-parameter read tool; only the relationship to get_ranking and pagination behavior are left 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?

Schema description coverage is 100%, so the schema already documents category, country, and limit including defaults and the ISO pattern. The description adds the notion of a country availability filter being applied, but does not explain the limit parameter or how truncation interacts with rank values, so baseline 3 applies.

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 and scope: a category's products as seen by a reader in one country, returned in order with published score and rank. It is clear what the tool returns, but it never names or contrasts with the sibling get_ranking, so an agent must infer the difference between the country-scoped and unscoped variants.

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 only implied — 'as a reader in one country sees them' signals that this is the country-specific view, which hints at when to prefer it over get_ranking, but no explicit when-to-use, when-not, or alternative is named. There are no stated prerequisites either, such as needing a category id from list_categories.

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, non-destructive and closed-world, and the description corroborates rather than repeats them by specifying what is guaranteed absent: no referral/affiliate link, no revenue, no logging, no ranking mutation, nothing opened. It also discloses the receipt signing key and the not-served short-circuit, which annotations cannot express. Slightly short of a 5 only because it does not describe failure modes beyond the country case.

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 precondition is front-loaded and the closing sentence cleanly lists what the tool does not do. The first sentence is a long comma-laden enumeration of the returned fields that is denser than it needs to be, but every clause carries real information.

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?

There is no output schema, so the description carries the return-value burden and does so thoroughly: it names each handed-over field, the receipt's signing key, and the handedOff=false outcome with a reason. For a consent-gated hand-off tool with six parameters, an agent has everything needed to call it and interpret the result.

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 coverage is 100%, so the baseline is 3, and the description adds genuine semantics on top: consent gates the whole call, query is preserved in the receipt, country drives the serves-country decision, and vol is the reader's monthly volume. It stops short of explaining edge behavior for optional fields, so it is above baseline but not exhaustive.

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?

States a specific verb and resource — returns what to hand over once the reader has consented — and enumerates the payload (provider address, rank, score, country, volume, page, serves-country, signed receipt). It also explicitly bounds the tool against siblings by saying it does not open anything, log the reader, or change rankings.

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 trigger condition is explicit and front-loaded: call only once the reader has agreed (consent: true). It also names the downstream verification path (check the receipt with verify_receipt) and states the negative case — a provider that does not serve the reader's country yields handedOff=false with a reason.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral content: each entry carries a ranked-product count, an assessed-and-excluded count with a reason, a leader, and a page reference — important because there is no output 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?

A single front-loaded clause states the scope, followed by a compact enumeration of returned fields. Nothing is redundant and no sentence is wasted.

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 must carry the return-value burden and it does so for the main fields. It is slightly incomplete on ordering (ranked by what?) and on how the 'page' reference should be consumed, but for a zero-parameter listing tool it is nearly 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies the call needs no arguments and returns the full set.

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 names a specific resource (every category ChainChoice ranks) and its scope is unambiguous: all categories, no filtering. It does not explicitly contrast with siblings such as get_ranking or search, so it falls short of a 5, but an agent can still tell this is the enumeration endpoint rather than a lookup.

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 only implied — 'every category' suggests this is the discovery step before calling get_ranking, but the description never says when to choose it over search or get_ranking. There are no exclusions or prerequisites stated.

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 readOnly, idempotent, non-destructive and closed-world, so the safety bar is low; the description still adds real behavior: readBy only appears while the model tier is on and released by its measured eval, country precedence follows the words, and the answer card carries figures from the published ranking. It does not cover empty/no-match behavior, pagination or limits, which keeps it off a 5.

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 purpose is front-loaded in the opening clause, which is good. The remainder is a single long sentence built from deeply nested parentheticals enumerating return fields, which makes it hard to parse and easy to lose the key country-precedence rule mid-stream; the content earns its place but the structure does not.

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?

There is no output schema, so the description carries the full burden of return-value explanation, and it does so thoroughly across page types, the answer card fields, readBy, and open. The main omission is failure/empty-result behavior for a free-text query, which an agent would want before calling.

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 coverage is 100% and both parameters are documented, so the baseline of 3 applies. The description does add one genuinely useful rule the schema lacks: country applies to a ranked list only when the words name none, and a country in the words wins. Beyond that it restates the query parameter's intent rather than adding syntax or format detail.

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 first clause names a specific verb and resource: it reads a query the way ChainChoice's search bars do and returns that reading, enumerating the outcome types (ranked list, product verdict, compare, guide, clarifying question). An agent can tell this is the natural-language entry point. It never names a sibling tool (get_ranking, get_evidence) as the alternative, so differentiation is implied rather than stated.

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: this is the reader-style front door, and the enumeration of page types shows the contexts it covers. There is no explicit when-to-use versus get_ranking or get_evidence, no stated conditions for preferring structured lookups, and no note on what happens when nothing matches.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real context beyond that: verification is against ChainChoice's published keys, and accepted input is either a ChainChoice-served receipt or an issuer envelope. It stops short of disclosing what a failed or malformed verification produces.

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?

Two tight sentences with the verification action front-loaded and the checks enumerated immediately after. The API-endpoint cross-reference is compact and 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?

There is no output schema, so the description carries the burden of describing the result, yet it never says what verification returns (a boolean, a status object, per-check breakdown) or how failures surface. The nested receipt object's internal shape is also left entirely unspecified. Adequate for invocation, incomplete for interpreting the outcome.

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 coverage is 100%, so the baseline is 3, but the description genuinely extends the bare schema text 'The receipt JSON, with its signature' by clarifying the two accepted envelope forms. That distinction affects what the agent should pass and is not present in the input 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?

States a specific verb and resource ('Checks a signed receipt') and enumerates the exact checks performed: content-hash match and signature validity. No sibling (get_evidence, get_ranking, search, hand_off) performs validation, so an agent can route to this tool unambiguously.

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?

Implies its use case (verifying a receipt you already hold) and adds a useful anchor by noting it is the same verifier as POST /api/v1/verify. However, there is no explicit when-to-use vs. when-not, no guidance on what to do with a failed check, and no prerequisites stated.

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