ASPERN: counterparty checks for agents

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

Beyond the annotations, the description discloses a lot of non-obvious behavior: results are six separate answers with deliberately no aggregate score, the `limits` field carries four explicit refusal caveats, and `economicChain` reports four links tagged `evidenced`/`unevidenced`/`unread`/`unevidenceable` with worst-link governance. The x402 case (delivery link is unevidenceable) is a concrete, useful edge-case disclosure. The 'PAID' marker is consistent with readOnlyHint=false rather than contradicting 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, but the body is padded with rhetorical asides and heavy all-caps emphasis ('THERE IS NO SCORE', 'DEMONSTRATED'). The substance about `limits` and `economicChain` earns its place; the anti-scoring manifesto is repeated twice and could be compressed.

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?

An output schema exists, yet the description still usefully explains the shape of the answer (six independent questions, no score, `limits`, `economicChain` status vocabulary), which is what an agent needs to interpret results. The one real omission is routing guidance relative to the many sibling evidence 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?

There is a single required parameter at 100% schema coverage, so the schema already documents `address`. The description adds nothing about the address — no format, chain scoping, or whether an address can be a contract versus an EOA — so baseline 3 applies.

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

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

The description states a specific assessment target: whether an agent has a demonstrable business, broken into six named sub-questions (independence of payers, revenue trend, repeat custom, delivery evidence, cost, multi-address linkage). That is far more specific than the title alone. It never names a sibling, though, so the boundary against the very similar `agent_economic_profile` is left to the agent to infer.

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 describes who cares about the answer ('an investor, a marketplace or an operator') but never says when to call this tool versus `agent_economic_profile`, `counterparty_history`, or `payment_evidence`. There are no preconditions, exclusions, or alternative-routing statements — the agent must guess which of the many evidence tools to reach for.

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 open-world, so the description earns no credit for safety there. It does add genuinely non-obvious behavior: one row per field per agent, absent row means no movement rather than no coverage, data begins at a record start date, and a key plus the agents.changes capability is required. That auth/capability note is the strongest contribution, but nothing is said about output shape beyond what the output schema carries.

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 body carries aphoristic padding such as 'the question anybody holding a list asks next' and 'rather than pretending nothing happened.' Those sentences cost length without adding callable guidance, though the row-granularity and truncation facts do earn their place.

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

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

With an output schema present, the description needn't explain return values, and it correctly spends its words on semantics the schema can't carry: field-level row granularity, absent-row interpretation, historical start boundary and auth requirements. A brief note on typical volume or ordering would close the remaining 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%, so every parameter is already documented, including the capped/pagination pattern and the default date window. The description adds no format or default detail beyond the schema and instead explains `from`, which is an output field rather than a 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?

The opening sentence states a specific verb and resource: what moved in the agent record, across all agents, since a date. It also explicitly distinguishes itself from counterparty_check (current state of one address vs. change history for all). The phrase 'agent record' is slightly oblique about what an agent is, but the row-granularity sentence clarifies the answer shape.

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 (counterparty_check) and the condition that selects it: point-in-time truth for one address versus change history across the list. It also states that the `address` case exists for narrowing to one holder. What is missing is guidance on narrowing by other dimensions or on when this tool is the wrong choice entirely.

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: it discloses the four gating tests, that failures are downgraded to 'shared-counterparty' with the failed test named and reported as a LEAD, that the concentration line counts dependencies only, and that the result is a FLOOR on real concentration, never a measure. It also explains the otherwise puzzling readOnlyHint=false by stating 'PAID.'

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 body is a dense wall of prose with capitalized emphasis and a rhetorical 71-agents-vs-3-agents illustration that could be compressed. Every sentence is informative, yet the payload is oversized for a one-parameter tool and hurts quick 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 analytics call with an output schema, the description supplies everything an agent needs to decide and to interpret: eligibility rule, the four tests published per party under `tests`, LEAD vs dependency reporting, and the important scope caveat that most shared infrastructure produces no payment at all.

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 already carries its own rationale (min 2, max 25 and why). The description only restates 'two to twenty-five addresses', adding no new format or syntax guidance, so the baseline of 3 is right.

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: given 2-25 addresses it finds the parties more than one of them pays. The opening line plus 'THE PRODUCT IS THE DISTINCTION, NOT THE JOIN' makes the output semantics sharper than a generic join, and it is clearly separable from counterparty_check and counterparty_bulk.

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 when-to-use ('If your firm relies on several external agents') and explicit exclusions: single-payer parties are routed to 'counterparty_check, free', and infrastructure with no payment is called out as invisible to this tool. The four tests (repeated, one-way, sustained, shared) define inclusion precisely.

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: it is PAID, based on a nightly record, returns NULL rather than zeros for unread blocks, and exposes blocksAnswered and cannotSee limitations. It does not explain the payment mechanics or why readOnlyHint=false, which is a meaningful omission for a paid tool.

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 four readings are front-loaded effectively, but the description spends multiple sentences on philosophical justification for not having a score. That argument could be compressed to a short sentence without losing actionable meaning.

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

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

An output schema exists, so return values need not be explained, and the description usefully clarifies NULL semantics, blocksAnswered, and cannotSee. It stops short of explaining cost, billing, or freshness beyond 'nightly record', which matters for a paid 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 schema has 100% description coverage and already documents that the address can be EVM or Cardano and resolves to the record key. The description adds no additional parameter semantics, 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 exactly what the tool returns: one agent's four readings — earnings, completed contracted work, supplier dependencies, and trading/endpoint status. It explicitly distinguishes itself from siblings that answer those questions singly, so an agent can tell why this composite exists.

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?

Makes clear this is the aggregate view over the same nightly record, while the individual questions are available elsewhere on the server. It implies when to prefer the composite but does not name the specific sibling tools or state explicit exclusions for when to use them instead.

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 the description adds real context beyond them: it is free, it is a statement about the service's own limits, and it makes no quality judgement. It does not describe response shape, but the output schema covers that.

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 front-loaded with the key instruction, but the body is rambling and repetitive ('It says what we CAN read and never whether a vault is any good' restates earlier points), and the closing enumeration of nine columns is largely tangential for a no-argument metric 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?

For a no-param read tool with a full output schema and safety annotations, the description supplies the missing framing (what the numbers mean, that they are two distinct counts, that this is not a quality verdict). Return values need not be described given the 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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify or compensate 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?

It states a specific resource — the coverage of each vault reading, counted two ways (open-vault count and capital) — and explicitly separates itself from the paid screen that lists which vaults are missing. That is enough to tell it apart from list_vaults/find_vaults, 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?

