Agent Embassy

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

Annotations already declare non-read-only, non-destructive, idempotent behavior, and the description adds context annotations cannot express: the call is paid ($0.25 USDC on Base or Arbitrum One), requires an x402 v2 PAYMENT-SIGNATURE header, and must be invoked as an HTTP POST to paid_url. The refusal rule for unverifiable principals is a real behavioral constraint 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?

The core semantics are front-loaded in the first sentence, with invocation mechanics and pricing following in logical order. There is mild redundancy at the end — 'Paid tool' and 'Paid URL' restate the payment context already established, plus a docs link — but nothing is confusing.

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 10-parameter paid mutation with full schema coverage, annotations, and an output schema, the description supplies exactly the missing invocation layer: transport (POST JSON to paid_url), auth (PAYMENT-SIGNATURE header), cost/chain, and the eligibility rule. Nothing needed to call it correctly is absent.

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

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

Schema description coverage is 100%, so parameter meaning is already carried by the schema, including the idempotency-key semantics. The description only restates the validity_days default ('defaults to standard'), which the schema already spells out, so it adds little beyond the 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?

States a specific verb and resource — 'Issue an Agent ID' — and defines the artifact as 'attestation binding a pubkey to a verified principal', which separates it from renew/revoke/verify siblings. It also adds a scoping rule ('unverifiable are refused') that tells the agent what eligibility means.

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 explicitly routes post-issuance checking to 'agentid_verify' and gives the operational precondition (payment via x402 and POSTing to paid_url). It doesn't contrast issuance with agentid_renew or agentid_revoke, so an agent deciding between lifecycle operations gets only the verb cue.

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 that this is a paid mutation requiring an x402 v2 PAYMENT-SIGNATURE header, costs $0.25 in USDC on Base or Arbitrum One, and must be invoked by POSTing JSON to the given paid URL. It also clarifies that renewing retires the old ID and that the signature is over the old Agent ID, which materially explains the destructive behavior.

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

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

The description is front-loaded with the purpose and retirement behavior, then moves to signing, default validity, the alternative tool, and payment details. It is dense but efficient, with only minor fragmentation in the payment sentences.

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

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

For a paid, destructive, signature-based mutation, the description covers the essential invocation mechanics: the paid URL, POST body instruction, x402 v2 payment header, price, and accepted networks. The schema and output schema handle parameter details and return values, so the description is complete enough for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents agent_id, validity_days, idempotency_key, and revocation_signature. The description adds only a light reminder that validity_days defaults to standard and that signing works like a revocation; the detailed signature format and idempotency semantics remain 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 specific verb and resource: 'Renew an Agent ID,' and explains the exact outcome: 'fresh ID, same chain; the old retires.' It also distinguishes the operation from the sibling tool agentid_revoke by naming it explicitly for outright retirement.

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: renew to replace an Agent ID while preserving the chain, and use agentid_revoke to retire outright. It does not spell out every eligibility condition or compare with agentid_issue, but the main alternative is named with its distinguishing purpose.

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 destructiveHint=true and idempotentHint=true, so the safety profile is known; the description adds meaningfully beyond that with the cost and payment rail ($0.25 USDC on Base or Arbitrum One), the x402 v2 payment-signature requirement, and the finality implied by 'no successor.' It stops short of stating outright whether revocation is reversible or what happens to previously issued attestations, which is the one behavioral gap left for a destructive operation.

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

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

Purpose is front-loaded in the first clause, and the sibling contrast follows immediately — good ordering. The payment sentences are dense but each carries non-obvious operational detail; the only friction is the somewhat awkward 'POST to paid_url' instruction, since paid_url is not actually a schema parameter and slightly blurs the invocation model.

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 values need not be explained, and the description fills the remaining gaps the structured fields cannot: price, payment protocol, endpoint URL, and the no-successor semantics. Completeness is only marginally short of 5 because finality/reversibility of retirement is never stated explicitly for what annotations mark as a destructive call.

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%, including a detailed revocation_signature spec and idempotency_key semantics, so the schema does the heavy lifting and a 3 baseline applies. The description's 'sign as the revocation_signature field specifies — who signs, and how' merely redirects to the schema rather than adding new meaning, and it does not surface the required reason or agent_id constraints in prose.

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 leads with a specific verb and resource — 'Retire an Agent ID instantly, with no successor' — which is more precise than the title's 'Revoke'. It actively distinguishes itself from the nearest sibling by noting that agentid_renew provides a 'fresh ID, same chain,' so an agent can choose between permanent retirement and rotation 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 names the alternative (agentid_renew) and the condition that selects it — no successor versus replacement. It also spells out the invocation prerequisite (POST JSON to paid_url with an x402 v2 PAYMENT-SIGNATURE header), but there is no explicit statement of when not to revoke, e.g. prerequisites such as holding the on-file revocation key are only implied via the signature parameter.

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

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

Annotations only say idempotent, non-destructive, not read-only; the description adds the material behavior an agent actually needs: this is a paid POST ($0.25, USDC on Base or Arbitrum One), it requires an x402 v2 PAYMENT-SIGNATURE header, the payload goes as JSON to paid_url, and unknown IDs degrade to 'unknown' instead of erroring. Cost, payment mechanism, and failure semantics are all disclosed 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?

It is front-loaded with the outcome states and sibling routing, then the payment mechanics — a sensible order with little waste. The telegraphic 'POST the tool inputs as JSON to paid_url' is slightly ambiguous since paid_url is not a declared parameter, though the literal URL at the end resolves it.

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

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

With an output schema present, return values need no explanation, and the description still covers what an agent must know to call it correctly: endpoint, HTTP method, required payment header, price and chains, and the never-error behavior on unknown IDs. Nothing needed for a successful invocation 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 both agent_id (64 hex chars, 30 checks/min rate limit) and idempotency_key (replay semantics, per-payer scoping) are already fully documented in the schema. The description adds only the transport instruction (POST inputs as JSON), not any new meaning about the parameters themselves, so the baseline 3 applies.

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

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

The description names the specific resource (an Agent ID) and enumerates the exact outcome space — valid, revoked, expired, unknown — plus that chain and envelope are returned. It also explicitly separates itself from agentid_issue (issue) and agentid_renew (extend), so an agent can pick it over its closest 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?

It routes the agent explicitly: use this for state checks, agentid_issue for issuance, agentid_renew for extension, and unknown IDs return 'unknown' rather than an error. What is missing is any when-not guidance (e.g. whether to use this before attest_work or trust_preflight) and prerequisites for obtaining the x402 payment credential before calling.

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 the privacy guarantee ("we never see it" — only the hash is transmitted), the output nature (signed, hash-chained attestation), the payment model and chains, and the transport/auth mechanism (POST JSON to paid_url with an x402 v2 PAYMENT-SIGNATURE header). These are exactly the preconditions an agent must satisfy before calling and are not derivable from readOnlyHint/destructiveHint/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?

