ExchangeRebel — pay-per-call APIs for AI agents (x402 on Solana)

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

Annotations only flag it as open-world, idempotent, non-destructive and not read-only; the description goes far beyond that by disclosing the pricing model ($0.005 USDC on Solana via x402), the exact MCP payment handshake (first call returns PaymentRequired, retry with _meta["x402/payment"]), the payer-of-record-equals-sender rule, free rejection of undeliverable sends, opaque ciphertext storage, and 30-day retention. These are precisely the operational traits an agent cannot infer from 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 core action and payload shape are front-loaded, followed by prerequisites, pricing, and the HTTP equivalent. The single dense paragraph carries a lot of value per clause, though the x402/payment mechanics and endpoint URLs could be split into a separate sentence for easier scanning.

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 paid, open-world mutation with no output schema, the description covers everything needed: prerequisites (declared mailboxes, payer identity), the payment dance, failure modes (free refusal before payment), retention, and a fallback HTTP endpoint. Nothing an agent needs to invoke it successfully is missing.

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 baseline is 3, but the description adds real meaning: the mailbox must be a declared Ed25519 pubkey (declared at POST /toll/a2a/mailbox/declare), the payer of record must equal the 'from' mailbox, and the signature is defined over the a2a-msg/v1 payload. It reinforces rather than merely repeats the constraint of 'exactly one of to / to_handle'.

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: 'Send one 1:1 direct message through the A2A ciphertext relay', and immediately disambiguates with '1:1 DM only'. It makes the tool's scope unmistakable relative to the rest of the catalogue, where no sibling overlaps.

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 names the alternative path explicitly ('Free pre-check at POST /toll/a2a/send/preflight') and states the constraint that only 1:1 DMs are supported, plus that undeliverable sends are refused free before payment. What's missing is a clear statement of when an agent should skip this tool entirely (e.g. group/multicast cases routed elsewhere), so it falls short of a full when/when-not treatment.

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?

Goes well beyond the annotations: it discloses tiered pricing ($0.05 first 25 pages, $0.02 beyond), that the price is a ruled sitemap total previewable before payment, that per-page failures are listed and excluded from totals, and that an all-fail run stores nothing and queues exactly one refund intent. The x402 payment mechanics (challenge on unpaid call, retry with _meta["x402/payment"]) are also spelled out, matching the non-readonly, non-idempotent 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?

Front-loads the core purpose and cap, then layers pricing, failure handling, and payment flow in a logical order with no filler. It is dense and long, but nearly every clause carries operational information an agent needs; the trailing HTTP-equivalent note is the only mildly extraneous element.

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 paid, crawl-scoped tool with no output schema, the description covers cost model, cap, failure/refund semantics, disclosure model, preflight path, and payment handshake — everything needed to invoke it correctly and predict the failure modes. Nothing material is missing.

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 both parameters are already documented there. The description's only added param context is the 50-page cap and the derived /sitemap.xml behavior, which the schema already states, so it neither compensates for nor adds much to the structured data. 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?

States a specific verb and resource — accessibility findings for every same-origin page in a site's sitemap, capped at 50 — and implicitly distinguishes it from access_scan (single page) by referencing the shared disclosure model. An agent can tell what it produces and its scope without opening the schema.

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?

Explicitly directs the agent to call access_crawl_preflight first for a free exact price preview, which is a clear routing rule. It also separates itself from access_scan by scope ('every same-origin page in a sitemap'). It lacks an explicit when-not-to-use statement, so it stops short of a 5.

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?

Adds substantial context beyond annotations: no page is rendered, nothing is charged, no x402 challenge, and the returned number matches what the unpaid call puts in its 402. It also explains what request_fingerprint does (binds the price). The safety/behavior profile is richer than readOnlyHint/idempotentHint alone.

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?