The opening imperative ('BEFORE YOU TRUST ANY COVERAGE FIGURE FROM US, ask this') gives a clear when-to-use trigger, and it states a when-not ('never whether a vault is any good'; the missing-vaults screen is a different, paid tool). No alternative tool is named, so it falls 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 behavior beyond annotations: paid, cross-comparison logic, the `between` field naming disagreeing readings, asymmetrical verdict impact ('can only make the verdict worse'), simulation semantics, revert interpretation, node refusal handling, and `ran` reporting for skipped checks. These details materially change how an agent interprets results.

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

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

Front-loads the call-to-action and key value proposition, and most sentences carry useful operational nuance. It is dense and somewhat rhetorical, with all-caps emphasis and long sentences, but not padded with irrelevant material.

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

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

Given the complexity, high schema coverage, and presence of an output schema, the description provides enough context: what it aggregates, when to invoke it, what simulation does, how failures and gaps are represented, and why it is paid. Nothing critical for correct invocation appears 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 combination-level meaning: calldata unlocks the strongest check, and calldata + chain + from enables simulation. It also reinforces that missing calldata means UNREAD rather than fine, which is more than the individual schema fields convey.

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 and scope: a pre-signing composite check that reads five sources and compares them. It clearly distinguishes itself as an aggregate ('one request instead of five') whose sold value is the comparison, though it does not name sibling alternatives 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?

Strong usage trigger: 'CALL THIS BEFORE YOUR AGENT SIGNS ANYTHING THAT MOVES MONEY.' It also tells the agent to send calldata whenever available and specifies that calldata, chain, and from together enable simulation. It lacks explicit when-not-to-use guidance or named alternatives among the many sibling tools.

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

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

Annotations already declare the safe, idempotent, open-world read profile, so safety isn't the burden here. The description adds genuinely non-structured traits: the call is free, it distinguishes declared vs observed vs reading layers, and it warns against over-reading a single `latest` value. Much of the remaining prose is output interpretation that the output schema likely already carries.

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 opening sentence is well front-loaded, but the body runs several hundred words for a one-parameter read tool, with repeated emphases ("never merges them," "never folded into one number," "separate fields") and field-by-field exposition that belongs in the output schema. Several sentences do not earn their place in a tool-selection document.

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?

An output schema exists, so return values need not be explained, yet the description still covers semantics, caveats, and the drift/freshness interpretation an agent needs before calling. Nothing essential is missing; the issue is excess rather than incompleteness.

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 exactly one parameter with 100% schema description coverage, so the baseline is 3. The description restates that it takes the http(s) URL of the endpoint but adds no format, constraint, or edge-case detail beyond the schema's own wording.

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: give it an http(s) URL of an MCP or A2A endpoint and it reports who declares it, whether the probe reached it, what it answered, and how many readings responded. That is a real, distinguishable purpose. It never names a sibling tool, so it lacks the explicit differentiation a 5 requires.

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?

"Call this before connecting to a service" gives a clear trigger condition, and it adds exclusion-style guidance: unreachable is an availability fact, not bad faith, and unprobed endpoints are outside the reading. It also routes one case (catalogued x402 resources with no registered agent) to reading `unpaidProbe`. No alternative tool is ever named, 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?

Annotations declare readOnlyHint=false, and the description explains precisely why: an x402 authorisation moves USDC and records a receipt, while a call without one changes nothing. It further discloses the 400 'too_many' refusal instead of silent truncation, the capability-gated 'shared' block on Analyst+, and what an empty list means. This 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 the purpose, then the differentiator, then pricing, then the readOnlyHint rationale. Every paragraph carries information, though the 'four agents stopping together' illustration and the closing receipt warning are somewhat verbose for what they add.

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?

An output schema exists, so return shape needn't be explained. The description still covers pricing model, capability gating, error behavior, interpretation caveats, and the safety rationale — everything an agent needs to decide whether and how to call it.

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's constraints (1-50, mixed address forms, refusal at 51, one row per address in input order) are already written verbatim in the schema. The description restates the same limit and refusal behavior, adding little 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 and resource ('Check up to fifty addresses in one call') and immediately specifies the two outputs: per-address observations plus the set-level 'shared' block. It explicitly carves out what a per-address row cannot contain, which differentiates it from counterparty_check without needing to open either 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 clear when-to-use context: when the input is your own shortlist and you want the shared-payee intersection across it. It also explains the two payment paths and the capability gate. It stops short of explicitly naming counterparty_check as the single-address alternative, so the routing is implied rather than spelled out.

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, so the description wisely spends its words on interpretation instead: it states the cost (free) and warns that `independence` means no payment back rather than proof of distinct owners, that an all-time record does not prove the agent still operates (44% unpaid in 90 days), and that `restsOn.suppliers` of zero is not proof of no dependency. That is exactly the kind of caveat no annotation or schema can 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?

Purpose is front-loaded and every sentence carries information, but the middle is a dense semicolon-chained run-on with capitalized emphasis (WHETHER…, WHAT IT ITSELF RESTS ON) that is hard to parse. The three limits are valuable yet would read far better as a short list than as one sprawling 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?

For a rich read-only inspection tool with an output schema and full annotation coverage, the description supplies the missing pieces — the set of chains accepted, the meaning of the non-obvious fields, and the misreading traps. An agent can call it and correctly interpret the result without further help.

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 required parameter is documented, so the baseline is met; the description goes beyond it by naming the accepted address families (EVM, Cardano addr1…, Solana), which the schema does not say. It does not specify validation or error behavior for a malformed address.

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

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