The core purpose and privacy guarantee are front-loaded in the first sentence, with operational details (alternative tool, payment, endpoint) following in short clauses. A few lines are mildly redundant, such as "Paid tool — $0.25" immediately followed by "Paid URL: ...", but nothing is padded or off-topic.

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 need not explain the receipt contents, and it covers the pieces structured fields can't: privacy, pricing, chain, and the exact payment-header protocol. It omits anything about error behavior (e.g. malformed hash, rejected example keys, insufficient payment), which would have made it fully sufficient for a paid mutation 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 document_hash's 64-hex pattern and the idempotency_key replay semantics are already fully documented in the schema. The description only restates that document_name is an optional label and adds no new constraint or format detail beyond the structured fields; baseline 3 applies.

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

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

"Prove a document existed: send its SHA256 hash ... for a signed, hash-chained attestation" gives a concrete verb (prove/attest) and resource (document by hash), and the privacy clause clarifies exactly what is submitted. It differentiates against check_url_custom for live URLs, but never mentions the closest sibling attest_work, so the boundary with the other attestation tool 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?

It explicitly routes a related case elsewhere ("Live URLs: check_url_custom") and states the payment precondition ($0.25 USDC on Base or Arbitrum One) plus the required x402 header, which are real gating conditions. It stops short of a full when-to-use vs when-not framing, e.g. it never says when attest_work 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?

The annotations say nothing about payment, yet the description discloses the price ($222.00 USDC), the accepted chains, the x402 v2 PAYMENT-SIGNATURE header requirement, and the exact paid endpoint. That is exactly the kind of auth/cost context the description is supposed to carry beyond 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?

Purpose and the sibling disambiguation are front-loaded and the payment facts are compressed into two short sentences. The choppy, telegraphic fragments and the bare reference to 'paid_url' before it is defined slightly interrupt the flow.

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 the receipt format, and it covers payment mechanics, endpoint, and the sibling distinction. What's missing is post-call behavior on verification failure, which matters for a paid mutation.

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%, including a very detailed idempotency_key description, so the schema does the heavy lifting. The description's only added parameter meaning is flagging evidence_urls and evidence_hash as optional, which is already implied by the required array 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 specific verb and outcome ('Notarize work done anywhere... we verify it and mint a signed receipt') and explicitly disambiguates from the sibling 'attest_document' by naming that tool's job (document existence). An agent can pick between the two 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 routing guidance against attest_document and notes that evidence_urls and evidence_hash are optional, which shapes how to call it. It falls short of a 5 because it never states prerequisites, exclusions, or what to do if verification fails.

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 and idempotentHint, but the description adds the genuinely load-bearing behavior: this is a paid tool ($222.00, USDC on Base or Arbitrum One) that only charges and issues a receipt when a change is detected, and it requires an x402 v2 payment header. That auth/payment context is exactly what annotations cannot convey. What it omits is how the standing check is fulfilled or canceled afterwards.

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 short and front-loads the core concept and the sibling routing before the payment mechanics. The stitching of fragments (docs link, price, paid URL) is dense but every clause carries useful information, with minor redundancy around the interval default.

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 rich annotations, the description only needed to cover the payment gate and the standing-check semantics, and it does so. The gap is lifecycle detail — how a standing check is later inspected or halted — though that may belong to other 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?

Schema coverage is 100% and idempotency_key is documented in exhaustive detail in the schema itself. The only parameter the description touches is the default of check_interval_hours, which merely repeats the schema's declared default of 24.

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

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

The description states a specific verb and resource — a 'standing URL check' that only charges on change — and explicitly sets itself apart from the one-time sibling check_url_custom. An agent can classify this tool 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 names the alternative (check_url_custom) and the condition that selects it (one-time vs. standing), plus the required invocation path (POST JSON to paid_url with an x402 PAYMENT-SIGNATURE header). It does not distinguish check_url_sealed, so routing among all URL-watch siblings is not fully resolved.

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 destructiveHint=false, but the description adds critical context the annotations cannot: this is a paid tool ($0.001 USDC on Base or Arbitrum One) invoked by POSTing inputs as JSON to paid_url with an x402 v2 PAYMENT-SIGNATURE header. It also discloses that the result is a signed pass/fail receipt. It stops short of describing rate limits or behavior on fetch failure, so it is strong but not exhaustive.

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

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

The definition is dense and front-loads the core purpose before alternatives, payment mechanics, and invocation details. Every sentence (price, paid URL, x402 reference) is operationally necessary for a paid tool. The fragmentary phrasing is efficient but slightly harder to parse than plain prose, which keeps it from a 5.

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

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

With an output schema present, return values need not be explained, and the description correctly focuses on invocation requirements: payment protocol, price, endpoint, and sibling routing. Combined with 100% schema coverage and annotations, an agent has what it needs to call the tool. Missing only edge-case behavior (e.g., what a failing check returns), which is minor 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?

Schema description coverage is 100%, so every parameter is already fully documented, including defaults and constraints. The description's 'status, substring, JSON value' and 'Default status 200' merely map onto parameters the schema already explains, adding no syntax or edge-case detail beyond it. Baseline 3 applies when the schema carries the semantic load.

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 fragment 'Your conditions, one fetch: status, substring, JSON value — signed pass/fail receipt' conveys the specific action (single fetch of a URL evaluated against custom conditions returning a signed verdict), and it explicitly names the sibling alternatives (check_url_sealed for public proof, check_url_changes for watching). The telegraphic style makes it slightly less crisp than a full sentence, but an agent can distinguish it from siblings 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 routes explicitly to alternatives: 'Public proof: check_url_sealed. Watch: check_url_changes.' That gives clear when-to-use-this-vs-sibling guidance. It does not state exclusions or failure-mode conditions, but for a tool with two clear sibling alternatives the routing is adequate.

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 (which only say non-read-only, open-world, idempotent, non-destructive), the description discloses the critical operational facts: this is a paid tool, the exact price and chains, that inputs must be POSTed as JSON to the paid URL with an x402 v2 PAYMENT-SIGNATURE header, and a docs link for the payment protocol. Cost and auth mechanics are exactly the kind of behavior an agent cannot infer from annotations.

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

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