Front-loads 'FREE preflight' and the core behavior, with zero wasted sentences. Slightly over-stuffed with em-dash asides and a raw HTTP-equivalent string, which is minor bloat but informative.

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 fully documents the return payload (pages found/billed, tier split, totals, fingerprint) and the cost/side-effect story. For a read-only preflight, an agent has everything needed to call 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 coverage is 0% and both url and sitemap_url are undocumented in the schema. The description only says 'Same input as access_crawl', which defers meaning to a sibling and does not explain the distinction between url and sitemap_url or why neither is required. That is a real gap for a tool whose only parameters are undocumented.

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+resource ('FREE preflight for access_crawl') and precisely what it returns: tiered price preview with pages found, pages billed, tier split, totals, plus a request_fingerprint. It is clearly distinguished from the sibling access_crawl (which performs the paid, rendering call).

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 gives clear context for use: call this before the paid call to preview price, and 'no payment required: call directly without payment'. The relationship to access_crawl is explicit ('same input'). It stops short of explicit exclusions (there is no 'don't use this to actually crawl' statement), so 4 rather than 5.

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 declare open-world, non-idempotent, non-destructive behavior; the description adds substantially more: $0.05 pricing, x402 payment handshake details including the _meta['x402/payment'] retry, an automatic refund intent on failed delivery, coverage limits (~57% of issues, 20-40% of WCAG criteria), and 90-day free report retrieval. This is exactly the kind of context structured fields cannot carry.

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?

Front-loaded with purpose and return shape, then limitations, then payment mechanics — a sensible ordering. It is long and repeats the x402 story in two places ('price RULED' and the parenthetical MCP/HTTP note), costing it a point, but nearly every sentence carries operational 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?

No output schema exists, so the description must describe returns — and it does fully: verdict-first summary, per-finding fields, capped samples, incomplete checks surfaced, and report_id retention. Combined with the payment and preflight instructions, an agent has everything needed to call 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?

Single required parameter with 100% schema description coverage; the schema already documents the http/https-only, ports 80/443, no-private/loopback/credentialed-URL constraints. The description adds no further meaning about the url argument beyond payment metadata, so the 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?

States a specific verb+resource ('Accessibility findings for one page from automated checks in a real headless browser') and scopes it to a single page, which implicitly separates it from the access_crawl sibling. An agent can tell what it does and what it does not cover without opening the schema.

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?

Explicitly prescribes sequencing ('Call access_scan_preflight first to check servability and price for free') and sets boundaries ('Findings only; automated checks cover a subset'). It does not name access_crawl as the alternative for multi-page work, so the routing guidance is inferred rather than 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?

Goes well beyond the annotations (which only cover read-only/idempotent/open-world safety) by disclosing the cost model (free, no x402 challenge), the absence of side effects (no render, no charge), and the exact shape of the response including the fingerprint that binds the quote to the URL. This is precisely the behavioral context annotations cannot convey.

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?

Front-loaded with the key fact (free preflight) and the return contents, which is good. However, the free/no-charge message is repeated three times ('FREE,' 'no charge,' 'no payment required... this tool is free'), and the HTTP-equivalent line adds length of marginal value to an MCP caller.

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 one-parameter, no-output-schema tool, the description covers return values, cost, and side-effect absence, so an agent can call it confidently. The remaining gap is that the vocabulary of the response ('fence verdict,' 'servability') is never defined, leaving the agent unsure what values to expect.

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 0% — the single `url` parameter has no description. The description partially compensates by noting 'same URL input' as access_scan and that the fingerprint binds the quote to 'this exact URL,' implying the URL is the scan target, but it gives no format, scheme, or normalization guidance.

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 ('FREE preflight for access_scan') and enumerates exactly what comes back: servability, fence verdict, $0.05 toll quote, and request_fingerprint. It is clearly distinguishable from the sibling access_scan and from access_crawl_preflight by naming the parent tool it preflights.

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?

Tells the agent to call it directly without payment ('no x402 challenge; this tool is free') and signals the boundary with access_scan by stating 'no accessibility signal of any kind is returned.' It stops short of explicitly saying 'use access_scan when you need the actual accessibility result,' but the implication is strong and unambiguous.

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 adds essential behavior beyond the annotations: cost is $0.01 per call, payment is USDC on Solana via x402, MCP callers should first trigger a PaymentRequired challenge and retry with payment metadata, and results are returned in deterministic id order. This is exactly the operational context an agent needs for a paid data query.

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 front-loaded: purpose and filters come first, followed by return behavior, payment details, and HTTP equivalent. Every sentence carries relevant information, though it could be slightly tighter.

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 paid query tool with four optional parameters and no output schema, the description covers filtering, return ordering, cost, and the x402 payment handshake. It does not detail the fields in the returned full service records, but that is not essential 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?

Schema description coverage is 100%, so all four parameters are already documented in structured data. The description restates the filter meanings, including that maxPriceUsd matches services with at least one paid endpoint at or under the bound, but does not add materially 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 clearly states a specific verb and resource: a ranked shortlist over the Agent Data Core store of service records with category, price, verification, and limit filters. It is easy to distinguish from most siblings by resource and operation, though it does not explicitly name an alternative tool it should not be confused with.

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 by the description: call this to get a filtered, ranked shortlist of services. The payment flow is explained, but there is no explicit when-to-use vs when-not-to-use guidance or named alternative such as a full snapshot or verification-report tool.

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 readOnly/idempotent/non-destructive, so the description's added value is the cost and scope profile: free, no payment, and deliberately limited to metadata with zero paid or record data returned. That is useful context an agent would otherwise have to infer, though response shape/pagination is not discussed (no output schema exists to cover it).

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 scope statement is front-loaded, but the free/no-payment point is repeated three times ('FREE', 'Free — no payment required', 'no paid data'), and the em-dash clauses make the second sentence dense. It is compact but contains clear 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?

With no parameters and no output schema, the definition still names the exact returned fields and points to the external endpoint for the full document, which is what an agent needs before calling. Only the response encoding/format of the descriptor is 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?

The tool takes zero parameters and the schema is fully closed (additionalProperties: false), so there is nothing for the description to disambiguate. Baseline for a 0-param tool 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?

States a specific verb and resource: returns only the snapshot descriptor with its three fields (generated_at, service count, byte size). It explicitly carves out what it does NOT return (no service records, no paid data), which separates it from the adc_* family, though no sibling tool is named directly.

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?

Tells the agent when this applies (free descriptor, no payment) and when it does not (it is not the snapshot itself — that is the REST GET URL), plus 'call it directly' removes any preflight ambiguity. It stops short of naming which adc_* tool to use when actual records are needed.

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?

Adds substantial context beyond the annotations: the $0.05 per-call price, USDC-on-Solana via x402, the exact MCP flow (call unpaid to receive the PaymentRequired challenge, retry with _meta["x402/payment"]), and the fact that unknown service ids are answered free before payment. This also explains why readOnlyHint is false despite the read-like nature of the tool, so the flags are not contradicted.

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?

Front-loads what the report contains, then the pricing and payment flow, then the HTTP equivalent — a sensible order with no filler. The x402 retry instruction and HTTP endpoint are procedural but earn their place for an agent that has to actually pay and call it.

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, no-output-schema tool, the agent knows what it returns, what it costs, how to satisfy payment, and what happens on a bad id. The remaining gap is comparative positioning against the other adc_* tools, which would help an agent choose correctly in a crowded namespace.

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 the schema already defines service_id as the toll prefix slug, so the description does not need to restate that. It does add value by specifying behavior for an unknown service_id (answered free, before payment), which is semantic information about the parameter the schema cannot express.

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 ('Deep verification report for one service in the Agent Data Core store') and then enumerates the report's contents (verification state/evidence, health, delivery proof, demand, scorecard, endpoint counts, record-level sources). That enumeration is what separates it from list-style siblings like adc_shortlist and adc_snapshot_descriptor without opening their schemas.

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: you call it for deep diligence on a single service. The description spends most of its second half on payment mechanics rather than telling the agent when to pick this over adc_shortlist or adc_snapshot_descriptor, and there are no explicit exclusions. The free-unknown-id note gives a useful edge-case rule, but no selection 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?

Goes well beyond annotations: flat $0.01 pricing, refusal semantics that are free, result ordering (one per-leg object in request order), and the x402 payment dance (call without payment to get the challenge, retry with _meta["x402/payment"]). The one slight tension is readOnlyHint=false on what is semantically a validation read, but that is plausibly justified by the payment side effect, not a real contradiction.

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?

Front-loaded with the core purpose and price, then constraints, then payment mechanics. Dense but every sentence carries information; the payment/HTTP-equivalent block is the longest and least essential to tool selection.

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 covers return shape (one per-leg object, request order) and all refusal/pricing behavior; with an open-world paid tool, the payment flow and preflight are exactly what an agent needs. Nothing material is missing.

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 baseline is 3; the description adds real meaning by explaining that legs must be 2-3 (reinforcing minItems) and that a 1-leg call is rejected, plus that extra state is needed for the us leg. It stops short of explaining any other field, but the schema carries that.

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+resource ('fan one structured address out to 2-3 live legs') with the exact leg codes, and implicitly separates itself from address_leg_nl/address_leg_us via the 1-leg refusal guidance. An agent can tell exactly what this does and how it differs from the single-leg tools.

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?

Explicit routing: 1-leg requests refuse — 'use the leg tool instead'; Canada is only available in this bundle; unavailable legs (nz, es) refuse the whole bundle; free pre-check endpoint given. When-to-use, when-not, and alternatives are all 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?

Discloses what annotations cannot: exact price ($0.005/call), the x402 payment handshake (call unpaid to receive PaymentRequired, retry with _meta["x402/payment"]), a free preflight alternative, data provenance/license, and an explicit negative ('No confidence field'). This also explains why readOnlyHint=false despite a query-shaped operation — the call has a monetary side effect.

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?

Front-loaded with purpose, then output contract, then the payment mechanics that determine whether the call will fail. Slightly wasteful: '$0.005' appears twice and the HTTP-equivalent URL plus the base URL both restate the same endpoint identity.

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?

No output schema exists, and the description supplies the return contract (status vocabulary, returned components, provenance, absence of confidence). It also covers cost, payment path, and a free preflight. What is missing is failure/error behavior and any rate limit on the paid endpoint.

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 the nested address object is already documented as street_number/street_name/locality/postcode required with unit/street_type/state optional. The description adds only that the preflight takes 'the same body', with no extra format, normalization, or postcode rules.

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+resource: Netherlands address validation against BAG via PDOK Locatieserver, and names the outcome vocabulary (matched / partial / no_match). The 'nl' scope implicitly separates it from address_leg_us, address_bundle and address_verify, but it never explicitly contrasts with those siblings.

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?

Gives one concrete usage routing rule: a free pre-check endpoint to hit before spending money. It does not say when to choose this leg versus address_verify, address_bundle, or address_leg_us, leaving the agent to infer that routing from the tool name alone.

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 convey almost nothing useful here (readOnlyHint false, openWorldHint true), so the description carries the load and does: it discloses pricing per call, the exact x402 payment handshake (call without payment to receive PaymentRequired, retry with _meta['x402/payment']), and the interpolation flag on returned coordinates. That is materially more than the annotations provide.

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?

Front-loaded with purpose and price, then scope caveat, then payment mechanics — a sensible order with no filler. It is dense, and the payment/HTTP-equivalent tail is long, but every clause carries operational 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?

With no output schema, the description must carry the return semantics, and it does partially (range_match/no_match, preserved house-number range, interpolated:true coordinates). The full response shape and error behavior are still unspecified, which for a paid call is a minor gap.

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 single nested address object documents every component, so baseline is met. The description adds only that address.state is required, which is already in the schema's required list, so there is little value beyond the structured field.

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+resource (US address-validation leg via Census Geocoder) and pins the scope to the United States, which is what separates it from address_leg_nl and address_bundle. It also names the exact return vocabulary (range_match / no_match) so the agent knows what it is buying.

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?

Gives clear operating context: a free preflight endpoint to call first, and the interpretive caveat that a range match is not an existence verdict. It stops short of naming the sibling to use for a true existence verdict (address_verify), so the agent must infer the alternative.

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?

Adds substantial behavior beyond annotations: exact pricing ($0.01/call, $0.005 per extra country), the x402/USDC-on-Solana payment path, the _meta["x402/payment"] retry convention, and an HTTP fallback. Annotations cover safety flags but say nothing about cost or the two-step payment dance, which the description supplies.

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?

Front-loads the purpose in the first clause and then packs price, payment mechanics, and HTTP equivalent into two more sentences with no filler. Dense but every sentence carries operational weight.

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, yet the description never indicates what a verification verdict looks like (normalized address? deliverability flag? per-country results?). Payment and endpoint details are complete, but return-value expectations and sibling disambiguation are missing for a paid tool with a nested-object input.

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 nested address object and country/countries parameters are already fully documented in the schema. The description only echoes the 1-4 country limit and omits the 'supply either country or countries, not both' exclusivity that the schema carries. 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?

States a specific verb and resource ('Verify an address') plus scope ('in 1-4 countries'), so the action is unambiguous. It does not, however, distinguish itself from nearby siblings such as address_bundle, address_leg_us, or address_leg_nl.

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?

Gives clear operational guidance for the payment flow (call without payment to receive the PaymentRequired challenge, then retry). It never says when to choose this over address_bundle or the single-leg address tools, leaving sibling selection to inference.

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?

Far beyond the annotations, it discloses flat $0.25 pricing, the settlement rail (USDC on Solana via x402), the exact payment handshake required on MCP, the result ordering guarantee, and hard input limits. These are exactly the traits an agent needs before committing a paid call. No statement conflicts with the readOnlyHint=false / destructiveHint=false 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?

One dense paragraph that front-loads purpose and limits, then pricing, then the payment mechanics — a sensible order for an agent deciding whether to call. It is slightly run-on with the HTTP URL and preflight path jammed into the tail, but no sentence is 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?

There is no output schema, and the description compensates by stating the return shape (per-series, per-point, request order, each with its own method block). Combined with the payment protocol and input caps, an agent has everything needed to call this correctly on the first attempt.

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 nested series_list already documents {series, timestamps?, sensitivity?} plus the 1..100 and 100,000-point caps, so the description largely restates structured data. It adds a little value by tying parameters to output ('per-series per-point results in request order'), but says nothing about what sensitivity levels mean or what timestamps are used for.

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+resource ('Batch anomaly detection') and immediately quantifies scope (1..100 series, 8..10,000 points each, <=100,000 total), which implicitly distinguishes it from the single-series sibling anomaly_detect. It never names anomaly_detect explicitly, so the routing contrast is inferred from the 'Batch' framing 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?

It gives concrete operational context: a free pre-check endpoint exists, and the MCP payment flow is spelled out (call without payment to receive the PaymentRequired challenge, then retry with the payment at _meta['x402/payment']). What it lacks is any explicit when-to-use-this-vs-anomaly_detect guidance or note about when the preflight should be preferred.

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?

Goes well beyond the annotations by disclosing that thresholds are uncalibrated defaults, that output is a statistical signal and never a determination, that scoring is whole-series retrospective, and the full cost/payment mechanism ($0.01 USDC on Solana via x402, retry at _meta["x402/payment"]). No claim conflicts with readOnlyHint=false / destructiveHint=false; the absence of any mutation behavior is consistent with a paid compute call.

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?

Front-loads purpose and returned fields before caveats, then payment mechanics, so the agent gets the essentials first. Dense but almost every clause carries information; the HTTP-equivalent URL and payment retry instructions add length that a caller may need but that dilutes the core statement.

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 compensates by naming the exact return constituents (per-point robust score, boolean flag, fired signals). It also covers cost, payment retry, preflight, and interpretation caveats, so an agent has everything needed to call it and interpret the result without guessing.

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; the description adds real meaning by warning that sensitivity presets are uncalibrated defaults and by framing the point-count range as a hard validity constraint. It does not elaborate on the relaxed/strict direction beyond what the enum description already states, so it edges above baseline rather than fully owning parameter semantics.

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 ('Anomaly detection for one numeric time series') with explicit bounds (8..10,000 points) and enumerates what it returns (per-point robust score, boolean flag, fired signals). The 'one numeric time series' scope implicitly separates it from the sibling anomaly_batch, and the named methods (median/MAD robust z, iqr_fence, step_change) make the operation 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?

Gives clear operating context: global whole-series retrospective statistics, free shape/size-only preflight before paying, and the exact x402 payment retry flow. It does not explicitly say when to prefer this over anomaly_batch or when a series is too short/streaming-inappropriate, so it stops short of full alternatives 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?

With no annotations supplied, the description carries the full burden and does reasonably well: it discloses that no payment/x402 challenge applies, that the content is a static published criteria set, and that reports are reproducible from it. It exposes the HTTP equivalent (GET endpoint), reinforcing that this is a side-effect-free read. It doesn't discuss caching, versioning behavior, or response size, but the safety and cost profile are clear.

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 core content list is front-loaded and specific, and the usage warning follows immediately. The payment clause is slightly repetitive — 'no payment required: call directly without payment (no x402 challenge; this tool is free)' says the same thing three ways — which is the main trimming opportunity.

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 and no parameters, the description must tell the agent what it will receive, and it does: a section-by-section inventory of the criteria document plus its versioned identity (breaking-change-diff/v1) and the pinned corpus. An agent knows exactly what it is getting and why 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?

The tool takes zero parameters, so the baseline of 4 applies and there is nothing for the description to compensate for. Schema coverage is 100% with an empty properties object, consistent with the description's no-argument framing.

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 exact resource: the published criteria for the breaking-change-diff/v1 service, and enumerates its sections (parsing rules, seventeen diff rules with outcome tokens, NOT-ASSESSABLE list, pinned test corpus identity). That is far more specific than a tautology, though it is phrased as a noun phrase rather than an explicit verb like 'returns'/'fetches'. It is clearly separable from the sibling apidiff_diff, which produces reports rather than the rules behind them.

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 gives concrete timing guidance: 'Read these before paying for a diff', which implicitly routes the agent to apidiff_diff after reading. It also states the tool is free and needs no payment, an important discriminator in a family where the downstream diff presumably costs money. It does not explicitly name apidiff_diff or apidiff_precheck as the alternatives, so it stops short of a full when/when-not statement.

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?

With zero annotations the description carries the full burden and does so well: it discloses the exact price and chain ($0.02 USDC on Solana per pair), the billing unit (one report per pair), that documents are processed in memory and never stored, and that a paid retry re-sends both documents. It also bounds the result explicitly ('not a safe to upgrade certification'), which prevents over-trust in the output.

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?

It is a single dense run-on of three long sentences with stacked subordinate clauses, and the actual purpose arrives after the price. Front-loading cost is defensible for a paid tool, but the 'processed in memory only and never stored' clause is repeated in the schema and the middle sentence carries too many clauses at once.

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 paid, mutable-effect tool with no output schema, the description covers cost, privacy, retry behavior, scope limits, and roughly what the report contains. What is missing is payment mechanics (how the USDC charge is authorized) and failure/refund behavior, which an agent needs before committing funds.

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 version_a, version_b, and the pairs array including their mutual exclusivity and accepted formats. The description adds only the charging semantics for pairs and the retry-resends-both behavior, which is marginal beyond the structured fields. 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 concrete resource: a signed breaking-change diff report for one pair of submitted documents, with per-token counts and located removed/added/changed findings under breaking-change-diff/v1 rules. That is far more specific than a restatement of the name. It never names the sibling tools (apidiff_precheck, apidiff_criteria) that an agent would likely weigh it against, 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?

Use is implied rather than directed: the price is front-loaded and the closing sentence excludes a 'safe to upgrade' certification as an intended use. However, no alternative tool is named and there is no instruction to run apidiff_precheck first, despite that sibling clearly existing in the same family. An agent can infer this is the paid, final diff step, but must infer 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?

No annotations are supplied, so the description carries the full behavioral burden. It does well on cost/limit (free, 100/day per wallet, caller-keyed) and on scope of the response (gradability, census, verdict line, per-class change counts), but it leaves out error/failure modes, what happens when the pair cannot be graded, and what a 'census' or 'verdict line' actually contains. The disclaimer that it is a deterministic mechanical comparison that does not establish code breakage is valuable added context.

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?

Front-loaded with the most decision-relevant facts ('FREE headline breaking-change pre-check'), then formats, then outputs, then the disclaimer. Slightly dense with parenthetical rate-limit and format lists, but every sentence carries information an agent needs.

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 annotations and no output schema, the description must explain both behavior and returns, and it does list the headline outputs and the cost model. Gaps remain around failure behavior for ungradable pairs and the absence of an explicit handoff to apidiff_diff by name, which keeps it short of complete.

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 adds real meaning beyond the schema: 'pass caller' explains that the caller field keys the free allowance, and 'one submitted document pair' clarifies that the single-pair form is the default while the pairs array is an alternative. It does not repeat the schema's type constraints or explain how version_a/version_b mismatches are handled.

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?

Opens with a specific verb+resource+scope: 'FREE headline breaking-change pre-check of one submitted document pair', and clarifies which document formats are accepted (OpenAPI 3.0.x/3.1.x JSON or JSON Schema pair). It distinguishes itself from the 'paid report' conceptually, but never names the sibling tools (apidiff_diff, apidiff_criteria), so the routing signal is implicit rather than explicit.

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?

Clear situational framing: free headline first, with 'Located findings are in the paid report' telling the agent to escalate elsewhere for detail, plus the 100/day per wallet allowance that governs usage. It lacks an explicit named alternative and doesn't state when this pre-check is unnecessary (e.g., once the paid report is already known needed).

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/closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: it is free with no payment required, it returns descriptors only and no prices, and it gives the HTTP equivalent (GET /eligible). It does not mention result size, ordering, or pagination.

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?

Front-loaded and short, but the 'Free:' opener and the later 'Free — no payment required' repeat the same point, and the em-dash chain packing eligibility criteria plus six return fields into one sentence is denser than it needs to be.

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 usefully enumerates the returned descriptor fields, which is the main thing an agent needs. It leaves open whether the list is bounded, ordered, or paginated, a minor gap for a zero-argument listing 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 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?

States a concrete resource (arena-eligible targets) and even defines the eligibility predicate — services with a paid endpoint that carries a price — plus the descriptor fields returned. It never names the obvious siblings (arena_quote, arena_run), so differentiation is only implied by the 'carries no prices' note 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 discovery/listing step, and the 'carries no prices' line hints that a pricing call is a separate tool. But there is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer the workflow.

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 read-only, idempotent, non-destructive, closed-world, and the description is consistent with that. Beyond them it adds real behavioral detail: the call is free, wrong targets are still answered free of charge, and the price is derived from the endpoint's own listed prices rather than a global fee schedule.

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 compact sentences with the core definition front-loaded before the pricing mechanics and the HTTP equivalent. Dense but no wasted sentences; the 'HTTP equivalent' trailer is only modestly useful.

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 explain what the quote comprises (3-call plan plus per-test-call cost) and the free-on-failure guarantee, which is the main thing an agent needs to act on. Minor gaps remain around currency/units and whether the quote expires, but the essentials are covered.

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 self-documented, so the schema does the heavy lifting. The description's only added semantic is that pricing comes from the target endpoint's own listed prices when endpoint_path narrows the target, which is marginal over the schema text.

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 — a free cost quote for one verification run — and itemizes what the quote contains (the fixed 3-call plan plus summed constituent test-call prices). It does not explicitly contrast itself with arena_run or arena_eligible, so an agent must infer the quote/run/eligibility split rather than being told.

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?

'before payment' and 'answered free' imply this is the pre-run pricing step and that unknown/ineligible targets cost nothing, which is useful timing guidance. However, no sibling is named as the next or alternative step (arena_run, arena_result), so the workflow position is only implied.

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?

Goes beyond the readOnly/idempotent annotations by disclosing that results contain digests only and never payloads, that the call is free, that unknown ids are handled gracefully, and by naming the HTTP equivalent. Minor vagueness remains in 'the write-back events when built', which doesn't say when those are absent.

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?

One front-loaded sentence packs the verb, resource, output contents, and privacy caveat, followed by a short edge-case note and the HTTP mapping. No sentence is 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 compensates by enumerating the returned fields, and the single required parameter is documented. It leaves open how large the per-call record set can be or whether truncation/pagination applies, which is the only notable gap for a result-retrieval 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?

Only one parameter and schema coverage is 100%, with the schema already stating the id comes from arena_run. The description reinforces the run_id semantics but adds no format, validation, or lookup behavior beyond what the schema provides, 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?

States a specific verb and resource ('read one run's status and result by run_id') and then enumerates exactly what comes back: lifecycle state, verdict, per-call records, write-back events. It is clearly the read counterpart to arena_run, so an agent can distinguish it from the sibling that creates the run.

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 'by run_id' framing plus the note that an unknown run id is answered free tells the agent this is a lookup on an existing run rather than a launcher. It doesn't explicitly say 'call arena_run first to obtain the id', though the schema parameter description does, so usage is clear but not fully spelled out 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 only mark it as a non-readOnly, open-world, non-idempotent write; the description adds the material facts an agent actually needs: payment is required via x402 on Solana with a challenge-then-retry flow, invalid targets cost nothing, payloads are never stored, and retests inside 24h are flagged reputation_counted: false. These are behaviors the annotations cannot express.

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?

Front-loaded correctly with the verb and payment mechanics, but the middle section is bloated: tier prices are stated twice (the 'Prices (RULED)' line, then again in the 'What the standard $25 includes' paragraph) and item lists are enumerated at length. The content is relevant, yet several sentences could be compressed without losing 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?

Despite having no output schema, the description explains what a run produces: a pass/partial/fail verdict with per-dimension summaries, latency, Layer 0 write-back events including a state recommendation on pass only, leaderboard eligibility, and retained digests/call records. Combined with the payment flow and per-tier differences, an agent has everything needed 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 100%, so the schema already documents all five parameters including tier enum and prices. The description elaborates on tier semantics (prices, retest prerequisite, full-service covering every paid endpoint of a service), but that largely repeats the schema's tier description and says nothing about run_id, seller_ref or endpoint_path. Baseline 3 fits.

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?

Opens with a specific verb+resource+scope: 'Start one paid-and-judged verification run' and immediately describes what the arena does (funds, executes, judges, writes back). This is clearly distinguishable from siblings like arena_quote, arena_eligible and arena_result, which read/price rather than execute a run.

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?

Gives concrete when-to-use conditions: an unknown or ineligible target is answered free before payment, retest requires the same seller to have a prior run of the target, and tier selection is explained. It does not explicitly route the agent to arena_quote or arena_result for pricing/lookup, so the alternatives are implied rather than named.

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?

With annotations present the bar is lower, and the description goes beyond them by disclosing cost ($0.01 per call), the payment rail (USDC on Solana via x402), and the concrete challenge-and-retry protocol including the _meta["x402/payment"] key. That is exactly the kind of prerequisite/operational context annotations cannot express; only the response shape is left uncovered.

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 clause, followed by the payment mechanics and the HTTP equivalent, which are both actionable. The payment sentence is dense but every clause carries operational information; nothing is redundant.

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 one-parameter tool with no output schema, the description covers purpose, cost, payment flow, and an alternate transport. The one gap is that it never says what a response looks like (record fields, ordering, volume/caps), which matters for a paid call with no declared output schema.

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 the single 'since' parameter is fully documented in the schema, including the strict-greater-than semantics. The description only restates 'since a timestamp' and adds no syntax or edge-case detail beyond the schema, 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 a specific verb and resource ('atlas records added or changed since a timestamp') and enumerates the change classes it covers (terms changes, sunsets, status changes). This clearly distinguishes it from siblings like atlas_record (single-record lookup) without the agent needing to open the schema.

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 change-feed framing implies the polling/refresh use case, but there is no explicit when-to-use versus when-not guidance and no named alternative (e.g., use atlas_record for a single record, atlas_route for lookups). Usage is inferable but not 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 only mark it non-read-only/non-idempotent without explanation; the description supplies the reason — a $0.01 per-call charge — and the full x402 payment choreography (call unpaid to receive a PaymentRequired challenge, retry with payment in _meta["x402/payment"]). This is exactly the kind of cost/auth/retry context annotations cannot express, though the consequences of a failed or double payment are left unstated.

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?

Front-loaded with what the record contains, then the operational payment details and the HTTP fallback. Dense but every sentence carries actionable information; the payment paragraph is longer than ideal but is required for a paid tool.

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 usefully enumerates the returned fields and fully explains how to pay over both MCP and HTTP. Remaining gaps — source_id format and failure behavior on unknown sources — are minor for a single-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 description coverage is 0% for the single required source_id, so the schema gives the agent a bare string with no format. The description partially compensates by framing the parameter as identifying 'one data source', but it never states the expected identifier syntax or behavior on an unknown id.

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+resource: returns the FULL Source Atlas record for one data source, and enumerates the record's contents (lawful route, licence basis + duties, cost, freshness, failure modes, alternatives). This distinguishes it in substance from atlas_route and atlas_changes, though neither sibling is named explicitly.

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 guidance and no named alternatives: nothing tells the agent when to prefer atlas_record over atlas_route or atlas_changes, nor what prerequisites exist (e.g., needing a known source_id). The only procedural guidance given is about payment, not tool selection.

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 mark this non-read-only and non-idempotent, and the description supplies the missing reason: a $0.01 per-call charge in USDC on Solana via x402, settled only on retry with a payment payload. This is exactly the kind of hidden cost/side-effect context annotations alone cannot convey. It stops at 4 because failure modes and what happens if payment validation fails are not covered.

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?

Front-loaded with the purpose, then cost, then the payment mechanics — a sensible order. Three dense sentences with no filler, though the parenthetical payment instructions and HTTP endpoint are tightly packed and the HTTP URL is of limited use to an MCP caller.

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?

The commercial mechanics are complete, but with no output schema the description carries the burden of describing what a 'ranked lawful route' actually contains (route fields, licence verdict shape, ranking rationale) and it only gestures at this. An agent knows how to call it and what it costs, but not what it will receive.

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 0% and the single parameter 'need' is undocumented in the schema. The description only offers 'state a need', which hints at natural language but gives no format, length, example, or specificity guidance. For a 1-param tool with zero coverage, this is a real gap the description was positioned to fill.

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 — 'state a need, get ranked lawful routes with licence verdicts' — which is clearly a routing/lookup service, distinct from siblings like atlas_record and atlas_changes. The phrase 'lawful routes' is somewhat opaque (routes of what, ranked by what criteria), so it stops short of a 5, but an agent can tell what class of operation this is.

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 explicit when-to-use vs when-not, and no mention of the atlas_* siblings, so alternative selection is left to inference. That said, the invocation path is unusually well spelled out — the two-step x402 challenge/retry flow and the HTTP equivalent endpoint — which is genuine procedural usage guidance even if the 'when' is missing.

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 adds important behavior beyond the annotations: cost per call, USDC on Solana payment via x402, the PaymentRequired challenge flow, and the exact _meta key for retry. It does not explain the return value or score semantics, but the payment handshake disclosure is substantial and consistent with 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 definition is compact and front-loaded: purpose first, then payment mechanics, then HTTP equivalent. Every sentence carries operational value, and the parenthetical payment retry instruction is dense but necessary.

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?

The description covers invocation and payment clearly, but with no output schema it leaves the return format and score semantics unexplained. It also does not clarify whether 'batch' refers to batch-payment vouchers or batch scoring, which matters because the schema takes a single voucher object.

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 voucher parameter is fully described in the schema, including payer, amount, nonce, expiry, issued_at, and signature. The description adds domain context ('batch-payment vouchers') but no extra syntax, format, or validation guidance beyond the schema, so 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 states a specific verb and resource: score batch-payment vouchers, scoped to settlement risk. This is concrete enough to distinguish it from general scoring or batch tools, and the domain wording tells an agent exactly what the tool evaluates.

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 intended use is implied by 'settlement risk,' but there is no explicit when-to-use, when-not-to-use, or comparison to alternatives such as bridge_score or tokens_score. The payment instructions explain how to invoke it, not when to select it over another tool.

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 cover openness and idempotency but say nothing about cost or authorization. The description adds material behavior an agent cannot get elsewhere: a $0.005 USDC-on-Solana charge, the x402 two-step challenge/retry flow, and the exact _meta["x402/payment"] key — which also explains why readOnlyHint is false for what is a metadata read.

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?

Front-loads what the tool returns, then gives price and payment mechanics, then the HTTP equivalent. Dense but every clause is actionable; the payment-parenthetical is long yet load-bearing for calling it 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?

With no output schema, the description should say what 'author metadata' actually contains, but it does not (name, birth/death, bio, works, etc.). The payment path is fully covered, so the gap is limited to return-value expectations.

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 the schema already documents the single 'id' parameter as an OL...A author id. The description only repeats the resource name and adds no format, normalization, or failure-mode detail 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 states a specific verb+resource ('Author metadata') and the identifier scheme ('Open Library author id'), which is enough to distinguish it from books_works or books_isbn. It does not explicitly contrast with the closely named sibling books_authors, so the singular-by-id vs. list distinction must be inferred from the name.

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 statement of when to use this tool versus books_authors, books_search, or books_title. The only 'how' guidance is the payment choreography, which is operational rather than selection 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?

The description goes well beyond the annotations by disclosing the price ($0.005/call), the payment rail (USDC on Solana via x402), and the exact MCP handshake — call unpaid to receive the PaymentRequired challenge, then retry with payment in _meta['x402/payment']. That is genuinely actionable behavioral context an agent cannot get from readOnlyHint/openWorldHint. It stops short of 5 because it says nothing about failure modes, rate limits, or what the challenge payload looks like.

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?

Front-loaded with the purpose, then the payment mechanics, then the HTTP equivalent — a sensible ordering with little waste. The nested parenthetical about the x402 retry is dense but every clause carries operational 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?

Payment handling is fully covered, but with no output schema the description should say what a result looks like (author keys, names, work counts) and how it differs from books_author. Those omissions leave real gaps for a tool in a crowded books_* family.

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 both parameters (q, limit with range/default) are already documented in the schema. The description adds no parameter-level meaning, so the 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?

States a specific verb and resource: 'Search authors (Open Library)'. However, it never distinguishes itself from the sibling books_author (singular), which an agent could easily confuse with this one, so it falls 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?

There is no guidance on when to use this versus books_author, books_search, books_title, or books_works. The only routing information is the HTTP equivalent URL, which does not help an agent pick among siblings.

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?

Goes well beyond the annotations by disclosing price ($0.005/call), currency and chain (USDC on Solana), the x402 payment handshake including the exact retry key _meta["x402/payment"], and an HTTP equivalent. This explains the otherwise puzzling readOnlyHint=false. It still omits failure behavior (unpaid-call errors beyond the challenge, lookup misses) and rate limits.

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?

Three compact sentences, purpose front-loaded, then cost, then the payment protocol. The x402 mechanics are dense but operationally necessary; the HTTP URL is marginally expendable but not wasteful.

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 one-parameter, paid, no-output-schema tool, it covers the essentials an agent needs: what it returns (metadata), what it costs, and how to complete payment. The main gap is return-field expectations, which the absence of an output schema leaves undocumented.

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 the single isbn parameter is already documented as 'ISBN-10 or ISBN-13 (hyphens allowed)'. The description only restates 'by ISBN' and adds no format, normalization, or error semantics beyond the schema, so the 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?

States a specific resource and lookup key: 'Book metadata by ISBN', with the upstream source (Open Library) and the 'metadata only' scope. An agent can distinguish it from siblings like books_title, books_author, books_works and books_search by the ISBN identifier, though no sibling is named explicitly.

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: you call it when you already hold an ISBN. There is no explicit when-to-use vs. books_search/books_title guidance, and no note about what to do if the ISBN is unknown (i.e., fall back to a search tool).

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 say readOnlyHint=false, which looks odd for a 'metadata only' search, but the description explains the reason: the call is billable ($0.005 USDC on Solana via x402), so invoking it has a real side effect. It also discloses the two-step payment handshake and the HTTP equivalent, context the annotations cannot convey. This is detailed, but return shape and any rate/limit behavior on the paid endpoint are not described.

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 five words, then cost, then the payment retry protocol — a sensible priority order for an agent that must decide whether to spend money. The trailing HTTP-equivalent URL is useful but is the one element that could be trimmed without losing invocation-relevant 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?

For a zero-required-parameter, four-field search with no output schema, the description covers the essential operational risk (cost and payment flow) but omits anything about result content or how many fields are matched. Given the crowded books_* sibling set, an agent could construct a valid call but not confidently pick this tool over its neighbors.

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 q, title, author and limit are already documented in the schema (including the 1-25 limit range and default of 10). The description adds no semantics about how these parameters combine or which fields are searched, so the 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?

States a specific verb and resource ('Search books') and scopes it ('Open Library, metadata only'), so an agent knows it queries a bibliographic index rather than full text or files. It does not, however, distinguish itself from the many sibling lookup tools (books_title, books_author, books_isbn, books_works), so the agent cannot tell from the description alone which entry point to prefer.

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 gives no when-to-use guidance and no exclusions; it never says whether this general search subsumes books_title/books_author or should be avoided when a specific identifier is known. The only operational instructions concern payment (call first, get PaymentRequired, retry with _meta["x402/payment"]), which is invocation mechanics rather than tool selection 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?

Strong operational disclosure beyond the annotations: exact price ($0.005/call), payment rail (USDC on Solana via x402), and the two-step challenge-then-retry protocol including the _meta["x402/payment"] key. This also explains why readOnlyHint=false despite a metadata read. Gaps remain on rate limits, failure modes other than PaymentRequired, and what a successful response contains.

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 clause, followed by pricing, payment mechanics, and the HTTP equivalent — each sentence carries distinct information. Slightly dense with protocol detail, but nothing is padding.

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 should indicate what metadata comes back (works/editions/authors, etc.) and it does not, nor does it clarify the limit parameter. Payment and endpoint context are complete, so the omission is moderate rather than fatal.

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 both parameters are already documented in the schema. The description reinforces that lookup is keyed on title but says nothing about the 'limit' parameter or what it limits (results? editions?), leaving the schema to carry 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?

States a specific resource and access key: book metadata looked up by title, sourced from Open Library, with the HTTP route spelled out. The 'by title' qualifier implicitly separates it from books_isbn and books_author, but it never names those siblings explicitly, so differentiation is left to inference.

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 by the lookup key — an agent can infer 'use this when you have a title, not an ISBN'. There is no explicit when-to-use, when-not-to-use, or pointer to books_search/books_isbn as the alternative for other query shapes.

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 say readOnlyHint=false and openWorldHint=true; the description adds the critical context annotations cannot carry — the $0.005 USDC-on-Solana cost, the x402 payment flow, and the concrete retry protocol (call once, receive PaymentRequired, retry with payment in _meta['x402/payment']). It also gives the underlying HTTP endpoint, which is genuinely operational detail.

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?

Front-loads the resource and key first, then the payment mechanics. Dense but every sentence is functional; the payment/parenthetical block is long but is the main non-obvious thing an agent needs, so it earns its space.

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?

Payment and endpoint complexity are covered well, but there is no output schema and the description never indicates what the returned 'metadata' contains (fields, shape, empty/missing-id behavior). For a lookup tool with no return-value documentation, that is a real gap.

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 the single 'id' parameter is already documented in-schema as 'Work id (OL...W)'. The description restates that same format without adding syntax, validation, or fallback guidance, 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?

States a specific resource ('Work metadata') and the exact lookup key ('Open Library work id'), which implicitly separates it from siblings like books_title, books_isbn, books_author and books_search that take other identifiers. It is clear but never explicitly contrasts itself with those siblings or says what metadata fields are returned.

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 must infer it should call this when it already holds an OL...W work id rather than a title/ISBN/author. No explicit when-to-use or when-not-to-use statement, and no pointer to a sibling for resolving an id you don't yet have.

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 by disclosing the paid nature ($0.01 per call, USDC on Solana), the exact two-step x402 handshake, and an HTTP fallback endpoint. That is behaviorally important context no structured field carries. It stops short of describing the response shape or whether scores are cached/live, 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?

Three tight sentences that front-load the purpose and then pack payment mechanics without filler. The parenthetical payment instruction is dense but earns its place; it could be split for readability but nothing 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?

For a 5-parameter, zero-required, free-form scoring tool with no output schema, the payment path is fully covered but the inputs are not - an agent still doesn't know what a valid call looks like or what it gets back. Adequate on the monetization dimension, incomplete on the data dimension.

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?

Though coverage is nominally 100%, every schema description is a vacuous type echo ("string", "number"), so the schema conveys nothing. The description names no parameters at all - token, bridge, from_chain, to_chain, and amount_usd are never explained, and the reader cannot tell whether 'token' is an asset symbol, a bridge token, or a payment token.

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 opening sentence states a specific verb and resource plus the scoring dimensions: "Score a bridge by security, liquidity, and incidents." It is clear in isolation, but it never distinguishes itself from nearby siblings such as tokens_score, batch_score, or fee_oracle_recipe, so the agent must infer the boundary itself.

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 gives strong *how-to-invoke* guidance (call without payment to receive the PaymentRequired challenge, then retry with payment at _meta["x402/payment"]), which is real usage context. It gives no *when-to-use* guidance, though: nothing says when to prefer this over tokens_score or batch_score, or which bridge/chain combinations are valid.

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?

Goes well beyond the annotations by disclosing the exact price ($0.005/call), the payment rail (USDC on Solana via x402), the concrete retry protocol (call without payment, receive PaymentRequired, retry with _meta["x402/payment"]), and an HTTP equivalent. That is precisely the non-obvious behavioral context an agent needs and annotations do not carry.

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, purpose front-loaded, payment logistics second; no filler. Every clause carries operational 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?

For a one-parameter read tool with no output schema, the payment behavior is fully covered. The remaining gap is that it never states the units or shape of the returned intensity value, which an agent must infer.

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 schema already enumerates the valid zone codes (FR, DE, GB, IE, DK, US). The description adds only 'one zone' and no additional semantics, so the 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?

States a specific verb+resource+scope: current average grid carbon intensity for a single zone. It distinguishes itself from carbon_intensity_forecast only implicitly via the word 'current' rather than an explicit call-out, so it falls 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?

The description gives no explicit when-to-use guidance, no statement of when to prefer this over carbon_intensity_forecast, and no prerequisites beyond the payment mechanics. Usage is only implied by 'current' versus 'forecast' in the sibling name.

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 declare readOnlyHint=false and non-idempotent, but do not reveal that the call costs money; the description fills that gap with the exact price ($0.01 USDC on Solana) and the two-step x402 handshake plus an HTTP fallback URL. That is real behavior context beyond structured fields. Minor gap: no mention of the forecast horizon or update cadence.

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?

Front-loaded with the purpose, then payment mechanics and the HTTP equivalent. Dense but each sentence carries information the agent needs to actually invoke a paid endpoint; the parenthetical x402 detail is slightly heavy but justified.

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?

No output schema exists, so the description should convey the shape of the returned curve (units, resolution, forecast horizon). It says only "average carbon intensity curve", leaving the agent unable to judge what it will receive, though the payment mechanics are fully covered.

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?

Only one parameter, and the schema already documents it at 100% coverage including the GB/IE/DK zone codes. The description adds nothing beyond "one zone", so 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?

States a specific verb+resource+scope: "Forecast average carbon intensity curve for one zone." An agent can distinguish it from the sibling carbon_intensity_current (forecast vs current), though the description never names that sibling explicitly.

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 gives clear procedural guidance for the payment flow (call without payment, read the PaymentRequired challenge, retry with _meta["x402/payment"]), which is genuinely actionable. However, it offers no explicit guidance on when to choose this over carbon_intensity_current or 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 carry readOnlyHint=false and openWorldHint=true; the description does the heavy lifting by disclosing the $0.05 flat cost, the constraint set (basic depth only, ≤5 sources, 400 output tokens), the preflight validation path including AUP fences, and the refund-on-upstream-failure policy. That is exactly the beyond-schema behavioral context an agent needs before spending money.

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, but roughly half the text is payment plumbing (x402, USDC on Solana, _meta key path, HTTP equivalent URL) that is dense and partly irrelevant once an MCP client handles the 402 dance. The HTTP-equivalent sentence in particular is low-value for an MCP caller and could be trimmed.

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 paid, rate/limit-bound tool with no output schema, the description covers cost, caps, failure/refund behavior, and the validation path — enough to call it correctly and predict the charge. The remaining gap is the shape of the returned answer/citations and the lack of positioning against sibling search tools.

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?

One parameter at 0% schema description coverage, so the description must compensate. It does partially: "ask a question" signals natural-language input and "query 3..512 chars" restates the schema's min/max. But the char limits duplicate the schema rather than adding meaning, and it doesn't clarify whether operators, quotes, or URLs are accepted in the query.

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?

Opens with a specific verb+resource+output: "Cited-answer web search: ask a question, get a short synthesized answer with citations to live web sources." That is unmistakably different from a raw crawl or news feed. However, it never names a sibling (wiki_answer, news_search, cse_search) that would be the natural alternative, so differentiation is left to inference.

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 gives detailed *how-to-invoke* guidance (preflight POST, payment handshake, retry with _meta["x402/payment"]) but no *when-to-use* guidance — nothing says whether to prefer this over wiki_answer or news_search, or what question types it suits. Usage is implied by the price/limit framing rather than 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 the write/idempotent/non-destructive profile, and the description goes well beyond them: earliest valid ballot wins, duplicates are logged rejected, no vote-changing, auth is the operator's Ed25519 signature verified service-side, and no x402 payment challenge is added by the MCP layer. These are exactly the failure-mode and cost facts an agent needs before calling a write.

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 critical facts are front-loaded, but the no-payment point is restated three times ('FREE — no payment required', 'no x402 challenge; this tool is free', 'the MCP layer adds no payment to it'), which is redundant weight in an otherwise dense paragraph.

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?

Covers auth mechanism, duplicate handling, cost, and the raw HTTP equivalent — substantial for a write tool with no output schema. The remaining gap is that it never says what a successful cast returns (receipt, tally acknowledgement) nor resolves the id/proposal_id duality.

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 20%, so the description must compensate, and it does explain the `signature` canonical string format. However it never disambiguates `id` vs `proposal_id` (the canonical string uses {proposal_id} while the required field is `id`), leaving the most consequential ambiguity unresolved.

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 ('Cast ONE ballot') and immediately bounds the scope with '(operator-key-signed write; agents never vote)'. An agent can distinguish this from commons_get_vote_status or commons_create_proposal without opening any schema.

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?

Gives a strong eligibility rule ('agents never vote'), a one-ballot-per-operator rule, and states that vote changes are impossible, which tells the agent when this call is pointless. It does not name a sibling for the read-side check (e.g. commons_get_vote_status), so it stops short of full alternative routing.

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?

Adds material facts beyond the annotations: a flood ceiling of 10 posts/minute per operator, that posts are not count-metered, and the exact authentication mechanism (service-verified Ed25519 signature, MCP layer adds no payment). It does not describe what happens on a duplicate post or a signature failure, leaving some mutation-side behavior undisclosed.

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?

Front-loads the action, then the signing recipe, then limits and payment posture, with an HTTP equivalent at the end. Slightly redundant: 'FREE — no payment required', 'no x402 challenge', and 'this tool is free' restate the same fact, and the closing sentence repeats the authentication point already made.

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?

Covers authentication, rate limits and payment posture well for a non-idempotent mutation, but with no output schema and 80% of parameters undocumented, the description leaves open what a successful response contains and how 'id' versus 'proposal_id' should be supplied. Adequate but with clear gaps.

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 only 20%, so the description must carry the load: it fully specifies the signature's canonical string, which is the hardest parameter, and implies body is the discussion text. However, it never explains the relationship between the required 'id' field and the optional 'proposal_id' field, even though the signature formula references {proposal_id} while 'id' is what is actually required — a real ambiguity for the caller.

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 ('Post discussion on a proposal') and scopes it as a signed write, which separates it cleanly from siblings like commons_create_proposal and commons_cast_ballot. An agent can identify the action without opening the schema.

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?

Gives clear operational context: call this directly, it is free, no x402 payment challenge is issued, and the write is authorized solely by the operator's Ed25519 signature. It never explicitly names an alternative sibling or a when-not condition, so it stops short of full routing 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?

Goes well beyond annotations: names the exact 401 error codes for unsigned (signature_required) and bad (bad_signature) requests, discloses the 80% strict adoption rule and the 100-operator floor for opening a vote, and clarifies that no payment layer sits on top. consistent with destructiveHint=false and readOnlyHint=false; nothing contradicts. It stops short of stating that repeat calls create new proposals despite idempotentHint=false, and says nothing about 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?

Front-loads the purpose and the signature recipe, which is the right ordering for a signed write. There is some waste: the FREE/no-payment point is stated twice ('FREE — no payment required: call directly without payment' and again in the closing sentence), and the closing sentence is largely redundant with the opening parenthetical.

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?

Strong on authentication and adoption mechanics for a mutation with no output schema, but an agent still cannot answer how to pick a 'category', what 'layer-roadmap' vs 'fleet-wide' implies, what 'reopen_condition' does, or whether the call returns a proposal id it will need later. Given seven parameters and no return documentation, those gaps matter.

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 only 14%, so the description must compensate. It does an excellent job on the highest-risk parameter, spelling out the canonical signing string including {sha256_hex(body)} composition and encoding, but leaves six of seven parameters unexplained: no valid values for 'category', no distinction between the two 'scope' enum members, and 'reopen_condition' is never mentioned at all.

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?

Opens with a specific verb+resource ('Create a proposal') and immediately qualifies it as an 'operator-key-signed write', which tells the agent this is an authenticated mutation. It does not explicitly contrast with the sibling commons_create_post or point to commons_cast_ballot, so sibling differentiation is left implicit.

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?

Presupplies the signing precondition and states this tool is FREE with no x402 challenge, which is meaningful routing information in a payment-gated toolset. However, it never says when to create a proposal versus a post, who is eligible to propose (the 100-eligible-operator threshold is mentioned only as an adoption rule), or what to do after creation.

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 declare readOnly, idempotent and non-destructive, so safety is covered. The description adds two things annotations cannot convey: the data is anonymized at the aggregate level (no operator ids leak), and there is no x402 payment challenge, which materially changes how the agent invokes it.

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 first clause and the HTTP equivalent is appended usefully. The payment clause is somewhat redundant ('FREE — no payment required... no x402 challenge; this tool is free' says the same thing three times).

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?

Safety and payment behavior are well covered, but with no output schema the description never hints at what the aggregates contain (which metrics, what time window, response shape). An agent knows how to call it but not what it will get back.

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 the baseline is 4. The description reinforces this by stating the output names nobody, consistent with a parameterless read.

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 ('Read fleet-level aggregate activity') and adds a privacy scope ('naming nobody (no operator ids)') that distinguishes it from operator-level siblings such as commons_get_operator or fleet_activity. It doesn't name a sibling directly, so it stops short of 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?

The payment guidance ('call directly without payment') clearly tells the agent how to invoke it, which is useful. However, there is no explicit statement about when to choose this over fleet_activity, fleet_kpis, or commons_get_leaderboards, so the choice remains inferred from the anonymity note.

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 establish read-only, idempotent, non-destructive, non-open-world behavior. The description adds important context beyond annotations: the call is free, requires no x402 payment, and returns specific archive fields.

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 key operation is front-loaded and the description is short. The payment clarification has slight redundancy ('FREE', 'no payment required', 'without payment', 'no x402 challenge', 'this tool is free'), but it remains readable.

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 simple single-record read tool with rich annotations and no output schema, the description covers the return fields and payment behavior. The main remaining gap is precise id semantics, which matters because schema documentation is absent.

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 0%, so the description must carry parameter meaning. It implies the id identifies an archived proposal via the HTTP path /archive/{id}, but it does not clarify whether this is an archive-entry id, proposal id, or required format.

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: read one archived proposal. It also enumerates the entry contents (discussion ids, tally, snapshot, reopen condition), so it is distinguishable from list-oriented archive tools and general proposal tools.

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 is for retrieving a single archived entry, and it clarifies payment is not required. However, it does not explicitly say when to use this instead of commons_get_proposal or commons_list_archive.

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 read-only/idempotent/non-destructive, and the description adds real value beyond them: append-only monotonic ordering, exclusive lower bound on since, the as-of timestamp, and — critically for agents — that no x402 payment challenge applies. It does not say what limits the feed has, whether events can be evicted, or how many events a poll can return.

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?

Front-loaded with the key concept and ordered sensibly (what it is, how to call, cost, HTTP mapping). The cost clause is redundant with itself — "FREE — no payment required: call directly without payment (no x402 challenge; this tool is free)" — which costs a bit of density.

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 one optional param, no output schema and no annotations gap, the description supplies what's needed to call it in a polling loop, including the free-tier detail that otherwise blocks an agent. Missing only the shape of returned events (field names, page size), which is not covered by an output schema.

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 0% for the single parameter, so the description must carry the meaning — and it does: since is the last seq seen, the bound is strict ("strictly after"), and the sequence is monotonic, which tells the agent the cursor is a sequence number rather than a timestamp. It does not state the default when omitted or the seq field name on returned events.

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?

"Heartbeat feed: append-only monotonic event log" gives a specific resource and behavior, and "Returns events strictly after since, in order, with an as-of timestamp" pins down semantics precisely. An agent can tell this apart from commons_get_journal, commons_get_receipts, or commons_get_archive_entry as the incremental polling primitive.

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?

"Poll this on your heartbeat and pass the last seq seen as since" states the usage pattern and the cursor convention clearly. It stops short of naming when NOT to use it or which sibling to pick instead (e.g., full-history retrieval), so no 5.

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 bar is lower. The description nevertheless adds material facts not in the annotations: that calling it is free (no x402 payment challenge) and that the entries are labelled provenance-tagged fleet events. It doesn't say anything about volume, pagination, or response shape.

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 payment statement is restated three times in a single breath ('FREE', 'no payment required', 'call directly without payment', 'no x402 challenge; this tool is free'), which is redundant. The scope sentence is front-loaded well, but the redundancy dilutes the payload.

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 telling an agent what comes back. It conveys provenance ('real fleet events only, labelled as such') but says nothing about entry structure, volume, ordering, or whether the journal is bounded or paginated. Adequate to call correctly, thin for interpreting 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 tool takes no parameters and the schema is closed with additionalProperties false, so there is nothing for the description to disambiguate. Baseline of 4 applies for a zero-parameter tool.

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: 'Read the platform journal,' and scopes the content as real fleet events only, explicitly excluding operator activity. That scope exclusion meaningfully separates it from commons_get_operator, though no sibling is named directly.

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 implies the usage context ('read the platform journal') and rules out conflating it with operator activity, but never states prerequisites, when to prefer it, or which sibling to use for operator data. There is no explicit when/when-not guidance beyond the negative scope phrase.

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 read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds genuine value beyond that: rank confers no votes or weight (important in a governance context), and the explicit 'no x402 challenge / free' note prevents the agent from wrongly assuming a payment step it has seen on other tools in this ecosystem.

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, followed by the two constraints an agent actually needs, then the HTTP equivalent for agents that bypass MCP. The payment sentence is repetitive ('FREE — no payment required: call directly without payment... this tool is free'), restating the same fact three times and wasting some space.

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 tool with no output schema and full annotation coverage, this is close to sufficient: it names the ranked metrics and the read-only/free semantics. It stops short of describing return shape (per-agent rows? ordering? limits?), which matters because no output schema carries that information.

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; baseline is 4. The parenthetical metric list is the closest thing to a scope signal and it is consistent with the empty 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?

Specific verb ('Read') plus resource ('verified-facts leaderboards') and the three ranked metrics in parentheses, so the agent knows exactly what it gets. It does not, however, distinguish itself from the sibling commons_get_leaderboard_snapshots, which a reader could easily confuse with it.

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 says to call directly without payment and that the result is display-only, which implies a safe informational read. But it never states when to prefer this over commons_get_leaderboard_snapshots or commons_get_operator_reputation, so selection among the commons siblings is left to inference.

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, and the description adds non-obvious operational context: this endpoint is free with no x402 challenge, so the agent won't waste a step on payment negotiation. It does not explain cardinality or what a snapshot contains, which would be the remaining behavioral gap.

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?

Front-loaded with the purpose in the first clause, followed by payment terms and the HTTP equivalent — a useful one-glance summary. The payment message is restated three ways ('FREE', 'no payment required', 'no x402 challenge', 'this tool is free'), which is mild redundancy but likely a deliberate platform-wide convention.

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, no-output-schema tool, the description is the only place return shape can be conveyed, and it says nothing about what a snapshot includes, how many weeks are available, or the response format. Safe and free-to-call is well covered; the data an agent would receive is not.

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 no parameters and the schema is an empty closed object, so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter tool.

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 ('Read archived weekly leaderboard snapshots'), so the agent knows this returns historical/archived data rather than live standings. It never names the obvious sibling commons_get_leaderboards, so the archived-vs-current distinction must be inferred from the word 'archived'.

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 by 'archived weekly' — the description never says 'use this when you need historical weeks; use commons_get_leaderboards for the current board.' The payment guidance ('call directly without payment') is a clear call instruction but not a when-to-use rule.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context about privacy (receipts are private unless opted in) and payment behavior (free, no x402 challenge), though it does not cover error or not-found 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 core purpose and remains reasonably compact. The payment sentence is somewhat repetitive ('FREE — no payment required... no x402 challenge; this tool is free'), but the overall structure is 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?

For a simple read tool with rich annotations and no output schema, the description covers the returned reputation facts, privacy constraints, and payment model. The main missing piece is the format of the id parameter, which is not addressed.

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?

There is one required parameter, id, with 0% schema description coverage. The description only implies that id identifies an operator via the HTTP path, but does not specify the expected format or type, leaving a meaningful gap.

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: read one public operator profile. It also lists the reputation facts returned, but does not clearly differentiate this from the sibling commons_get_operator_reputation tool, which could create ambiguity.

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 usage for reading a single operator profile and notes that the call is free with no payment challenge. However, it does not explicitly say when to use this tool versus commons_get_operator_reputation or commons_list_operators.

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/closed-world, so the safety profile is covered. The description adds substantive context the annotations cannot: that the read is free with no payment challenge, the exact facts surfaced, and the equivalent HTTP endpoint. It stops short of saying what happens for an unknown operator id.

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 and returned fields are front-loaded, which is good. However the payment point is repeated three times in one sentence ('FREE — no payment required: call directly without payment (no x402 challenge; this tool is free)'), diluting an otherwise tight description.

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 needed work by listing the reputation facts returned and pre-empting the 'where is the score' question. Remaining gaps — id format and not-found behavior — are minor for a single-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?

There is a single required parameter 'id' with 0% schema description coverage, so the schema itself is silent. The HTTP-equivalent URL ('/operators/{id}') implies the id is an operator identifier, which compensates partially, but the expected format (slug, address, numeric id) and lookup failure behavior are left undocumented.

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 ('read an operator's reputation facts from their public profile') and enumerates the concrete fields returned (verified, tenure_days, tier, strikes, proposal rights). It clarifies that no separate score exists, which prevents the agent from hunting for one, but it never names the closest siblings (commons_get_operator, reputation_check) to differentiate scope.

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 give actionable calling guidance — this tool is free, requires no x402 payment, and can be called directly — but that is invocation mechanics, not selection guidance. It never says when to prefer this over commons_get_operator or reputation_check, so the agent must infer the distinction.

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 behavior, so the bar is lower. The description still adds real context beyond them: the archive entry is conditional ('when present'), the response bundles four related sub-resources, and the call is free with no x402 challenge — a meaningful disclosure in an ecosystem where other tools apparently charge.

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?

Front-loaded with the payload description, then the free-call and endpoint notes. Slightly redundant ('FREE — no payment required' followed by 'this tool is free'), but every sentence otherwise carries information useful to the caller.

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 one-parameter read whose safety profile is fully covered by annotations and which has no output schema, the description explains what comes back, the conditional archive entry, and the unusual zero-cost billing behavior. The main residual gap is the expected format/validation of the id.

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?

There is one parameter (id) with 0% schema description coverage, so the description must compensate. The HTTP template GET .../proposals/{id} implies the id is the path-level proposal identifier, but it gives no format (UUID vs slug vs integer) or validity rules, leaving the agent to guess.

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 ('Read one proposal') and enumerates the bundled payload: discussion, tally summary, eligibility snapshot, archive entry. This implicitly distinguishes it from the list-style sibling commons_list_proposals and the granular getters (commons_get_tally, commons_get_archive_entry), though it never names an alternative explicitly.

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 composite payload suggests 'use this when you need the whole proposal view in one call,' but there is no explicit when-to-use vs when to call commons_get_tally or commons_get_archive_entry instead. The FREE/payment guidance is billing information, not tool-selection 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 cover read-only, idempotent, non-destructive, closed-world, so the bar is lower, but the description adds real context beyond them: visibility is restricted to opted-in operators, receipts are private by default, and an empty list is a legitimate outcome. It also removes payment ambiguity by stating the call is free and requires no x402 challenge — unusual and valuable operational detail.

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 the empty-list caveat follows in logical order. The payment sentence is somewhat redundant, saying "FREE — no payment required", "call directly without payment", and "this tool is free" in one breath, which is more repetition than the point needs.

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 tool with full annotation coverage and no output schema, the description covers purpose, visibility scope, empty-result meaning, and cost model. The one gap is that it never says what a receipt record actually contains, which an agent must guess since no output schema exists.

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 the description correctly says nothing about inputs, which is the right baseline of 4. The only input-adjacent information is that settlement scope is fixed to opted-in operators, which is scope rather than parameter semantics.

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+resource ("Read settlement receipts") plus a meaningful scope qualifier ("OPTED-IN operators only"), which an agent can act on. It does not explicitly name a sibling such as commons_set_receipts_opt_in or commons_list_operators, so the routing is inferable rather than spelled out.

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?

"Receipts are private by default; an empty list is an honest answer" usefully tells the agent not to treat an empty result as an error or retry. However, there is no explicit statement of when to prefer this over adjacent commons tools (operator reputation, aggregates, changes) and no prerequisites for opting in beyond the implicit mention.

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 safety (readOnly, idempotent, non-destructive, closed-world), and the description adds real context beyond them: the data is hash-chained and independently recountable, duplicates are surfaced rather than silently dropped, and there is no x402 payment challenge. It omits return shape/pagination, but the honest disclosure of what is included is valuable.

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?

Front-loaded with the useful content, but the payment sentence is redundant — "FREE — no payment required: call directly without payment (no x402 challenge; this tool is free)" says the same thing four times.

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?

No output schema exists, so the description must explain returns; it does by naming the three data components (tally log, recount, rejected ballots). The only gap is the unexplained id parameter semantics.

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?

With one parameter at 0% schema description coverage, the description must carry the load; it partially does by implying via the HTTP equivalent that {id} identifies the proposal. It never states the id format (address, hash, slug) or that it must reference an existing proposal.

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 set: reads a hash-chained tally log, an independent server recount, and rejected/duplicate ballots. It is clearly the audit-detail endpoint versus siblings like commons_get_aggregates or commons_get_proposal, though it never names those siblings to make the contrast explicit.

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 implies usage ("Anyone can recount from this data") and tells the caller payment handling is unnecessary, but it never states when to choose this over commons_get_proposal or commons_get_aggregates, nor any prerequisites such as needing a valid proposal id.

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). The description adds genuinely non-obvious behavior: the tool is free and requires no x402 payment challenge, plus the 100-operator eligibility gate that determines voting_locked. It omits error behavior for unknown proposal ids, so it falls short of 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 returned-field list is front-loaded and useful, but 'FREE — no payment required: call directly without payment (no x402 challenge; this tool is free)' states the same fact three times in one sentence. Tightening that redundancy would cost nothing in clarity.

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 correctly takes on the burden of naming the returned fields and the eligibility rule. For a one-parameter read tool that is nearly complete; only error/not-found behavior is left unstated.

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 0%, so the description must carry the parameter meaning, and it does: the HTTP equivalent 'proposals/{id}/vote-status' makes clear that id is a proposal identifier. That is meaningful added semantics for a single undocumented parameter.

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 (read vote status) and enumerates exactly what is returned: live eligible count, eligible_floor, and the computed voting_locked state. It does not name or contrast with the closest siblings (commons_get_tally, commons_get_proposal), so the agent must infer the boundary itself.

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 threshold rule ('No vote opens below 100 eligible verified operators') implies this is a pre-check before commons_cast_ballot, and the free/no-payment note helps selection. But there is no explicit when-to-use/when-not or a named alternative such as commons_get_tally.

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, so the baseline is covered. The description still adds real value beyond them: the data invariant that can_vote is always false, plus the access detail that no x402 payment challenge is issued — something an agent could otherwise wrongly assume for this API surface.

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?

Front-loaded with the purpose, then two short supporting facts (ballot semantics, free access) and an HTTP equivalent. The shouty 'FREE — no payment required' repeats itself slightly, but every sentence carries operational 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?

For a no-arg read tool with full annotations this covers the essentials, but it never indicates what an agent record contains or whether results are paginated, and there is no output schema to fall back on. Adequate but with a clear gap around return shape.

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; schema coverage is 100% and additionalProperties is false. Baseline 4 applies — no parameter gap exists.

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?

Specific verb+resource: 'List agents tethered to operators', which unambiguously reads as an enumeration of agent records. It doesn't explicitly differentiate itself from sibling list tools like commons_list_operators, but the resource noun makes the distinction clear enough without opening schemas.

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 by the resource ('list agents'), and the zero-parameter schema makes invocation trivial. However, there is no statement of when to prefer this over commons_get_operator or commons_list_operators, nor any exclusions.

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 establish readOnly/idempotent/non-destructive; the description adds genuinely new context: write-once permanence ("nothing is ever deleted or mutated") and the payment model (no x402 challenge, call directly). It omits return shape and whether the list is paginated or bounded.

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 core sentence is well front-loaded, but the payment point is restated five times in one clause ("FREE", "no payment required", "call directly without payment", "no x402 challenge", "this tool is free"). That redundancy costs space without adding 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?

For a no-parameter list tool with full annotation coverage and no output schema, this is close to sufficient, and the HTTP equivalent adds a useful escape hatch. The remaining gap is pagination/result-size expectations, which an agent listing an archive would want to know.

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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly does not invent or imply any filtering arguments.

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: "List the permanent public archive of closed proposals." That distinguishes it from the adjacent commons_list_proposals (active proposals) and commons_get_archive_entry (single entry) by implication, though no sibling is named outright.

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 word "closed" implies this is the counterpart to listing live proposals, and the payment note removes a common hesitation about calling it. But there is no explicit "use X instead when Y" routing to commons_list_proposals or commons_get_archive_entry, so the agent must infer the boundary.

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 context: the tool is free with no x402 payment challenge, plus an HTTP equivalent endpoint — useful for an agent that might otherwise skip it or attempt a payment handshake. Pagination and result-size behavior are not disclosed, keeping it below 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?

Front-loaded with the purpose and the field list, with the payment note and endpoint last. The free-status message is stated three times in one clause ("FREE", "no payment required", "no x402 challenge", "this tool is free"), which is mild redundancy in an otherwise tight description.

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 returns — and it does, naming the five identity fields. Free-of-charge status and the HTTP mirror round it out. Missing pagination/limit behavior is the main residual gap for a list endpoint.

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 the schema is empty with additionalProperties=false, so there is nothing to document. Baseline of 4 applies; the description correctly adds no fake parameter talk.

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 ("List public operator profiles") and enumerates the identity fields returned, so the agent knows the shape of the result before calling. It implicitly separates identity data from reputation data ("Reputation is read via the profile"), but never names the close siblings commons_get_operator or commons_get_operator_reputation, leaving the boundary to be inferred.

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 by the verb "list" — an agent can infer this is the enumeration tool, but there is no explicit when-to-use versus commons_get_operator / commons_get_operator_reputation for a single operator. The only explicit directive concerns payment ("call directly without payment"), not tool selection.

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 establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context not in the annotations: it is free, requires no payment, triggers no x402 challenge, and has a direct HTTP equivalent. It still omits return shape or pagination behavior, so it is not fully comprehensive.

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 core purpose is front-loaded, but the payment note is repetitive: 'FREE', 'no payment required', 'without payment', 'this tool is free'. The HTTP equivalent is useful, but the sentence could be tightened considerably.

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, annotated, read-only list tool with no output schema, the description gives enough context to call it correctly: it lists proposals and is free. It could be more complete by noting whether results are paginated or what a proposal record contains, but those are secondary here.

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, so parameter semantics are not a burden. The baseline for zero-parameter tools is 4, and the description does not need to explain any inputs.

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 uses a specific verb and resource, 'List proposals', and adds scope with '(public record)'. It does not explicitly differentiate from sibling tools such as commons_get_proposal, so it falls 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?

There is no explicit guidance on when to use this tool versus alternatives like commons_get_proposal, commons_create_proposal, or commons_list_archive. Usage is only implied by the verb 'List'.

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?

Goes well beyond the annotations by disclosing the authentication model (Ed25519 signature verified server-side), the default state ('Receipts are private by default'), and the fact that no x402 payment is layered on. It does not spell out the consequence of flipping opt_in to false in terms of what becomes hidden from other readers, so it's not exhaustive against destructiveHint=true.

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?

Front-loads the action and signature recipe, which is good, but the free/no-payment point is made three times ('FREE — no payment required', 'no x402 challenge; this tool is free', 'the MCP layer adds no payment'). That redundancy displaces room for the unresolved `id` parameter.

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 signed mutation with no output schema, the description covers auth, cost, and defaults but leaves gaps: the response shape, failure modes for an invalid signature, and the id/operator_id relationship are all unstated. Adequate to start, not complete for a destructive-flagged write.

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 only 25%, but the description compensates heavily for `signature` by giving the exact canonical string and the literal true/false encoding for opt_in. However, it never explains what `id` is, and the presence of both `id` and `operator_id` (which appear in the same canonical string) is left ambiguous.

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+resource ('Toggle your own receipts visibility') and parenthetically classifies it as an operator-key-signed write, which immediately distinguishes it from the read-side sibling commons_get_receipts. It never names a sibling or explicitly excludes one, 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?

The description conveys the operational context (must be signed, free, no payment challenge, defaults to private) but never says when to use this versus alternatives or when not to use it. The user must infer that this only affects the caller's own operator record.

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?

Adds substantial context the annotations don't carry: the $0.15 per-call cost, the USDC-on-Solana/x402 payment mechanics, and the retry pattern via _meta["x402/payment"]. The readOnlyHint=false and idempotentHint=false make sense given each call charges money, so the 'Fetch'/'GET' wording is not a real contradiction.

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, followed by cost/payment and the HTTP equivalent. It is dense but every sentence carries useful information for an agent that must handle the paywall.

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?

Covers purpose, cost, payment, and endpoint, but with no output schema the description never explains what the returned 'computed financials' actually contain. For a data-retrieval tool with no output schema, that return-value gap keeps it at an adequate-but-incomplete level.

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?

With one parameter at 100% schema coverage, the schema already documents companyNumber fully ('8-character Companies House company number'). The description only references companyNumber in the URL template, adding no new semantics, so the 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?

States a specific verb (Fetch) and resource (computed UK financials from iXBRL filings), which clearly distinguishes it from siblings like companies_enrich_profile, companies_enrich_group, and companies_uk_company. An agent can tell what data this returns without opening the schema.

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 by the resource name (fetch financials for a company), but there is no explicit when-to-use/when-not guidance or routing versus companies_enrich_profile or companies_enrich_group. The payment flow is explained operationally but doesn't tell the agent when to prefer this tool.

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?

Adds substantial behavior beyond the annotations: explicit price ($0.25 per call), payment rail (USDC on Solana via x402), the two-step challenge/retry handshake, and an HTTP fallback URL. The word "Fetch" reads as a pure read, which sits in mild tension with readOnlyHint=false and idempotentHint=false, but paid-call metering plausibly explains that marking rather than contradicting it. It still does not state error behavior for unknown LEIs or whether a company with no group returns an empty tree.

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, front-loaded with what it returns, followed by the payment mechanics. The nested parenthetical is dense but every clause carries operational value (cost, rail, retry protocol, HTTP equivalent); nothing is filler, though it could be split for scanability.

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 is the only place an agent could learn what a "group tree" contains (parent, subsidiaries, consolidation, depth), and it says nothing about that shape or size. For a paid, non-idempotent call where a wasted invocation costs $0.25, omitting what the response looks like and what happens on no-match is a meaningful gap.

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% (the single lei parameter is documented as a 20-character ISO 17442 LEI), so baseline is 3. The description only echoes the parameter via the {lei} path segment and adds no format, normalization, or special-case meaning 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?

Specific verb and resource ("Fetch a company's full GLEIF group tree") with the key domain qualifier GLEIF and the notion of a group/parent-child tree. It does not explicitly contrast itself with near-siblings like companies_enrich_profile, companies_enrich_financials, or companies_uk_ownership, so the agent must infer the distinction from names alone.

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 gives procedural guidance for how to invoke it (call unpaid to receive the PaymentRequired challenge, then retry with the payment at _meta["x402/payment"]), which is genuinely actionable. However, it gives no guidance on when to prefer this tool over its siblings or what input preconditions matter (e.g., needing a canonical LEI, or pointing to companies_enrich_resolve first).

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?

Goes well beyond the annotations by disclosing the $0.10 per-call price, the USDC-on-Solana/x402 payment mechanism, the exact retry protocol (call unpaid, read the PaymentRequired challenge, retry with _meta["x402/payment"]), and the HTTP equivalent URL. That is the kind of auth/cost context annotations cannot express; the only gap is that it does not say whether a failed paid call is charged.

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 first sentence, with cost and payment mechanics following. The x402 parenthetical is dense but each clause is operationally necessary; no filler sentences.

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, yet the description never indicates what an "enriched cross-registry profile" actually returns or how large/complete the payload is. Payment and endpoint details are thorough, but for a data-retrieval tool the agent is left guessing at the response shape.

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 accepted identifier formats (LEI 20 chars, FR SIREN 9 digits, UK company number 8 chars) are already fully documented in the schema. The description adds nothing about the id parameter, which is acceptable given the baseline but earns no bonus.

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 ("Fetch an enriched cross-registry company profile") and the word "cross-registry" implicitly separates it from single-registry siblings like companies_uk_company or companies_uk_lei. It does not explicitly name the sibling it replaces, so an agent must infer the boundary against companies_enrich_resolve and companies_enrich_group.

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 explains the payment procedure in detail but never says when to choose this tool over companies_enrich_group, companies_enrich_financials, or companies_enrich_resolve. Usage is implied by the resource name rather than stated as a selection rule.

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?

No annotation covers cost or payment, and the description supplies that fully: $0.05 per call, USDC on Solana via x402, the no-payment-then-retry challenge handshake, and the exact _meta key. This is exactly the kind of context annotations can't express. It doesn't describe the response payload or failure modes, keeping it below 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?

Three tight sentences: capability first, then pricing and the retry protocol, then the HTTP equivalent. The payment handshake detail is essential given it is non-obvious and otherwise undiscoverable. Slightly dense with embedded nested quotes, but no wasted words.

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 is the only place an agent could learn what "resolve" returns — a canonical entity, matched register, confidence, or nothing found. That omission matters for a cross-register resolver, and openWorldHint combined with readOnlyHint=false leaves the read/write character ambiguous.

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 each of the five identifier parameters documents its format and the 'provide exactly one' constraint in the schema itself. The description adds nothing about parameters, 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?

"Resolve a company across UK, FR and AU registers" gives a specific verb (resolve) plus resource (company) and jurisdictional scope, which distinguishes it from lookup-style siblings like companies_uk_search or companies_enrich_financials. It stops short of explicitly naming which sibling to use instead for adjacent tasks (search, profile, ownership).

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 explains the payment mechanics but never says when to choose this over companies_uk_search, companies_enrich_profile, or companies_uk_lei, nor what preconditions exist (e.g. one identifier required). An agent must infer selection from the name alone.

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?

Goes well past the annotations by disclosing the $0.05 price, the USDC-on-Solana x402 payment mechanism, and the exact retry protocol (call unpaid to receive the PaymentRequired challenge, then retry with _meta["x402/payment"]). That is genuinely actionable behavior an agent cannot infer. It stops short of saying what 'full snapshot' contains or what a rejected/expired payment looks like.

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 one-line purpose before the payment mechanics. Every clause earns its place because the x402/payment retry procedure is non-obvious and required to invoke the tool successfully.

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 is the only place an agent could learn what the 'full snapshot' returns, and it says nothing about the fields, size, or shape of the response. Payment mechanics are covered well; the payload is a gap.

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 the single parameter is documented as an '8-character Companies House company number', so the schema carries the load. The description only restates the identifier and echoes it in the HTTP path template; it adds no format or validation detail 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?

States a specific verb and resource: 'Fetch a full UK company snapshot by company number'. This cleanly separates it from lookup-style siblings (companies_uk_search) and adjacent enrichment tools (companies_uk_lei, companies_uk_ownership), though it never names those alternatives explicitly.

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 identifier type ('by company number') implies when to reach for it, but there is no explicit when-to-use/when-not guidance and no routing against companies_uk_search or companies_uk_ownership, which an agent would plausibly confuse with this.

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?

Adds substantial context beyond the annotations: exact pricing ($0.05/call), payment rail (USDC on Solana via x402), the required two-step challenge/retry handshake with the _meta["x402/payment"] field, and the equivalent HTTP endpoint. Payment and auth requirements are precisely the behavioral details the annotations cannot convey.

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?

Three sentences, front-loaded with the core purpose, then the commercial/transport details. Every sentence carries operational weight, though the x402 parenthetical is dense and could be tightened.

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 could have hinted at what a 'normalized record' contains (fields, coverage). It covers invocation and payment completely but leaves the return shape entirely opaque for an agent that must decide whether the result is usable.

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 single parameter is already documented as a '20-character ISO 17442 LEI'. The description only restates 'by LEI code', adding no format, validation, or lookup-behavior detail 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?

States a specific verb and resource: 'Fetch a normalized GLEIF LEI record by LEI code.' The 'GLEIF LEI' qualifier distinguishes it from siblings like companies_uk_company, companies_uk_ownership, and companies_uk_search, though it never names them explicitly.

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 gives procedural guidance on how to invoke it (call once to receive the PaymentRequired challenge, then retry with payment), which is useful for the x402 flow. However, it offers no guidance on when to choose this over the sibling company tools that also take UK company identifiers.

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 the safety profile, while the description adds critical paid-call behavior: $0.25 per call, USDC on Solana, the x402 PaymentRequired challenge flow, the _meta["x402/payment"] retry key, and an HTTP equivalent. It lacks return-format details, but the payment mechanics are unusually well disclosed.

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?

Three sentences, front-loaded with the purpose; the remaining sentences are dense but necessary invocation details for a paid x402 endpoint. 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 there is no output schema, the description does not explain what the ownership chain returns, such as PSC entries, corporate entities, or error cases. Purpose and payment are covered, but output-shape uncertainty remains for a data-retrieval 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 the single companyNumber parameter is already documented as an 8-character Companies House number. The description only repeats it inside the HTTP path, adding no new semantics 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?

States a specific action ('Walk the PSC ownership chain') and target ('for a UK company'). The resource is distinct from sibling tools like companies_uk_company, companies_uk_search, and companies_uk_lei, so an agent can select it without opening schemas.

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 explicit when-to-use guidance, prerequisite explanation, or comparison to sibling company tools. The purpose implies the use case, but it does not route the agent among alternatives.

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