The title and first sentence agree: it reports what the chain records about a single address, and the body enumerates the concrete sub-results (independent payers, payback behavior, concentration, independence, restsOn, ACP job outcomes, endpoint liveness, last payment). That is far more specific than a generic 'check address', though it never names the nearest siblings (counterparty_history, counterparty_bulk, preflight_payment) to draw a boundary.

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 paying or hiring an agent' gives a clear decision point that selects this tool. It stops short of exclusions or alternatives — nothing says when to use counterparty_bulk for many addresses or counterparty_history for a time series, and 'Free' is the only stated constraint.

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 explicitly justifying readOnlyHint=false: the call transfers USDC via x402 and writes a receipt, so it is not consequence-free, while an unauthorised call changes nothing and returns only the price. This is exactly the kind of side-effect disclosure annotations 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-loads the resource and its dimensions before the payment terms. The payment rationale is somewhat verbose and repeats the 'record we keep, not one the chain gives away' idea already implied in the days parameter note, but the length is defensible 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 an output schema present, return format need not be described. The description covers pricing, payment mechanics, failure behaviour without payment, the temporal limit of the data, and the safety profile — everything an agent needs to decide and invoke 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 both parameters are already documented in the schema, including the default and the 1-365 range. The description reinforces the 'history starts when we began keeping it' caveat, which is useful but largely restates the schema note.

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 ('one agent's record') and enumerates exactly what it returns: dealings, independent payers, concentration, delivery, day by day. The scoping word 'one agent' cleanly separates it from the bulk siblings (counterparty_bulk, find_agents).

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?

Explains the payment prerequisite, that an unpaid call returns the price instead of data, and points to the durable 'free check' alternative. It also warns the agent not to call speculatively. It stops short of naming the specific sibling tool (counterparty_check) the free check corresponds to.

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, open-world, idempotent, non-destructive behavior, and the description adds substantial context beyond that: state meanings, why states are not summed, the two separate denominators, fault semantics, deadline and notAsked behavior, and three-knock publication for x402 resources. This is unusually rich behavioral disclosure with no 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?

The description is front-loaded and structured around the right warning, but it is very long and rhetorical for a zero-parameter tool. Sentences such as 'The second number is the uncomfortable one...' and the closing 'Free, because...' add manifesto tone rather than invocation-critical detail.

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

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

Given the tool's complexity and the presence of an output schema, the description provides enough contextual caveats to interpret coverage correctly: denominators are separate, only fault states count as failure, and x402 reach is not a seller judgement. Nothing essential for correct use appears 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?

The tool takes zero parameters, so the baseline is 4. The description correctly does not waste space documenting parameters and instead explains the coverage 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?

The description clearly establishes that this tool reports endpoint coverage rather than uptime, and it explains the two populations being covered. However, it does not explicitly contrast itself with sibling tools such as check_service_endpoint or knock_on_endpoint, 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?

The opening line gives a clear usage condition: ask this before treating any endpoint as reliable. It does not name when not to use it or which sibling tool to use instead for direct endpoint probing, so it stops short of explicit 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?

The description adds substantial behavior beyond annotations: `items` returns NULL without a plan rather than an empty list, counts are free but the list is paid, and the measurement scope is limited to endpoints that were actually contacted. It also clarifies that a disagreement is not fraud evidence and explains the `comparable` denominator, which is exactly the kind of context an agent needs before calling.

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 definition is front-loaded, and most sentences carry useful scope or paywall information. However, the description is verbose and stylistically dramatic, with philosophical asides that could be compressed for faster agent parsing.

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

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

Given the rich annotations and output schema, the description is complete enough: it covers the measurement scope, plan-gating behavior, NULL return semantics, and alternatives for single-endpoint checks. No critical invocation detail 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% and the only parameter, `limit`, is fully described in the schema with its default and cap. The description adds no further detail about `limit`, so the baseline score of 3 is appropriate when the schema carries 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?

The description clearly defines the tool as identifying endpoints whose live handshake payee differs from their published catalogue listing. It distinguishes the concept from related tools by naming `test_purchase` and `list_x402_endpoints` as alternatives for single-endpoint readings, though it never states the operation as a crisp 'list' verb.

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 explains that counts are free while the list requires a plan, and that any single endpoint can be checked through `test_purchase` or `list_x402_endpoints` instead. This gives clear guidance on when to use the bulk list versus single-endpoint alternatives, though it does not explicitly frame all sibling-routing conditions.

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 readOnlyHint already declaring this is a safe read, the description goes well beyond: it defines all four outcome values, warns that `allow` is not a safety endorsement, explains that `abstain` is a gap rather than approval, and notes amount-dependence so the same address can differ by order size. That is exactly the decision-interpretation context annotations 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?

The usage trigger is front-loaded and the decision glossary is useful, but the prose is dense and backtick-heavy, with parenthetical asides and rhetorical framing ('inventing one would be worse than declining') that inflate length without adding callable 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 read-only evaluator with an output schema and 7 parameters, the description covers what it returns (four verdicts plus reasons/detail), how to read a failed rule, and the conservative-policy behavior on risk bands — nothing an agent needs to interpret a verdict 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 the baseline is 3, but the description adds real meaning: `amountUsd` omitted makes amount rules report as not-run rather than pass, and `requiredChecks` can only make the answer more conservative and unknown ids surface in `required.unknownIds`. Those behavioral consequences are not restated in 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 concrete verb and resource — weigh one prospective action against a named policy and return a decision — and enumerates the four action types (pay, connect_mcp, call_tool, allocate_capital). This is clearly separable from sibling read tools like list_policies or check_action.

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 an explicit trigger ('call this when you are about to DO something') and names the situations that qualify. It doesn't explicitly say when to prefer check_action or preflight_payment over this tool, so routing among the many sibling tools is left partly 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 openWorldHint, idempotentHint and non-destructive; the description adds substantial context beyond them — deterministic/no-model judging, $2 x402 pricing, no charge on out_of_coverage, free dryRun and sample vaults, and citation format dd:<digest>#<pointer>. However it never reconciles readOnlyHint=false with what actually changes server-side (payment, judgement record), and rate/plan-limit behaviour is only implied.

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 triggering condition, then verdict semantics, then pricing — a sensible order with no filler. It is dense and long, leaning on capitalized emphasis (MANDATE, CLAIMS, DIRECTION), which costs readability but each clause still carries 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 paid, deterministic, nested-object tool, the description covers what the agent needs: when to call, what is charged, what the verdict values mean, how findings are cited and verifiable, and how requiredNextSteps guide remediation. With an output schema present, no further return-value prose is owed.

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 earns above baseline by explaining the semantic role of mandate and claims — claims are checked against the snapshot, and a claim asserting as known what the snapshot records as unread produces insufficient_evidence. It also ties the vault parameter to list_vaults/find_vaults for slug resolution.

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: it judges a proposed vault capital decision against a stored due-diligence snapshot and returns a verdict. The verdict taxonomy makes the output shape concrete. It does not, however, distinguish itself from adjacent siblings such as vault_check, vault_assessment, check_action or evaluate_action, so an agent must infer which judgment tool to pick.

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 clear triggering condition ('call this before an agent moves capital into or out of a vault') and explains free paths (dryRun, sample vaults) versus the paid path. It stops short of naming alternative siblings or stating when a different tool (e.g. vault_assessment) is the better choice.

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 substantial context beyond them: the three edge kinds and the explicit rule that they are NEVER summed, the fact that it infers NO identity (a shared host is reported as exactly that), the `lookedForAndMissing` field so thin subjects aren't misread as complete, and a cost note ('Free'). This is rich behavioral disclosure well past the annotation bar.

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 tightly written, with each sentence carrying a distinct rule (edge kinds, no summing, no identity inference, missing data). It is somewhat long for a one-parameter tool and part of the edge-field enumeration may duplicate what the output schema already renders.

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 rich annotations, an output schema, and a single string parameter, the description supplies everything an agent needs: what the result contains, how to interpret it, what it must not do (sum edges, infer identity), and what the cost is. No material gap remains.

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 fully documented ('An address, or the http(s) URL of an endpoint'). The description adds no syntax or format detail beyond the schema, so the baseline 3 applies; it adds meaning only indirectly ('a thin subject never reads as a complete picture').

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: 'Everything we hold about one subject, as edges, each carrying where it came from.' It also positions itself against decision-making tools ('explain a decision rather than just make one') and repudiates a sibling concept (the reputation score it replaces), so an agent can tell it apart from check_action-style 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?

Gives explicit conditions: use it to explain a decision rather than make one, or to see what is MISSING before you act. There are no named alternatives or hard exclusions among the 30 siblings, but the usage context is concrete rather than 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?

The description discloses critical behavioral limits beyond the annotations: the fourth phase cannot be read, a zero there would be misleading, and the four per-phase states are carefully distinguished. It explains why `exempt` and `subjectRefuses` are not the same as `unread`, which is exactly the kind of nuance an agent needs before interpreting the result.

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 and every sentence contributes semantic content about phases and states. However, the heavy use of all-caps emphasis and dense long sentences makes it less scannable than it could 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?

Given zero parameters, an output schema, and rich annotations, the description supplies the remaining conceptual scaffolding: four phases, three readable, four possible states per phase, and no single aggregate percentage. Nothing essential is missing for correct interpretation.

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 there is nothing for the description to clarify at the parameter level. The baseline score of 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?

The description states a specific verb and resource: measuring how much of the exit lifecycle is visible, phase by phase, across every open vault. This is clearly distinct from listing actual exits, but it does not name a sibling tool to sharpen the boundary.

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, no mention of alternatives such as vault_exit_confidence or vault_exits, and no exclusion conditions. The only contextual cue is a note that the tool is free, which speaks to cost rather than invocation context.

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

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

With annotations present (openWorldHint=true, idempotentHint=true, destructiveHint=false), the description still adds real context beyond them: that results are historical flow rather than level, that "never-asked-this-size" is neither a refusal nor a failure, that unread vaults are counted separately as population, and that nothing is a forecast. It does not explain cost/billing mechanics behind the "(paid)" label or rate limits, which keeps it out of the top band. Note the mild tension between the plainly read-only framing and readOnlyHint=false, but no explicit 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?

It is well front-loaded — the trigger condition leads — but it is heavily overwritten for a two-parameter tool: all-caps rhetorical emphasis, the "LEVEL vs FLOW" aside, and the auditor anecdote consume space that a tighter statement of the three verdicts would cover. The anecdote and the verdict definitions do earn their place; the emphatic repetition does not.

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

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

For a screen with an output schema and full schema coverage, the description supplies everything an agent additionally needs: the meaning of each verdict, the caveat that absence of history is untested rather than safe, the population counter, and the historical-not-predictive framing. Nothing required to call or interpret it correctly 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%, so the schema already documents amountUsd (including the 6000000 example and why it is required) and the limit/count relationship. The description reinforces the meaning of amountUsd but adds no syntax, format, or edge-case guidance beyond the schema, so baseline 3 applies; `limit` is not touched on in the description 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?

The description states a concrete job — screen every vault that has withdrawal history for whether a withdrawal of the given size has actually cleared — and explicitly contrasts it with siblings: "Every other exit reading here is about one vault; this asks the same question across every vault" (i.e. vault_exits / vault_exit_confidence). The three verdict tokens pin down exactly what the tool returns, so an agent can distinguish it from neighboring exit tools without opening a 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?

It gives a clear triggering condition ("YOU HAVE A SIZE AND YOU WANT TO KNOW WHERE IT HAS ACTUALLY CLEARED") and implicitly positions itself against the single-vault exit readings. However, it never names the alternative tools an agent should use for a single vault or for a forecast-style check, so the routing guidance stays inferential rather than explicit.

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/open-world/idempotent safety, but the description adds substantive behavior: free access, independent payment evidence across named rails, no inference from zero, no reading of self-description, and explicit subject confidence labels including 'unknown' as a real answer. This adds rich context without contradicting 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?

Given 23 parameters and non-obvious evidence semantics, most of the length is justified and the purpose/scope is front-loaded. However, the dense all-caps caveats and long second paragraph make it less scannable than ideal.

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 complex 23-parameter, output-schema-backed search tool, the description supplies the needed conceptual model: rails read, positive evidence rule, subject labels, and filtering pitfalls. With annotations and output schema present, no critical invocation context 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% and the schema itself describes every filter in detail, so the baseline is 3. The description adds cross-cutting filter caveats—positive evidence vs absence, no self-description, api-service unreachable, and subject/evidence semantics—that help interpret the 23 parameters, though it does not document individual parameters 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 opening sentence names a specific verb and resource ('Find agents to hire') and immediately states the distinguishing evidence basis: chain records rather than claims. It also scopes the rails covered and defines row labels, so an agent can distinguish this from generic agent discovery.

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 strong filtering context, including 'READ THIS BEFORE FILTERING', the unreachable api-service label, and the caveat that absence means never paid rather than never worked. It does not explicitly name a sibling alternative or say when another tool should be chosen, so it falls 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?

Annotations already establish this as a safe, read-only, idempotent, open-world read. The description adds meaningful behavioral context beyond annotations: the call is free, the `earned` filter only matches comparable advertised/realised returns, venues with no quote or static share price are excluded, and a short list means few comparable cases rather than few performers.

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 and the caveats are relevant, but the description is noticeably wordy and repeats the same idea several times, such as counts being in the answer rather than here. For a 10-parameter tool with full schema coverage, some of the emphasis could be tightened without losing meaning.

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

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

Given the rich schema, annotations, and output schema, the description supplies the additional context an agent needs: the tool's performance-based discovery purpose, the meaning and limits of the `earned` filter, and the handoff to `vault_check` for detail. Return-value details and other parameters are appropriately left to the structured fields.

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 schema itself documents all ten parameters. The description nonetheless adds substantive meaning for the key `earned` parameter by explaining `short` and `beating` and the comparability/exclusion rules, though it does not add semantics for the other parameters.

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

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

The description states a specific verb and resource, and crucially distinguishes the tool from name-based discovery: it finds a vault by what it has DONE rather than what it is called. It also names the `earned` filter as the key mechanism, which lets an agent understand its distinct purpose relative to generic vault listing.

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 clear usage context for the `earned` filter, including what `short` and `beating` return, and directs the agent to `vault_check` on a slug for the full answer. It does not explicitly compare `find_vaults` to the sibling `list_vaults`, so the alternative-selection guidance is slightly incomplete.

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/openWorld/idempotent/non-destructive, and the description adds genuinely new behavior: it never disambiguates (address returns null with all candidates), hostname/endpoint links are the subject's own claim and not proof of control, unresolvable identifiers are not evidence of wrongdoing, and `says` distinguishes unknown subjects from unsupported chains. This is rich disclosure far beyond the structured 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?

Front-loaded with the call-first directive, then the identifier types, then the failure semantics. Dense and every sentence carries information, though the run-on sentence about candidates and the self-claim/evidence distinction 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?

An output schema exists, so return shapes need not be re-explained, and the description still covers the non-obvious output behavior (null address, candidate list, `says` field) that an agent needs to interpret results. Nothing material is missing for a single-parameter resolver.

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's own description of `q` already enumerates the accepted input forms, so the description's restatement of transaction hash / URL / hostname / registration number adds little. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('says which party that is') and precisely enumerates the accepted identifier types alongside a wallet address. It positions itself against siblings by declaring it is the entry point whose output feeds 'the other tools here', so an agent knows this is the resolving step, not the analysis step.

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?

'Call this FIRST whenever you hold something other than a wallet address' gives an explicit trigger condition and an implicit exclusion (already holding an address). It does not name a specific competing sibling, but the input-type routing rule largely obviates the need.

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 are thin (readOnlyHint false, openWorldHint true, not idempotent, not destructive), and the description carries the real weight: it discloses the three-call selector whitelist, that it refuses rather than guesses on unknown ABI, that amounts are atomic units, that it stores nothing and needs no key, and a rate limit of one live handshake per minute per resource. That is exactly the context 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 with the imperative and the alternative-check contrast, and nearly every clause carries information (selectors supported, refusal policy, atomic units, no storage). It is denser and more rhetorically styled than needed, which slows scanning, but there is no filler to cut.

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 six-parameter, nested-object tool with an output schema, the description covers the behavioral envelope an agent needs — refusal on unknown calldata, what expect omission means, quote-freshness semantics, live-refresh limits. What it does not say is what the answer looks like when called with nothing at all, a minor gap given the output schema handles 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?

Schema coverage is 100% and the nested expect/resource/freshness semantics are already spelled out in the schema descriptions, so the description is mostly restating. It does reinforce that calldata is mandatory in practice and that atomic units are not dollars, but adds little beyond the schema. Baseline 3 is right.

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 object — read the calldata you are about to sign and check it against what you believe you are doing — and explicitly contrasts that with what the sibling checks do ('every other check here asks whether an address is worth dealing with'). An agent can place it against preflight_payment and counterparty_check 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 the trigger ('before you sign it'), the exclusion (no amount of reputation substitutes for matching bytes), and the tool's own refusal boundary — it reads only transferWithAuthorization, approve and transfer and refuses any other calldata. It even sketches when the optional refreshQuote path applies and its rate limit.

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 substantial safety-critical behavior beyond the annotations: it never holds keys, a served answer means seller acceptance rather than settlement, a 402 after payment is reported as `rejected`, and re-signing with a fresh nonce can cause a second payment. It also discloses rate limits, catalogue-only targeting, and that seller answers are not stored.

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 first sentence is front-loaded and clear, but the body is a long, dense, all-caps block with meta commentary and repeated warnings. Much of the content is useful for a payment-bearing tool, but the formatting and verbosity make it harder to parse than 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?

Given the output schema and the annotations, the description covers the remaining behavioral and usage context an agent needs: payment semantics, settlement caveats, rate limits, catalogue restrictions, and read-vs-pay modes. Nothing essential for correct invocation appears to be 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%, so the schema already documents all six parameters thoroughly. The description reinforces key usage patterns such as omitting `payment` to read terms and sending the same `fill`/`query` values with a paid knock, but most parameter meaning is duplicated rather than added 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 and resource: knock on an x402 endpoint and get what it served. It explicitly distinguishes this from the sibling `test_purchase`, explaining that this tool is the paying half while `test_purchase` stops at the quote.

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 when-to-use guidance: omit `payment` to read terms, include `payment` to forward a signed authorization and retrieve the seller's response. It also names alternatives and prerequisites, including using `list_x402_endpoints` to find a catalogue endpoint and avoiding unpaid knocks more than once a minute.

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, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely non-annotated context: the response is complete ('in full'), it is deliberately published to the evaluated agents, and it carries no cost ('Free'). It does not, however, describe pagination or size limits for a full rulebook.

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 operational content is front-loaded: what is returned, then the completeness and cost notes. The closing aphorism ('a rule nobody can read is a rule nobody can correct') is rhetorical rather than informational, but it is short and does justify the deliberate-publication behavior.

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 an output schema present and annotations carrying the safety profile, the description only needs to say what the tool is for and what it returns, which it does well. The only gap is workflow placement relative to evaluate_action and the check_* family, which an agent would still have to 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?

There are zero parameters and the empty schema is fully self-describing, so the baseline is 4. The description adds nothing parameter-related, but nothing is needed.

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 the resource (the policies), the scope ('in full'), and the exact payload ('every rule, its id and the sentence it checks'), and it ties the resource to the sibling evaluate_action, which is the key disambiguator among 28 tools. The verb is only implicit ('the policies... can be run under'), so it reads as a resource description rather than an action, but an agent can still tell precisely what it returns.

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?

By naming evaluate_action the description implies when this is relevant (fetching the rulebook that evaluate_action checks against), and 'Free' hints it is cheap to call. However, it never states when to call this versus the other check_/evaluate_ siblings, nor any sequencing guidance such as 'call before evaluate_action'.

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), and the description adds genuinely new semantics: that the list is an allowlist of what is ingested, and that absence means 'not read by us,' not 'does not exist.' That negative-result interpretation is exactly the kind of context annotations cannot express. Ordering and pagination behavior are left to the schema, which documents offset/limit.

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 short sentences with no waste, and the scoping constraint is front-loaded. It is slightly telegraphic — 'The vaults we read' and the fragment 'Free.' read as clipped notes rather than plain guidance, which costs a little immediate intelligibility.

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

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