It is compact and front-loaded: proof concept first, alternative second, payment mechanics and price after. Minor waste exists, e.g. 'HTTP 200 at that moment, fixed at 200' restates itself, and the label 'paid_url' sits ambiguously between a field name and a URL.

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-value explanation is not needed, and the description covers the non-obvious parts an agent needs: payment flow, endpoint, price, and the alternative tool. It does not explain how the sealed receipt is verified or what the agent must retain for later verification, a small gap for a proof-oriented tool.

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

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

Schema coverage is 100% and the parameter descriptions are unusually rich, covering URL fetch limits, redirects, timeout, and full idempotency-key semantics. The description adds nothing parameter-specific beyond 'POST the tool inputs as JSON,' so the baseline 3 applies.

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

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

The description names the operation concretely: 'one fetch, transcript sealed in a signed receipt — HTTP 200 at that moment, fixed at 200,' and explicitly contrasts it with check_url_custom, so an agent can distinguish it from the sibling variants. The wording leans on marketing phrasing ('Proof anyone can verify') rather than a plain verb+resource statement, which slightly slows recognition of what is actually being checked.

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 the selection rule clearly: use this for a fixed, verifiable HTTP 200 proof, and use check_url_custom when you want your own conditions. Payment prerequisites ($0.25, USDC on Base/Arbitrum One, x402 v2 PAYMENT-SIGNATURE header) are given up front. There is no explicit when-not guidance against the other check_url_* siblings such as check_url_changes.

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

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

Annotations only declare safety/idempotency flags; the description adds substantial context they don't carry — that this is a paid POST to a specific paid_url, requires an x402 v2 PAYMENT-SIGNATURE header, costs $0.25 in USDC on Base or Arbitrum One, and returns a signed receipt. That is the exact information an agent needs before committing funds. It stops short of covering payment-failure or rate-limit behavior.

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

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

It is short and front-loads the purpose, then alternatives, then payment mechanics, which matches the order an agent needs. Minor waste remains in the promotional phrasing 'price moves that matter' and the trailing bare URL after the paid_url has already been given.

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, non-read-only tool, the description covers purpose, sibling routing, cost and currency, payment protocol, and the exact paid endpoint; parameters are fully covered by the schema and an output schema exists so return values needn't be described. An agent has everything required to invoke it correctly, including the payment step.

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 gpu, limit and idempotency_key in detail. The description only restates 'limit defaults to 25', which duplicates the schema rather than adding meaning, so the baseline 3 applies.

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

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

The description states a specific resource and output shape: 'GPU price moves that matter: significant spot moves, in a signed receipt.' Combined with the routing lines ('Live snapshot: compute_spot_prices. Past: compute_history') an agent can place it precisely among siblings, though the headline phrase 'that matter' is marketing wording rather than a crisp 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 explicitly names the two alternative tools and the conditions that select them: live snapshot versus past history, with this tool covering significant moves. There is no explicit 'do not use when' statement, so it falls short of a full 5, but the routing guidance is concrete and actionable.

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

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

The annotations only declare it is non-read-only, non-destructive, idempotent and closed-world; the description carries all the operationally critical context the schema cannot: it is a paid call ($0.25 USDC on Base or Arbitrum One), it requires an x402 v2 PAYMENT-SIGNATURE header, inputs must be POSTed as JSON to the paid URL, and it links to docs. This is exactly the kind of monetary/auth behavior an agent must know before invoking, and it is not duplicative of any structured field.

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 payload/scope sentence is correctly front-loaded, followed by alternatives, payment mechanics, and the endpoint, with no filler. The clipped fragment style ("Moves: compute_alerts.") is dense to the point of being slightly cryptic and could cost a beat of parsing, which keeps it off a 5.

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

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

An output schema exists, so return values need no prose. Given three near-fully documented parameters, the description still covers the things structure cannot: pricing, chain, x402 header requirement, transport (POST JSON to paid_url), the concrete endpoint, and sibling routing. Nothing an agent needs to invoke this 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 gpu filtering, the 1-200 integer range, the default of 50, and the full idempotency-key contract. The description only restates "limit defaults to 50," adding no format, syntax, or edge-case meaning beyond the schema, so the baseline 3 applies.

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

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

"GPU market memory: cheapest and median asks per class, in a signed receipt" names the resource (GPU market history), the specific payload (cheapest/median ask per class), and the artifact form (signed receipt). It then explicitly separates itself from two siblings: "Live: compute_spot_prices. Moves: compute_alerts." An agent can distinguish this from every other tool in the list 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?

The description routes the agent by contrasting this historical view against the live-price sibling and the price-movement sibling, which is real guidance rather than generic filler. It lacks an explicit conditional ("use when you need a time series rather than a current quote") and says nothing about when-not to call it, 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?

Goes well beyond the annotations by disclosing the payment model ($0.25/snapshot, USDC on Base or Arbitrum One), the required x402 v2 PAYMENT-SIGNATURE auth header, and the ephemeral nature of asks. It also explains the non-readOnly behavior implicitly via the paid call. It does not reconcile 'Observes only' with readOnlyHint=false explicitly, but the payment disclosure accounts for 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?

Dense and front-loaded — purpose first, then filtering semantics, then the sibling alternative, then payment/auth mechanics. Nearly every clause earns its place, though the fragmentary style ('GPU asks, not quotes') is slightly cryptic and costs a point.

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 values need not be described; the description covers filtering behavior, the sealed alternative, the paid URL, and the auth mechanism, which is what an agent needs to call it correctly. The only soft spot is not stating the consequence of the readOnlyHint=false annotation, though the payment note covers the practical effect.

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, and the description adds two facts not in the schema: that omitting gpu returns a full snapshot and that type defaults to ondemand. The remaining five filter parameters are left to the schema, which documents them fully.

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 the resource and scope concretely — GPU spot ask prices as a single timestamped snapshot — and distinguishes itself from compute_spot_sealed by name. The verb is implicit (the title carries 'Compute Spot Prices'), and the telegraphic 'GPU asks, not quotes' phrasing takes a beat to parse, so it falls short of a clean 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?

Gives practical selection context: 'Omit gpu = full snapshot; type defaults ondemand' and routes to the alternative sibling 'Sealed: compute_spot_sealed'. It also discloses the paid nature, which affects whether an agent should call it. It never explicitly states when NOT to use it, so 4 rather than 5.

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

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

Annotations only declare the safety profile (readOnlyHint=false, idempotentHint=true), and the description adds substantial context beyond them: the $0.25 USDC cost, accepted chains (Base or Arbitrum One), the x402 v2 PAYMENT-SIGNATURE header requirement, the paid_url endpoint, and a docs link. It does not cover failure/refund behavior when payment succeeds but the request fails, which is the remaining gap; readOnlyHint=false is consistent with charging and minting a receipt.

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?

Despite packing purpose, defaults, the raw alternative, payment mechanics, cost, and endpoint into a few short segments, nothing is wasted and the core purpose is front-loaded. Each fragment carries operational information an agent needs before calling.

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 explanation is correctly omitted, and the description covers what the schema and annotations cannot: payment protocol, cost, auth header, and endpoint. The main omission is the practical prerequisite of having a funded x402-capable payer and what happens on payment failure.

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 idempotency_key semantics (replay returns the original receipt, per-tool/per-payer scoping) are fully documented in the schema. The description's default notes ('type defaults ondemand; omit gpu = all classes') restate what the schema already says, so it adds little beyond the baseline 3.

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

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

The description uses a specific verb-and-resource framing ('GPU price, sealed proof: snapshot, cheapest ask/class, signed receipt') and names the sibling compute_spot_prices as the 'Raw' counterpart, so an agent can distinguish sealed-receipt pricing from raw pricing. It stops short of a single crisp sentence stating the operation, but the scope is clear.

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

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

It gives implied guidance through 'Raw: compute_spot_prices' and default notes ('type defaults ondemand; omit gpu = all classes'), but never explicitly says when to choose the sealed variant over the raw one or what preconditions exist (wallet/payer setup, funding). The alternative is named without a condition that selects it.

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

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

Annotations declare non-read-only, open-world, idempotent and non-destructive, and the description adds the crucial context those annotations cannot carry: the $1.00 USDC cost, the accepted chains (Base, Arbitrum One), the required payment-signature header, and a docs URL for the protocol. It stops short of failure/refund behavior or what the signed report attests, which keeps it below a 5.

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

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

The capability statement is front-loaded and useful, but the price is stated three times ('$1.00 correction pass', 'Paid tool — $1.00', plus the paid URL) and payment logistics are interleaved with the functional description. It is not padded with filler, but repetition of the cost and URL costs it structure points.

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

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

For a paid, open-world tool with an output schema, the definition covers what an agent needs to call it correctly: inputs to send, the endpoint, the payment header, the currency and chains. Only the post-payment failure modes and what 'leaks scanned' concretely checks remain unstated.

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

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

Schema description coverage is 100%, so all five parameters, including the enum for register and the full idempotency-key contract, are already documented in structured data. The description adds only one extra bit of meaning — 'register sets the voice' — beyond the schema, 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 description names a specific verb and resource — a '$1.00 correction pass on your draft' — and enumerates the actual operations (formatting, live link verification, term confirmation, leak scanning) plus the deliverables (corrected copy + signed report). No sibling tool in the list does copy correction, so the agent can distinguish it immediately.

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 solid invocation guidance (POST the JSON inputs to paid_url with an x402 v2 PAYMENT-SIGNATURE header) and notes 'register sets the voice', but it never states when to choose this tool over an alternative or what kinds of drafts are out of scope. Usage is implied by the artifact type rather than explicitly framed as when/when-not.

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

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

Annotations already cover safety and idempotency, and the description adds genuinely new operational context: the call is paid ($222.00 USDC on Base or Arbitrum One), requires POSTing inputs as JSON to a specific paid_url with an x402 v2 PAYMENT-SIGNATURE header, and returns a signed receipt. That is exactly the kind of auth/cost detail annotations cannot express; the only weakness is that payment failure behaviour and latency are not mentioned.

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 short and front-loads the bundle contents, which is good. But it is written in telegraphic fragments ('document_hash optional', 'One check: the tool alone') whose meaning is unclear, and payment mechanics are interleaved with capability description rather than separated, hurting scannability.

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, multi-check tool with a 100%-covered schema and an output schema, the description supplies what is missing: the composite nature of the result, the price and settlement chain, and the exact payment protocol. Only the cryptic single-check sentence and the absence of failure/payment-error behaviour keep it from a 5.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the detailed idempotency-key semantics and the SHA256 pattern for document_hash. The description only reiterates that document_hash is optional, adding no meaning beyond the schema, 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 description names the concrete checks bundled together (liveness, content, TLS fingerprint, trust verdict, doc timestamp) and states the output is a single signed receipt, which is far more specific than the bare name 'diligence_pack'. It does not, however, contrast itself with near neighbours such as trust_preflight, trust_report, or the check_url_* family, so the agent must infer which bundle is appropriate.

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 phrase 'One check: the tool alone' gestures at a rule of thumb (use individual tools for single checks) but never names a sibling or states the condition explicitly. Payment prerequisites and the price are spelled out, but there is no when-not-to-use guidance and no stated prerequisites for the target URL beyond the schema's HTTPS 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?

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), but the description adds the material behavior they cannot: this is a paid call at a fixed price of $0.25 in USDC on two named chains, requires an x402 v2 PAYMENT-SIGNATURE header, hits a specific paid URL, and returns a signed receipt. That is genuine context beyond structured fields, though it still omits what happens on payment failure or how the receipt identifies the caller.

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 short and the payment facts are front-loaded only after a dense product sentence, but the prose is telegraphic fragments ("agent_wallet optional, on the receipt.") rather than complete sentences, and the reader must reassemble protocol, price, and URL from clipped phrases. Nothing is gratuitous, but the ordering buries the critical payment precondition mid-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?

An output schema exists, so return-value detail is rightly omitted, and the payment mechanics are covered well enough to attempt a call. What is missing is the one thing this description alone could provide: what the returned template/receipt actually is and whether the payment POST happens through this tool or outside it, which is ambiguous given openWorldHint=false on a tool that names an external paid URL.

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 there is a single well-documented parameter, so the baseline is 3 — but the description introduces "agent_wallet optional, on the receipt," a field that does not exist in the schema, which sets additionalProperties=false. That actively misleads an agent into sending an undeclared property that will be rejected, so the description damages rather than adds to parameter understanding.

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

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

The description names the resource (a Farcaster starter kit: first casts, frame spec, launch checklist in a fill-in template) and the deliverable (a signed receipt), but never states a clear verb — is it generating a template, returning a guide, or issuing a receipt? The reader gets the domain but not the operation, so it lands at vague-purpose rather than a specific verb+resource.

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 explicitly routes one alternative: "On Nostr instead: nostr_kit," and it gives the payment precondition ($0.25 USDC on Base or Arbitrum One) and protocol (POST to paid_url with an x402 v2 PAYMENT-SIGNATURE header). It does not say when to pick this over the other 22 siblings or what happens if the payment header is absent, so usage is implied more than prescribed.

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 disclose readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description adds genuinely new behavior — real money moves in USDC on Base or Arbitrum One, the signed 402 quote binds the caller's exact amount, and a PAYMENT-SIGNATURE auth header is required. The idempotency claim mostly restates the annotation, and the return payload is left to the output schema, so it is strong but not exhaustive.

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 facts (gift, range, quote binding, x402 header) are front-loaded, but the range and 'paid' framing are stated twice ('$0.01–$222' then 'buyer chooses $0.01–$222.00') and the endpoint is repeated as 'paid_url' and then a literal URL. The promotional opener 'Support the Embassy' carries little selection value. Tight but with visible redundancy.

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

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