With only optional parameters and an output schema present, the description covers what an agent needs to call the tool correctly and interpret an empty result. Given roughly forty siblings including a near-named `find_vaults`, the missing cross-reference is the main completeness 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%, so all three parameters are already documented, including defaults and the nextOffset chaining convention. The description only loosely reinforces this with 'holding a name rather than a slug,' implying `q` is a name matcher. Baseline 3 is correct when the schema carries the parameter burden.

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 definition names the resource and its scope precisely: 'The vaults we read' tells the agent this is the enumeration of vaults the service actually ingests, and the clause about name-vs-slug clarifies the operative use. It stops short of distinguishing itself from the sibling `find_vaults`, so an agent must guess which of the two lookup tools to pick.

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 a concrete triggering condition: call this when you hold a name rather than a slug and need the one the service means. 'Free' also signals there is no cost barrier to calling it. It provides no explicit exclusions or routing to `find_vaults`, so the alternative-selection case is left implicit.

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, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: the catalogue size, that fields are seller claims, that listing is not evidence the endpoint answers, and that it is FREE.

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 key caveats, but it is somewhat verbose and mixes several claims in dense prose, which may reduce 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?

Given an output schema exists, the description need not explain returns. It covers purpose, key caveats, and pricing semantics, making it nearly complete for this 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?

Schema coverage is 100%, so the schema already documents q, limit, and payee. The description reinforces the payee and text-matching concepts but adds no new syntax or format details 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 and resource: listing x402 endpoints a payee sells or matching text. It clearly distinguishes from test_purchase by noting that a listing is not proof the endpoint answers.

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 for checking what a payee sells, but does not explicitly state when to use this tool versus alternatives like test_purchase or check_service_endpoint. The mention that test_purchase knocks on the endpoint is helpful context but not a full usage 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?

With readOnlyHint=false, the description goes beyond the annotation by explaining the reason ('this call writes a row in our store'), and it discloses idempotency per subject, auth need ('Needs a key'), first-run silence, and that unknown dimension/policy are refused rather than dropped. The one gap is destructiveHint=true: the description says a repeat call 'edits the watch' but never says what prior watch configuration is overwritten.

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 statement is front-loaded, but the prose is narrative and carries rhetorical filler ('a first reading dressed up as news is the thing this avoids', 'worse than no watch') and a meta-sentence addressing the annotations directly. Each sentence does carry a distinct behavioral fact, but the phrasing is wordier than the payload requires.

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?

An output schema exists, so return-format explanation is rightly omitted, and the description covers the write semantics, idempotency, refusal behavior, auth, and first-run edge case. It stops short of explaining what a 'change' notification looks like or what destructive overwrite entails, which is the only substantive omission for this 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 100%, so the baseline is 3; the description adds real meaning on top. It clarifies that 'subject' is the idempotency key ('calling it again edits the watch rather than creating a second') and reinforces the refusal semantics for unknown policy/dimension names with a rationale the schema only asserts.

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: be told when the answer about an address changes over time. It explicitly situates itself against a named sibling, explaining that the dimensions are the ones counterparty_check already answers and that this is 'that same reading on a schedule rather than a second opinion.' An agent can distinguish it from counterparty_check without opening either 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?