For a payment tool, the definition supplies the payment path (x402 v2 header, POST to the paid URL), amount bounds, currency/chain, and docs link, and it need not describe the receipt because an output schema exists. Only minor gaps remain, such as what happens on quote expiry or amount mismatch beyond the documented idempotent replay.

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

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

Schema coverage is 100% and both parameters carry detailed descriptions (canonical cent parsing, key format, per-payer scoping), so the schema does the heavy lifting. The description only reinforces the amount ceiling/floor and the 'signed quote binds your exact amount' constraint, adding marginal meaning beyond the schema — 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?

Names a specific action and resource — an open-amount USDC gift to 'the Embassy' — with the accepted range ($0.01–$222) and the fact that it yields a patronage receipt rather than work payment. No sibling tool (agentid_*, attest_*, check_url_*, compute_*, trust_*) overlaps with this, so an agent can identify it without opening the schema.

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

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

Gives clear context for when this applies: a voluntary tip/patronage payment, with the explicit exclusion that the receipt is 'never for work' — steering agents away from using it as a work-payment path. It also states how to invoke it (POST the inputs as JSON to paid_url with an x402 v2 PAYMENT-SIGNATURE header). It stops short of naming an alternative tool for the excluded 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description discloses the critical traits the annotations cannot express: a $222.00 charge in USDC on Base or Arbitrum One, an x402 v2 PAYMENT-SIGNATURE header requirement, and a non-custodial design where credentials and mail are never held. It does not address refunds, failures, or what happens on payment error, which keeps it from a 5.

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

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

The description is short and front-loads the price and the one-time nature, then the trust and privacy position, then the payment mechanics. A few phrases, such as 'no subscription, no contract' and 'we never see your mail', are marketing framing, but they still convey useful purchasing context.

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 values need not be explained, and the core needs are covered: price, asset, networks, payment header, and how the result unlocks downstream tools. Remaining gaps are edge behavior on payment failure and how to retrieve the receipt, which are minor for a three-parameter purchase 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 holder_type, holder_label, and idempotency_key are already fully documented in the schema, including the detailed idempotency replay semantics. The description adds no parameter-level meaning of its own, 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 description makes clear that this is a one-time license purchase for the Inbox Clearance product at a stated price, and the phrase 'The license key in your receipt unlocks the pass tools' distinguishes it from the pass-related siblings such as inbox_clearance_open_pass or inbox_clearance_record_pass. It stops short of naming an alternative tool explicitly, but an agent can identify the purchase step without opening any sibling 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: the license is a single one-time purchase, it runs through your own agent on your own Gmail, and the returned key unlocks the pass tools, so the agent knows this is the prerequisite step. What is missing is explicit exclusion guidance, such as what to do when a license already exists or which sibling to call if the pass has already been purchased.

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=false and openWorldHint=false, so the agent knows this mutates platform-side state without reaching outside. The description adds context annotations cannot carry: the call is free, gated by a license, runs against the caller's own Gmail session, and the vendor never holds credentials or sees mail. It does not address the non-idempotent risk (calling twice may open two passes) or pass lifetime, which is the one real behavioral gap.

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

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

The action and its license prerequisite are front-loaded in the first clause, and the rest is framed as return content plus trust posture. Some promotional packaging ('$222 once', 'Free') is tolerable because it tells the agent the call itself costs nothing, but it consumes space that could have covered idempotency.

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

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

For a one-parameter tool with an output schema, the description covers the essential unknowns: prerequisite license, cost, privacy boundary, and what the response runbook contains. Missing only whether repeated calls open duplicate passes and whether a pass expires, which matters given idempotentHint=false.

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 license_key parameter, so the baseline is 3 and the schema already explains origin of the key. The description corroborates rather than extends that ('the license key is the gate'), adding only the fact that it was issued once by inbox_clearance_buy.

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: 'Open an Inbox Clearance pass' and names the returned artifact (the pass runbook with 17 elements and 8 settings). It also names the prerequisite sibling inbox_clearance_buy, but it does not distinguish itself from inbox_clearance_record_pass or inbox_clearance_report, so an agent picking among the four inbox_clearance tools still has 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?

The gate condition is explicit: a perpetual license bought once via inbox_clearance_buy is required, and the license_key parameter is described as 'the gate'. That is clear context for when the call is valid, but there is no when-not guidance and no routing to the sibling tools (record_pass, report) that an agent might confuse it with.

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 idempotentHint=true and destructiveHint=false, and the description is consistent with readOnlyHint=false by describing a record/write into an existing pass. It adds behavior the annotations cannot: unknown ids are refused, sensitive credential categories are excluded by construction, and entries must come from live reads rather than being invented. Licensing cost ('free under the perpetual license') is also useful operational context.

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

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

Three tight sentences with the core action and target front-loaded, followed by the state taxonomy and the guardrails. Every sentence carries information, though the compressed phrasing ('each confirmed, unverified with its reason, or failed with its reason') reads densely and repeats the schema's reason rules.

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 five-parameter tool with nested objects and an output schema, the description covers the prerequisite pass, the accepted states, refusal on unknown ids, scope exclusions, and licensing. Return-value details are rightly left to the output schema. Only the absence of explicit sibling routing keeps it from being fully complete.

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

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

Schema description coverage is 100%, so the schema already documents elements, settings, audit, pass_id and license_key, including the reason-required rule. The description reinforces the confirmed/unverified/failed semantics and the live-read requirement for before/after, but adds little syntax or format detail beyond the schema 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 opens with a specific verb and resource — 'Record element and setting states into an open Inbox Clearance pass' — which pins down both the write action and its target. It is immediately distinguishable from inbox_clearance_open_pass (creates the pass) and inbox_clearance_report (presumably consumes it), and the enumerated state values confirm the record 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 states the prerequisite clearly by referencing 'an open Inbox Clearance pass' and by implication the pass_id from inbox_clearance_open_pass, plus the key constraint that values must be ones 'your agent read live.' It also carves out scope exclusions (password, 2FA, passkey, recovery changes) and refusal behavior for unknown ids. It stops short of naming a sibling as the alternative path, so it is clear context rather than a full routing 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?