It gives clear context for use — scheduled re-reads for change detection, with the alternative (counterparty_check) implied as the same reading taken once. It also flags the first-run behavior ('reports nothing') so the agent isn't surprised. There is no explicit 'do not use this for X' exclusion, but the scheduling framing routes the agent well.

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?

It is 'free,' and it discloses interpretive behavior annotations cannot: the leader's holding is readable on Hyperliquid and Drift ONLY, so elsewhere it is ABSENT and not zero; the median describes strategies-we-can-read rather than the manager; a large own-share is evidence of alignment and never proof because the address may be a treasury or custodian. This is exactly the kind of data-semantics context that makes results usable, well beyond readOnlyHint/idempotentHint.

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 caveats, with no filler — every clause carries an interpretation rule. The prose is dense and slightly rhetorical, but nothing is redundant given how much nuance is packed in.

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?

An output schema exists, so return structure need not be described; the description instead supplies the interpretation caveats (absence vs. zero, median scope, cannotSee) and the input's origin. Complete for an agent to call it correctly and read the result sensibly, with only minor room to say more about edge cases.

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

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

Schema coverage is 100% with a single documented `slug`, so the baseline is 3; the description adds the provenance value ('as vault_check returns it in operator.slug'), telling the agent where to source the value rather than just its type.

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 frames the tool as 'the question that follows vault_check: who runs the money, and how much of it is their own,' which identifies the resource (the operator behind a vault) and the key output (ownShare) while explicitly positioning it relative to the sibling vault_check. It is slightly metaphorical ('who runs the money') rather than a literal verb+resource, but an agent can still distinguish it from 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?

It gives a clear sequencing rule: use this after vault_check and take the input 'from vault_check's `operator`.' That is actionable invocation guidance. It stops short of naming when NOT to use it or listing alternative siblings beyond vault_check.

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 behavior, but the description adds critical semantics: the figures NEST and must never be added up, x402 counts only certain tiers, `notShownToBeX402` is excluded from figures, and `deliveryUnevidenceable` reflects a rail limitation rather than seller failure. This is exactly the kind of 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?

The key instruction is front-loaded in the first sentence, and every subsequent clause adds substantive semantic detail about the nested figures. The paragraph is dense and could be split for readability, but it is not padded with redundant restatements of the name or title.

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 zero parameters, an existing output schema, and rich annotations, the description provides more than enough context: it explains the nesting rules, the x402-specific definitions, the `tiers` breakdown, and the sibling relationship. An agent has everything needed to interpret and quote the figures 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?

There are zero parameters, so parameter semantics are not a meaningful burden; the baseline for zero-parameter tools is 4. The description does not need to explain input syntax, and it compensates by thoroughly explaining the output categories instead.

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: three nested figures (`settled`, `serviceLinked`, `deliveryEvidenced`) across x402 and ACP rails, plus `tiers` and `notShownToBeX402`. It distinguishes itself from the sibling `agent_business` by noting that the same split for one address lives there. An agent can tell what this tool 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?

It gives an explicit usage trigger: 'BEFORE YOU QUOTE ANY FIGURE FOR AGENT COMMERCE, ask which of three it is.' It also names the alternative for per-address figures (`agent_business`), so the routing decision is fully specified. No inference is required.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely non-duplicated behavior: a queue OUTRANKS a declared exit figure, the four exit readings are never summed, and the tool cannot verify that the caller actually holds the listed vaults. Minor shortfall: it never discusses rate limits, cost, or what 'a plan buys' concretely means.

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, but the definition is long and written in an idiosyncratic all-caps register that makes a single-sentence point ('four figures, never added up') across several clauses. Most sentences do carry information, but prose could be compressed without loss.

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?

An output schema exists, so return-shape explanation is not required, and the description still goes beyond it by pre-empting the two obvious misreadings of the exit output (adding four figures, treating coverage as liquidity). Scope, limitations and routing are all present; only plan/cost semantics are left unspecified.

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

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

Schema description coverage is 100% and the property description already carries the format, optionality, pricing rules, null-versus-partial-sum behavior and the 50-holding cap. The tool description contributes only the caveat that holdings cannot be verified, 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 first sentence states the verb and resource precisely ('READ THE VAULTS YOU HOLD TOGETHER') and immediately scopes it as a set-level operation, naming the three cross-holding questions it answers (shared controller, shared market, non-additive exit). It explicitly distinguishes itself from the sibling vault_check ('every per-vault reading behind them at vault_check'), so an agent can route without opening either 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?

It states when this tool is the right one (cross-holding shared exposure that 'no vault page can show you') and points at vault_check for the free per-vault readings it sits on top of. It also states a boundary ('It cannot verify that you hold any of this'). There is no crisp when-not/exclusion list beyond the vault_check handoff, which keeps it just 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?

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior. The description adds substantial context beyond annotations: it defines the three verdicts, warns that `nothing-against-it` is not a safety guarantee, explains that `cannot-say` must not be read as a pass, and describes how findings and endpoint-quote precedence work.

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 instruction, then explains verdicts and caveats. It is dense and occasionally verbose with all-caps emphasis, but most sentences carry actionable information for a complex preflight 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?

Given the tool’s complexity, annotations, and available output schema, the description is complete enough for correct invocation. It covers when to call, what each verdict means, how missing inputs affect checks, and how to interpret named findings.

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 schema already documents all four parameters. The description adds useful meaning by explaining that omitting amountUsd, chain, or resource causes specific checks not to run, and that resource is the sharpest check because it carries the seller’s published price and payee.

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: weighing one payment immediately before sending it, with checks against the endpoint’s published price, payee, historical receipts, and chain activity. It also distinguishes itself from per-counterparty tools by saying 'not once per counterparty', which helps an agent tell it apart from siblings like counterparty_check.

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 timing guidance ('immediately before sending a payment, every time — not once per counterparty') and explains that missing parameters cause checks not to run. It does not explicitly name alternative tools or when-not to use this one beyond the per-counterparty distinction, so it falls short of the highest bar.

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

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

Beyond the annotations, the description discloses important behavior: receipts are judged against payments read from chain, `not-found` is a statement about reading two days after filing rather than proof of absence, `unverifiable` means the reference is not a transaction hash, and claims raise no evidence status. It also states the tool is readable only by the key that wrote the receipt and is free.

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 every clause carries useful semantic information about statuses or access. It is dense and parenthetical-heavy, but not padded with irrelevant material.

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

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

Given the output schema, annotations, and single-parameter schema, the description is complete enough to call the tool correctly. It adds status semantics, access restrictions, cost, and timing caveats that an agent would otherwise lack.

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 single parameter is already documented in the schema as the id returned by `record_receipt`. The description reinforces that origin but does not add further syntax, format, or validation details 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 operation: retrieving what happened to a receipt previously recorded with `record_receipt`. It clearly distinguishes the tool from `record_receipt` and explains the judged statuses, so an agent can identify the purpose without 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?

Usage is clearly implied and partly explicit: call this after `record_receipt` to learn the judgment on a receipt. However, it does not name alternative tools such as `payment_evidence` or state when not to use 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?

Goes well beyond the annotations: discloses that reference is stored unverified, that a background judgement runs within the hour and can land as verified/contradicted/not-found/unverifiable, that an unchecked claim never inflates evidence status, that a key is required, that receipts are readable only by the writing key, and explicitly why readOnlyHint is false and a duplicate call is not free. This is exactly the extra context annotations 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?