Beyond the annotations (which already say not read-only, idempotent, non-destructive, closed-world), the description adds two non-obvious behaviors: the full before/after table is returned exactly once at close, and only hashes persist afterward. That 'one-shot disclosure' detail is exactly the kind of context annotations cannot convey. Cost info ('$0.00 charged') is also disclosed. It stops short of describing what a second call returns or any failure modes.

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

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

The core sentence is front-loaded and information-dense, but the pricing point is stated twice ('$0.00 charged under the perpetual license' and 'Free under the perpetual license'), which is wasted space in a three-sentence description.

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

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

An output schema exists, so return values needn't be spelled out, and the description covers the key operational facts: it is a closing step, it mints a signed receipt, the table comes back once, and it is free. Missing only sequencing/error expectations (e.g. behavior when the pass is already closed or elements were never recorded).

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 routes pass_id to inbox_clearance_open_pass and license_key to inbox_clearance_buy. The description adds no parameter meaning beyond that, 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?

States a specific verb+resource: 'Close an Inbox Clearance pass and mint its signed before/after report', and clarifies the payload (per-element states and hashes in a signed Outcome Receipt). It is clearly distinguishable from inbox_clearance_open_pass and inbox_clearance_record_pass by being the closing/report step, though it never names those siblings explicitly.

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

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

Usage is only implied through the lifecycle verb 'close' — an agent must infer that this is the final step after opening and recording a pass. No alternative tools are named, no preconditions stated (e.g. that record_pass must have run first), and no when-not guidance.

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

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

Annotations declare mutation/idempotency, and the description goes well beyond them: it discloses the price ($0.25), the settlement chains (USDC on Base or Arbitrum One), the required x402 v2 PAYMENT-SIGNATURE header, and the POST target. The idempotency semantics (replay returns the original receipt) confirm the annotation usefully. It does not say what happens on payment failure or how long the receipt/work product remains retrievable.

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 there is no obvious padding, but the text is a chain of telegraphic fragments ('agent_wallet optional, on the receipt.', 'Paid URL: ...') rather than clean sentences. The payment mechanics and the deliverable description are interleaved, which makes it harder to scan for the essentials before calling.

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 no prose, and the payment/transport details are unusually complete for a paid endpoint. However, the description never clarifies whether the 'kit' is a filled template document, a structured payload, or a link, and the stray agent_wallet reference creates ambiguity about the call contract.

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

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

With one fully documented parameter at 100% schema coverage, the baseline is a 3, and the description lowers it by introducing 'agent_wallet optional, on the receipt' — a parameter that does not exist in a schema that sets additionalProperties: false. That fragment actively misleads about what the caller may send. It adds no usable meaning about idempotency_key beyond what the schema already states.

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

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

The description names the resource concretely ('Nostr from zero: first notes, profile, relays, launch checklist in one fill-in template with a signed receipt') and explicitly distinguishes itself from the sibling farcaster_kit, so an agent can route between the two. It stops short of a clear action verb (produce/generate), and 'kit' remains a slightly abstract deliverable, but the subject matter is unambiguous.

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

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

The alternative is named directly — 'On Farcaster instead: farcaster_kit' — which gives an explicit routing condition rather than leaving the agent to guess. It also signals cost and payment prerequisites, which effectively gate usage. It lacks guidance on when this tool is inappropriate beyond the Farcaster case, or how it relates to the other 20+ siblings.

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

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

No annotations are supplied, so the description carries the full behavioral burden, and it discloses almost none: no statement of side effects, auth or quota requirements, freshness, or pagination. The one behavioral fact offered — that results may be absent for some years — is useful but thin for a tool with zero annotation coverage.

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

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

Two sentences, no redundant wording, but also no front-loading of the most decision-relevant fact. It is brief without being well-structured — brevity here reflects omission rather than economy.

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

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

With no annotations and no output schema, the description is the only source of behavioral detail, and it leaves the return shape ('ranked metric bucket'), scope of 'several measured years,' and failure modes unexplained. For a ranking/metric tool with no structured safety or output metadata, this is under-specified.

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 and the baseline of 3 applies. The description adds no syntax, formatting, or constraint information beyond what the schema provides.

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

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

The description names a specific verb and object — 'Fetch top-ranked conversion-based ROI metric breakdowns' — which is more than a restatement of the name. However, the resource itself is fuzzy ('metric bucket'), and the tool sits among X/Twitter lookup siblings with nothing in the text to distinguish it from them or to explain the ranking basis.

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

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

There is no statement of when to use this tool, when not to, or which sibling it replaces. The only conditional hint is 'whenever available,' which describes output availability rather than selecting this tool over an alternative.

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

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

Annotations already declare this as a safe, read-only, idempotent operation. The description adds useful behavioral context beyond them: results are newest first, pagination uses limit and offset, and the call is free. It does not discuss auth or rate limits, but that is minor here.

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 the main purpose front-loaded and alternatives appended efficiently. No filler or repetition.

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 a simple read-only list tool with full schema coverage, annotations, and an output schema, the description supplies the key context: scope, ordering, pagination, cost, and sibling routing. Complete enough for correct invocation.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema. The description mentions pagination via limit and offset and wallet scoping, but adds little detail beyond what the schema provides.

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

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

States a specific resource and scope: every receipt the wallet has paid for, ordered newest first, with per-tool counts and total charged. It is immediately distinguishable from receipt_lookup and watch_list by naming both alternatives.

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?

Clearly indicates this tool is for full receipt history and routes single-receipt lookups to receipt_lookup and URL watches to watch_list. It lacks an explicit when-not condition, but the alternatives establish the boundary 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?

The annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description still adds genuinely new context: the call is free, results are permission-scoped to the paying wallet, and the response includes a signature check plus settlement state. It stops short of describing edge behavior (e.g., what happens for an unknown or non-owned receipt_id), which keeps it off a 5.

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

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

Roughly four short statements, all front-loaded with the verb and return contents before the disambiguation clauses. Nothing redundant; even the one-word "Free." carries a real selection signal.

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 does not need to enumerate return fields, and it still summarizes them. Annotations cover the safety profile, the schema covers parameter formats, and the description covers routing and the authorization constraint — nothing an agent needs to invoke 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% and both parameters are documented there, including the emb_+24-hex format and the account-scoping note on agent_wallet. The description's "wallet must be the one that paid" largely restates the schema's own wording rather than adding new meaning, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ("Look up one of your own receipts by receipt_id") and enumerates what comes back: the stored signed receipt, its signature check, and settlement state. It also explicitly separates the tool from receipt_history and check_url_custom, so an agent can distinguish it from 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?

Routing is explicit: "One receipt by id: this tool. Your whole history: receipt_history. A check on a URL: check_url_custom." Each alternative is named with the condition that selects it, and the "wallet must be the one that paid" line states a precondition for use.

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 (destructiveHint=false, idempotentHint=true), the description discloses the important behavioral trait that the blob is stored opaquely and cannot be decrypted by the service, that only its hash and byte count enter a signed receipt, and that release is quorum-governed. It also states the paid nature, price, and network up front. It stops short of describing failure modes, review turnaround, or what an operator can and cannot do with the escrow.

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 in the first clause, with payment and endpoint mechanics after it, which is the right order for a paid tool. The sentence is dense and semicolon-chained, mixing escrow semantics with transport details, but almost every element carries operational weight for a payable endpoint.

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 write tool whose return shape is already covered by an output schema, the description supplies the encryption posture, receipt semantics, quorum governance, and full payment invocation details. Remaining gaps — what operator review entails downstream and how release is subsequently triggered — are adjacent concerns rather than blockers to calling it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns one more by reinforcing the semantics that matter most — that recovery_blob must be client-encrypted and is stored opaquely, and that quorum_rules are the release policy rather than free-form metadata. It adds context but no new format details beyond what the schema already documents.

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 ('Escrow an encrypted recovery blob') plus the outcome: opaque storage, operator review, a signed receipt proving the hash, and quorum_rules governing release. No sibling tool overlaps with recovery escrow, so an agent can identify this as the distinct registration path without opening the schema.

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

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

Usage is implied rather than stated: an agent infers this is the tool for depositing a client-encrypted recovery secret under quorum rules. There is no explicit when-to-use/when-not guidance, no mention of a companion retrieval or release tool, and no prerequisites beyond the payment mechanics. The invocation instructions (POST to paid_url with an x402 header) are operational, not selection guidance.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the description's main job is to add the payment context — and it does: exact prices, USDC settlement on Base or Arbitrum One, license bound to the buyer's wallet, and the x402 v2 PAYMENT-SIGNATURE handshake with a docs link. It stops short of disclosing failure/refund behavior, settlement timing, or what happens if payment is rejected, and the instruction to "POST the tool inputs as JSON to paid_url" is ambiguous about whether the agent invokes the tool normally or makes an external HTTP call.

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

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

The description is a run-on of em-dash fragments front-loaded with price rather than purpose, and it repeats the figures redundantly ($222.00 appears three times, $444.00 twice, plus "Paid tool — $222.00"). The actionable invocation detail (POST to paid_url with PAYMENT-SIGNATURE) is buried mid-paragraph rather than leading.

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 and parameter coverage is complete, so the description doesn't need to explain return values, and the annotations cover the safety profile. What remains thin for a paid mutation tool is the payment lifecycle (when funds are captured relative to paper delivery, what a failed or underpaid request looks like) and the ambiguity of the external-POST instruction, which could lead an agent to call it incorrectly.

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 every parameter (bundle tiers, paper_id rejection behavior, buyer_alias format, idempotency replay semantics, prior_receipt_id pricing) is already fully documented in the schema. The description's pricing and upgrade mentions largely duplicate the bundle and prior_receipt_id descriptions, adding no new parameter meaning; baseline 3 is appropriate.

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

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

The description conveys that this is a paid purchase of a research paper licensed to the buyer's wallet, with an optional provenance bundle, but it never states a clean verb+resource sentence — the first clause is a price list ("The research paper: $222.00; $444.00 with the provenance pack"). It also gives no differentiation from siblings like diligence_pack or attest_document, which an agent could plausibly confuse with a research/attestation purchase.

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 only usage guidance is about the bundle tier and the prior-receipt upgrade path, which is parameter selection, not tool selection. There is no statement of when to choose this over sibling tools, no prerequisites (e.g., wallet/funding requirements), and no exclusion 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?

Annotations are sparse (readOnlyHint=false, idempotentHint=true), and the description adds substantial context they don't carry: a $0.25 USDC price on Base or Arbitrum One, a required x402 v2 PAYMENT-SIGNATURE header, the paid endpoint URL, and the idempotency-replay behavior. It also clarifies no orders are placed despite the non-read-only hint. It stops short of explaining what "delayed scan" or "freshness-labeled" concretely mean.

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 text is short and front-loads the purpose before payment mechanics, which is good. But the opening clause is compressed to the point of obscurity, and payment/URL details are interleaved with scope statements rather than grouped, forcing the agent to parse several dense fragments.

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 needn't be explained, and the payment workflow is covered. Still, key concepts an agent would need to interpret results or choose parameters — what "delayed", "freshness-labeled", and "expressions" mean — are left undefined for a five-parameter 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?

Schema description coverage is 100%, so every parameter is already documented, including the query grammar, objective options, and budget tiers. The description only restates the budget-omitted-means-uncapped rule and adds no new meaning about objective selection or max_rows behavior; 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 says to "Shop an idea" and mentions "expressions fitting your budget, freshness-labeled, signed receipt," which hints at returning candidate trade ideas for a ticker/theme, but the phrasing is idiosyncratic jargon ("delayed scan", "expressions") that an agent must interpret. It never plainly states the verb+resource (e.g., "returns ranked ticker/option ideas"), and it does not distinguish itself from close siblings like compute_spot_prices or compute_spot_sealed.

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?

"Ideas only — no orders placed" is a genuine scope exclusion, and "budget_usd omitted: uncapped" plus the query examples imply when the tool fits. However, there is no explicit guidance on when to prefer this over the sibling compute/check tools, nor any stated prerequisites for obtaining an x402 payment signature before calling.

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 readOnly=false, openWorld=true and idempotent=true, and the description adds genuinely useful non-schema behavior: the tool is paid ($0.25 USDC on Base or Arbitrum One), requires an x402 v2 PAYMENT-SIGNATURE header, and expects the inputs POSTed as JSON to a specific paid_url. That payment and transport detail is exactly the kind of context annotations cannot convey; only the mechanics of what happens on payment failure are unstated.

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

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

Front-loaded with the gate purpose and verdict set, then payment mechanics. It is dense and mostly earns its space, though the paid URL is stated twice ('paid_url' and the literal URL) and 'Terms: trust_preflight' is terse to the point of being cryptic.

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

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