The call-to-action is front-loaded in the first clause, and the operational facts (evidence handling, verification outcomes, auth, idempotency) are all earned. Some framing prose ('the difference between a lookup and a control layer') is rhetorical padding that could be cut without losing instruction.

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 non-idempotent write tool with an output schema, the description covers everything an agent needs: when to call, what is stored versus verified, how and when the verdict is produced, where to read it, and the access-control model. No material gap remains.

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 already 100%, so baseline is 3; the description still adds meaning for `reference` (it is the caller's evidence, explicitly not verified) and explains the verification lifecycle that determines what a receipt can later be checked against. It does not add much for the optional fields (chain, policy, verdict, expected, deadline, amountUsd), which rely entirely on 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 (record a receipt of what you did) and explicitly frames it as the counterpart to the platform's 'should I' tools like check_action/evaluate_action. An agent can distinguish this write-and-later-reconcile tool from the read-only evaluation siblings 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?

'Call this AFTER you have paid an address or called a tool' gives an explicit temporal trigger and implicitly excludes pre-action use. It also routes the read path to GET /v1/receipts/{id} (receipt_status), so the agent knows where the follow-up verdict lives.

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 give generic safety hints, so the description carries the real load and delivers: no signing/sending/spending, head-block-only scope, per-holder defaulting, revert reasons surfaced (NotEnoughLiquidity, TransferReverted past V2 idle balance), oversize amounts clamped to position, unsupported chains not charged, and the x402 pricing model.

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 an all-caps imperative and ordered from what it does to limits to pricing. The middle is dense with stacked parentheticals and em-dashes, so some sentences require a second read, but no content 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?

Covers scope, mechanism, failure modes, unsupported-vault behavior, indirection via list_vaults/find_vaults, and cost model; an output schema exists, yet the description still sketches the return shape well enough to plan around it.

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 still adds meaning beyond the schema by explaining what happens when amountUsd exceeds the holder's position (tried at their position and reported as such) and by tying `pass` to free over-limit simulations on that vault.

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?

A specific verb plus resource plus mechanism: it runs the vault's own withdraw(amount, holder, holder) via eth_call at the head block. It also draws a clear line against adjacent tools (it simulates a call, it does not screen exits or report positions), so an agent can distinguish it from siblings like exit_screen or vault_exits.

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 opening line states the timing ('BEFORE YOU MAKE IT') and the description adds the boundary condition that only Morpho vaults are supported (others return simulated: false unpaid), plus the free/paid threshold. It does not name a sibling as the alternative to use instead, which keeps it just 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?

With annotations that only say readOnlyHint=false and openWorldHint=true, the description adds a great deal the agent could not otherwise know: the one-live-handshake-per-minute throttle, the 429 returned for a filled rehearsal inside the cooldown, the fact that filled rehearsals are excluded from endpoint history (implying unfilled ones are not), the three-state verdict rule that cannot-tell is never rounded up, and the guarantee that nothing is signed or spent. It also explains that quotedUsd is NULL when the catalogue lacks both halves of the token pair. This is rich disclosure well beyond the annotations.

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

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

The purpose is front-loaded and most sentences carry distinct information, but the prose is heavily stylized ('we knock', 'a hundred-fold error waiting to be quoted') and repeats the catalogue-gating point twice. It is noticeably oversized for the payload of facts delivered, costing clarity despite the information 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?

For a high-complexity, open-world tool with three parameters, a nested object, and an output schema, the description covers prerequisites, rate limits, side effects, and the semantics of the three verdict states. Return-value detail is partly explained despite the output schema existing, and nothing an agent needs to call it safely appears to be 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%, so the schema already carries the bulk of parameter meaning, including the detailed `fill` template-slot contract and the conservative-v1 default for `policy`. The description reinforces those points (only declared slots accepted, nothing silently dropped, origin/path pinned) but adds little syntax or format detail the schema does not already state, so the baseline of 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 opening sentence names a specific verb (rehearse/walk the purchase), a specific resource (an x402 endpoint), and a specific scoping constraint (without paying), so an agent immediately knows what this does. It does not, however, name or differentiate against the many adjacent siblings (preflight_payment, check_action, evaluate_action, inspect_payment), 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?

It gives prerequisites (the endpoint must already be in the x402 catalogue, discoverable via list_x402_endpoints) and discloses the one-a-minute-per-resource rate limit, which is real guidance. But it never states the decision point that selects this tool over preflight_payment or check_action, and offers no explicit when-not-to-use case.

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 open-world behavior, so the safety profile is covered; the description goes further by disclosing that the call is free, that ASPERN never holds a mainnet key and does not make the ERC-8004 calls, and what the hash does and does not cover. That is genuine context beyond the structured fields, though rate limits and pagination are unaddressed.

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, but the body is a dense all-caps run of em-dash clauses mixing behavioral disclosure, consumer guidance and release history. The 2026-10-21 narrative and the 'one number would destroy the distinction' aside are background that an agent does not need to call the 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?

An output schema exists, so return values need not be spelled out, yet the description usefully explains the hash/alsoPublished boundary and the refusal semantics that govern how to interpret missing dimensions. For a two-parameter read tool with full schema coverage, the agent has enough to call it and interpret the result 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 carries both parameters, including the slug/address resolution and the methodology-version caveat. The description reinforces the hash-rebuild use case for methodology and points to /v1/meta for the version list, but adds little that the schema does not already say.

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 clause states the resource precisely — a hash-committed assessment document for a vault — and adds a distinguishing property (the only artifact a third party can publish on chain under their own name) that separates it from sibling vault readings. It is clear what the tool returns, though it never plainly contrasts itself with named siblings such as vault_check or vault_risk_dimensions.

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 rather than stated: the agent learns to read data.document.refusals before treating a missing dimension as unknown, and to pass an older methodology to re-check an old hash, with the version list on /v1/meta. There is no explicit when-to-use/when-not versus the many sibling vault tools, 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 establish that this is a read-only, idempotent, non-destructive open-world access tool. The description adds substantial behavioral context beyond that: it says the tool is free, explains key-control implications, warns about interpreting `changedHands.watchedSince`, and directs the agent to `earned.comparability`, `earned.representativeness`, and `cannotSee`.

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

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

The description is dense and information-rich, with the purpose and highest-stakes warning front-loaded. It is longer than typical but mostly earns its length by surfacing caveats that affect interpretation; readability is slightly reduced by long packed sentences and heavy inline field references.

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?

An output schema exists, so the description is not obligated to document return values, yet it goes further by explaining how to interpret the most consequential fields and limitations. For a one-parameter but complex due-diligence tool, the description provides enough context to call and interpret 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% for the single `slug` parameter, and the schema already explains that it accepts a vault slug or resolvable address and recommends `list_vaults` first if only a name is known. The description adds no parameter-level semantics beyond that baseline.

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

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

The description clearly states the resource and due-diligence purpose: it reports what the record shows about a vault before putting capital in, including earned-vs-advertised rates, risk band, components, operator, and key-control details. It does not explicitly distinguish itself from close siblings like vault_assessment, vault_risk_dimensions, or vaults_earned, 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 opening phrase 'Before putting capital into a vault' implies when the tool is useful. However, it gives no explicit alternatives or exclusions among the many sibling tools, and its reading-order advice concerns output fields rather than 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?

Beyond the annotations (readOnlyHint=false, idempotent=true, openWorld=true) the description adds substantial behavioral semantics: the answer is the WORST component and never an average, 'unknown' outranks 'supports', 'not-asked' vs 'not-applicable' handling, the withdrawable figure is a FLOOR, and the 'PAID' marker discloses cost that annotations do not. It also disclaims that nothing is a guarantee of withdrawal. This is meaningfully richer than the structured fields 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?

The purpose is front-loaded in the first sentence, and most sentences carry real semantics (worst-of rule, unknown ranking, floor semantics). However it is long for a two-parameter tool and includes rhetorical padding such as the '$2m out of a vault with $400k free' illustration and the repeated 'PAID' emphasis, which dilute rather than inform.

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 an output schema present the description is not obliged to explain return values, yet it covers verdict aggregation, unknown handling, and the floor caveat thoroughly. Inputs, semantics, and limitations are all addressed; what is missing is any explicit sibling routing or when-not-to-use guidance.

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 schema already documents slug and amountUsd; the description nonetheless reinforces why amountUsd matters ('it is always about a size', a bare 'can I get out' has no answer) and warns that omitting it downgrades the result to a general picture. That adds interpretive value over the raw schema description, though it does not introduce new parameter mechanics.

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