For a paid, open-world tool with five required parameters and an output schema, the description covers cost, chain, payment protocol and endpoint – enough to invoke it correctly, and return values need not be explained since an output schema exists. Idempotency semantics live in the schema rather than the description, which is a minor omission rather than a gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the four probed inputs (endpoint, action, amount, permissions) in gate terms, which adds light framing but no syntax or format detail beyond the schema, and it says nothing about the optional 'context' 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?

The description names a specific function – an action gate that evaluates provider_endpoint, action, amount_usdc and permissions_requested – and states the four concrete verdicts (ALLOW, RESTRICT, ASK_HUMAN, QUARANTINE). It also cross-references the sibling names trust_report and trust_preflight, which helps position it, though the phrase 'probed unpaid' is ambiguous and the relationship to those siblings is only implied.

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 hints at context by labeling itself an 'action gate' and pointing to trust_preflight for terms and trust_report for the verdict, but it never says explicitly when an agent should call this instead of trust_preflight or trust_report. There are no stated prerequisites or exclusions beyond the payment requirement.

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

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

The annotations only declare it is non-read-only, idempotent, non-destructive and open-world; the description adds the material facts an agent needs: it is a paid tool at $0.25 in USDC on Base or Arbitrum One, the call must POST JSON to the paid_url with an x402 v2 PAYMENT-SIGNATURE header, and dry_run is intercepted before the payment gate so it is free. These payment, cost, and auth details go well beyond the annotation set. No contradiction with idempotentHint=true or destructiveHint=false.

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 and the free-preview option are front-loaded, and every remaining sentence carries invocation-critical information (payment header, price, paid URL). The colon-chained phrasing is choppy and the bare token 'paid_url' requires the agent to connect it to the trailing 'Paid URL' string, but there is little outright waste.

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?

This is a high-complexity tool with nested parameters, a payment gate, and an output schema, and the description covers the payment model, the free escape hatch, and the sibling alternative. Return values need not be explained because an output schema exists. The only gap is the lack of explicit guidance on how policy strings or context affect the verdict.

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

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

With 100% schema description coverage, the schema already documents every parameter, including the detailed idempotency_key contract. The description only reinforces dry_run=true as the free-quote mode; it adds no meaning about intent, policy, subject, or context beyond structured fields. Baseline 3 applies.

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

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

The opening clause names the specific job: a pre-payment trust check producing a signed verdict on 'who is paid, what's delivered, what changed' against supplied policies. It is telegraphic rather than a clean verb+resource sentence, but an agent can tell it produces a verdict about a spend target. It also distinguishes itself from one sibling by naming trust_report as the endpoint-verdict alternative, though it leaves trust_assurance unaddressed.

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' states the triggering condition clearly, and 'Free quote: dry_run=true' tells the agent how to preview without cost. 'Endpoint verdict: trust_report' routes to a sibling for a different use case. There is no explicit when-not-to-use clause or prerequisite list, which keeps it from 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 flag openWorld, non-read-only, idempotent, non-destructive, but the description adds material context they don't carry: the probe is performed unpaid first (so no charge for a failed probe), the price is $0.25 in USDC on Base or Arbitrum One, and payment requires an x402 v2 PAYMENT-SIGNATURE header POSTed to the paid URL. It does not state failure or refund behavior, which keeps it below 5.

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

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

The verdict and its four outcomes are front-loaded in the first clause, and later clauses cover alternates, payment mechanics, and price. It is telegraphic to the point of near-fragment sentences, but nothing is filler except arguably the docs link alongside the paid URL.

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 doesn't owe return-value detail, and it still names the verdict enum. Payment, pricing, network, endpoint, and the unpaid-probe behavior are all covered; missing only error/refund handling, which is a minor gap for a paid one-shot 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% and the schema itself documents the URL probing fallback and the idempotency replay semantics in detail, so the description need not carry parameter meaning. The description's only added mechanic is the payment-signature invocation pattern, which is not about the two parameters themselves — baseline 3.

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

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

The description names a specific resource (an x402 endpoint), a specific deliverable (a buy/don't-buy verdict) and enumerates the four possible verdicts (PROCEED, VERIFY_FIRST, DO_NOT_PAY). It also distinguishes itself from trust_preflight (terms) and trust_assurance (action gate), so an agent can pick it out of a 23-tool sibling list.

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 routes the agent to the two nearest alternatives by labeling their roles — trust_preflight for terms, trust_assurance for the action gate — which implicitly says when this tool is the right one. It stops short of an explicit 'use this instead of X when Y' rule, so a 4 rather than 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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the description doesn't need to restate safety. It goes further by disclosing the concrete consequence — it 'stops future change checks and charges' — and confirms it is free and that a repeat call returns the same cancelled state, which is real operational context.

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

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

Three short sentences with zero waste: the action and identifier come first, followed by cost/idempotency, then sibling routing. Every clause earns its place.

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

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

For a two-parameter mutation with annotations, a full schema and an output schema, the description covers effect, cost, idempotency and alternatives. Minor gaps remain around whether in-flight checks are completed before cancellation takes effect.

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

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

Schema coverage is 100% and both parameters carry their own descriptions, including where to obtain watch_id. The description's mention of watch_id adds no format or validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Cancel one of your standing URL watches by watch_id' — and explicitly distinguishes itself from watch_list (view) and check_url_changes (create). An agent can route correctly 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?

Names both relevant alternatives with their roles ('Your watches: watch_list. Create one: check_url_changes'), which gives clear routing context. It stops short of stating exclusions or prerequisites (e.g., that the watch must not already be cancelled).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds two useful behavioural facts — that the call is free and that status has two discrete values, watching or cancelled — but says nothing about ordering, pagination, or volume of results, which an output schema alone may not make obvious.

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

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

Three tight sentences, front-loaded with the resource and status, then the sibling routing. The lone filler is "Free.", though it does carry cost information not present elsewhere.

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?

A read-only, one-parameter list tool with an output schema and full annotations needs little prose. The description supplies the status vocabulary and the create/cancel routing, which is everything an agent needs to call it correctly.

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

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

There is a single parameter with 100% schema description coverage, including the note that the wallet is "the one that paid" and that results are scoped to it. The description reinforces wallet scoping via "your standing" but adds no new meaning beyond the schema, so the baseline 3 applies.

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

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

Uses a specific verb+resource combo — "List your standing URL watches" — and immediately qualifies the scope ("created by check_url_changes") and payload ("each watch's status"). That is enough to separate it from watch_cancel and check_url_changes 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?

Explicitly routes the two adjacent actions: create via check_url_changes, cancel via watch_cancel. An agent that wants to mutate watches is pushed to the correct sibling, leaving this tool's role unambiguous.

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