agent-embassy

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

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description discloses meaningful runtime behavior: issuance is refused when the principal cannot be verified, it is a paid $0.25 tool, it requires an x402 v2 PAYMENT-SIGNATURE header, and the payload must be POSTed as JSON. This adds real behavioral context beyond the generic hint flags.

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 purpose, then provides the essential payment, transport, and refusal behavior without padding. The last sentence crams cost, network info, and URL together, but it remains compact and every sentence carries useful information.

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

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

For a paid identity-issuance tool with a rich schema and an output schema, the description covers the critical operational facts: refusal behavior, cost, payment network, transport method, and endpoint. It does not spell out x402 setup prerequisites, but the linked documentation and payment details are sufficient context for an agent to proceed.

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 input schema already explains all 10 parameters. The description adds only high-level summaries like 'operator details and an expiry' rather than new per-parameter semantics. This matches the baseline of 3 when the schema does the heavy lifting.

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: 'issue an Agent ID: a signed identity attestation binding an agent's public key to a verified accountable principal.' This clearly separates issuance from the sibling operations renew, revoke, and verify, and states the core output without ambiguity.

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

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

The first sentence gives explicit guidance: 'Use agentid_issue when you want to issue an Agent ID.' It provides clear context and the main condition for use. It does not explicitly name alternatives or exclusions, but the sibling set makes the intended choice obvious enough.

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 indicate a mutating (readOnlyHint=false) yet idempotent (idempotentHint=true) operation. The description goes far beyond this: it explains that the old ID is retired, specifies the exact signature schemes (EIP-191 vs ed25519) and their failure modes (raw ECDSA fails), requires a payment with a specific header, and details idempotency key semantics. This level of behavioral detail is exceptional and not contradicted by annotations.

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

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

The description is dense but every sentence carries necessary information. It is front-loaded with the core purpose and then methodically covers signature, payment, and URL. The structure uses semicolons and precise technical details without fluff. It is long because the tool is complex, not because of 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 tool with this complexity—multiple signature schemes, payment requirements, idempotency, and a retired-ID side effect—the description covers all operational aspects: the exact message to sign, allowed signers, payment details, URL, idempotency behavior, and validity defaults. Since an output schema exists, return values need no explanation. Nothing an agent needs to call 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?

Even though schema coverage is 100%, the description adds substantial meaning beyond the schema. For revocation_signature, it details the exact message format, signing algorithms, and the requirement for the EIP-191 envelope. For agent_id, it notes case-insensitivity and rejection of unknown IDs. For idempotency_key, it explains scoping rules and that published example keys are rejected. This is a model of parameter enrichment.

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 precise verb-resource pair ('renew an Agent ID') and immediately differentiates it from siblings by stating what changes (fresh ID, same identity chain, new expiry, old retired). This unambiguously separates it from issue, revoke, and verify.

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 clearly states when to use the tool (to renew an Agent ID) and provides extensive context on how to invoke it (payment, signature, URL). It does not explicitly name alternative tools or exclusions, but the purpose is so specific that the intended use case is unambiguous. The reference to the same contract as retiring hints at the revoke tool but does not formally contrast them.

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 indicate a mutation (readOnlyHint false) and idempotency (idempotentHint true). The description adds valuable behavioral context: it is a paid tool ($0.25), requires a specific payment header, and details the signing requirements (EIP-191 vs ed25519, signer roles). It also clarifies the 'instantly' effect, though it does not fully explain post-revocation behavior. No contradiction with annotations.

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

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

The description is a single dense paragraph that mixes purpose, signing instructions, payment details, and a URL. It is front-loaded with the purpose, but the volume of technical detail makes it less scannable. Some information (e.g., exact URL, cost) could be structured better, though the content is necessary for correct invocation.

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

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

Given the tool's complexity (signature generation, payment, idempotency), the description covers the essential invocation details: payment cost and URL, required header, signature formats, and signer roles. It does not describe return values, but an output schema exists (has output schema: true), so that is acceptable. It also omits error cases, but the provided information is sufficient for a correct 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 descriptions already cover all four parameters (100% coverage) with details on format and constraints. The description further clarifies revocation_signature by explaining the two supported signature schemes and the signer authority, adding meaning beyond the schema. It also reiterates the idempotency behavior via the parameter description. This enriches understanding beyond the schema alone.

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 'Use agentid_revoke to retire an Agent ID instantly,' a specific verb (retire) and resource (Agent ID). This clearly distinguishes it from siblings like agentid_issue and agentid_renew, which serve different lifecycle purposes. No ambiguity about what the tool does.

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 purpose makes it obvious when to use the tool, but there is no explicit guidance about when not to use it or how it differs from alternatives. It does not mention that renewal or verification should not be used for revocation. The context of retiring an Agent ID is implied, but explicit routing to alternatives is absent.

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 provide idempotentHint=true and readOnlyHint=false, and the description adds substantial context beyond those: identical response shape for all statuses, unknown IDs never error, the x402 v2 PAYMENT-SIGNATURE header requirement, the $0.25 cost, and the nuance that replaying an idempotency key returns the original receipt even with different inputs. This significantly exceeds annotation data.

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 compact paragraph that front-loads purpose and then provides status behavior, payment protocol, and cost. Each sentence carries distinct, non-redundant information. It is slightly dense but no sentence is wasted, making it an efficient and well-structured 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?

Given the 100% schema coverage, output schema, and rich annotations, the description fills the remaining gaps: clear purpose, when to use, unknown-ID behavior, and payment/auth details via the x402 header and URL. It does not mention rate limits in prose, but those are in the schema, and the doc link supplements. The description is 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% and both parameters have detailed descriptions in the schema (agent_id format and rate limit, idempotency_key UUID v4 and scoping rules). The description adds no parameter-level meaning beyond a general 'POST the tool inputs as JSON,' so the baseline of 3 is correct.

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: 'check an Agent ID's current standing: valid, revoked, expired, or unknown.' It distinguishes from sibling issue/renew/revoke by focusing on verification, and the mention of identity chain, inclusion record, and attestation envelope clearly differentiates it from other check tools like verified_check.

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

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

It explicitly gives the trigger condition: 'Use agentid_verify when you want to check an Agent ID's current standing.' It does not name alternatives or exclusions, but the clear context and paid nature make usage conditions understandable. It could improve by explicitly routing to issue/renew/revoke for other actions.

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

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

The description goes well beyond the idempotentHint and readOnlyHint annotations: it reveals the probe is unpaid, the response is signed, the semantic of UNVERIFIED, the x402 payment header requirement, the cost, and the target URL. This gives the agent a realistic model of the tool's behavior with no contradiction against annotations.

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

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

The description is dense and front-loaded with the most important usage condition, followed by behavior, protocol, and payment details. It is longer than strictly necessary due to the URL and docs link, but every sentence contributes operational information an agent needs.

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

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

Given the rich output schema, idempotency info in the parameter schema, and annotations, the description completes the picture: it gives the endpoint, payment amount and chains, required header, decision vocabulary, and honest-default behavior. An agent has enough information to invoke and interpret the tool correctly.

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

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

The input schema has 100% description coverage for all six parameters, so the schema already carries the semantic load. The description adds invocation-level context (endpoint, payment, header) but does not add per-parameter meaning beyond what the schema documents, so a 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 clearly states the tool's purpose: produce a go/no-go verdict before an agent acts on a provider, and lists the exact decision values. It is more specific than a vague 'check' but does not explicitly contrast sibling tools like preflight_check or verified_check.

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

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

It explicitly says when to use the tool ('when you need a go/no-go verdict BEFORE an agent acts on a provider'), which is a strong usage condition. However, it does not mention exclusions or alternatives, so the guidance is complete on the 'when' but not on the 'when not' side.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=true, destructive=false), but the description adds crucial operational context: payment required ($222 USDC on Base/Arbitrum), x402 v2 PAYMENT-SIGNATURE header, POST to paid_url. That's a lot the agent can't get from structured fields alone.

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

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

Front-loaded with purpose, then logistics, then pricing and URL. Reasonably efficient, but the payment and URL details are somewhat crammed; could be better structured without losing content.

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, stateful tool with an output schema, the description covers the key non-obvious facts: payment protocol, auth header, endpoint URL, and pricing. Missing only explicit indication of what receipt object returns (output schema exists), so it's essentially complete.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema (including the detailed idempotency_key semantics). The description adds no parameter-level detail, which is acceptable at high coverage – 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 states a specific verb (notarize/verify) and resource (evidence of work → signed receipt), naming the mechanism ('mint a portable signed receipt'). It doesn't distinguish itself from plausible siblings like cert or trust_report, but the purpose 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?

Says 'Use attest when you want the Embassy to notarize your work', which is an implied trigger, but gives no contrast with sibling verification tools (cert, prove_it, trust_report) or when-not-to-use. Adequate but thin.

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

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

Annotations already cover readOnly=false, idempotent=true, destructive=false, so the safety profile is partly structured. The description adds genuinely non-structured context: cost ($0.25), payment rail (USDC on Base or Arbitrum One), a paid URL, and the privacy model ('You keep the document; we never see it'). It does not restate the idempotency behavior, which the schema already handles.

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

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

The core purpose is front-loaded, but '$0.25' appears twice (once as a bare price, once restating 'Paid tool — $0.25'), and the paid URL is duplicated framing. The repetition costs space without adding information.

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

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

An output schema exists, so return values need not be explained. For a paid mutation-style tool, the description covers cost, payment chain, and privacy, which is enough for correct invocation. Minor gap: no statement of latency/turnaround for the attestation or what the receipt contains beyond the 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% and the schema fully documents document_hash, document_name, and idempotency_key, including the UUID v4 and replay semantics. The description's mention of SHA256 overlaps with the schema rather than extending it. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb and resource: it timestamps a document's SHA256 hash into a signed attestation proving existence at a point in time. The mechanics ('we timestamp your document's SHA256 hash') are concrete. It does not explicitly distinguish itself from siblings like attest or prove_it, which appear to overlap in the timestamping/proof space.

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

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

Usage is implied by 'proof your document existed at a point in time,' giving the agent a clear scenario, but there is no explicit when-to-use vs. when-not, no prerequisites, and no named alternative among the sibling tools (attest, prove_it, trust_report). The agent must infer selection.

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

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

Beyond the annotations, the description discloses the paid nature ($0.25), payment network, required x402 v2 PAYMENT-SIGNATURE auth, the fact that results are sealed into a signed receipt, and the actual paid URL. This is significant behavioral context an agent needs before invoking a paid tool.

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

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

The description is compact and front-loaded: the use case and return value come first, followed by auth/payment/URL details. Every sentence contributes operational value; there is 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?

With an output schema present and the schema covering all parameters, the only missing operational context was payment/auth and endpoint details, all of which are provided. A link to the x402 docs fills the remaining procedural 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?

All three parameters are already documented with 100% schema coverage, including the idempotency-key semantics, so the description carries no additional parameter meaning. Baseline 3 is appropriate because the schema does the heavy lifting and the description need not repeat it.

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

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

The description names a concrete operation ('returns the current price-move alert list') and pins the domain precisely ('when GPU spot prices made a significant move'). This makes it immediately distinguishable from sibling tools like compute_spot_prices, which would return current prices rather than alerts.

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 opens with an explicit 'Use compute_alerts when...' trigger, giving the agent a clear condition for selection. It then supplies the exact invocation details for this paid tool: POST JSON to paid_url with the x402 v2 PAYMENT-SIGNATURE header, cost, and supported networks.

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

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

The description adds substantial behavioral context beyond the annotations: it discloses that this is a paid tool ($0.25 USDC on Base or Arbitrum One), requires an x402 v2 PAYMENT-SIGNATURE header, returns a signed receipt, and enforces idempotency-key replay semantics. It also clarifies that prices are ephemeral asks, not delivered-cost guarantees. This is consistent with the idempotentHint=true annotation and adds meaningful operational detail.

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

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

The description is front-loaded with the core purpose and then efficiently covers payment, idempotency, and data semantics. It is somewhat dense and includes a placeholder-like 'paid_url' reference alongside the explicit paid URL, but every sentence contributes necessary operational information without significant 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?

For a paid, idempotent market-history tool with an output schema, the description is remarkably complete. It covers what the tool returns, how to invoke it (POST, header, URL), payment terms, idempotency behavior, and the ephemeral nature of prices. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds useful context like 'per-GPU cheapest/median/offer counts' and 'whole-market when no GPU is named,' but it does not substantially extend the parameter-level meaning beyond what the schema provides. 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 opens with a specific verb and resource: 'Use compute_history when you need GPU compute market history.' It clearly defines the output as a bounded time series of per-GPU cheapest/median/offer counts, and distinguishes the whole-market variant when no GPU is named. This goes well beyond the generic title and differentiates it from sibling tools like compute_spot_prices.

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 states when to use the tool ('when you need GPU compute market history') and provides a clear branching condition ('whole-market history when no GPU is named'). It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

The description carries behavior the annotations do not: this is a paid call ($0.25 per snapshot, USDC on Base or Arbitrum One), requires an x402 v2 PAYMENT-SIGNATURE header to GET the paid URL, returns a point-in-time snapshot whose listings may already be gone, and explicitly performs no rent/reserve/hold action. With annotations silent on cost and auth, this is exactly the disclosure an agent needs.

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 return semantics, then boundaries, then payment mechanics. Dense and mostly waste-free, though the two payment sentences overlap ('Paid tool — $0.25 per snapshot...' and 'Paid URL: https://...') in a way that could be tightened.

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

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

With an output schema present, the description needn't explain return shape, and for a 7-param, zero-required tool it still covers scope, defaults, cost, auth header, and interaction boundaries. 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 coverage is 100%, so baseline is 3, but the description adds semantics not in the schema: the default for type (ondemand) is unstated in the schema, and 'Omit gpu for the per-class snapshot' tells the agent what a missing filter actually returns. That is genuine value beyond the field descriptions.

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: 'One timestamped snapshot of observed GPU asks,' and sharpens it with 'not quotes — listings may be gone when you rent.' An agent immediately knows this is a read of live GPU price listings. It does not, however, contrast itself with the nearby compute_history / compute_alerts siblings, so differentiation is left implicit.

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

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

Gives real conditional guidance: 'Omit gpu for the per-class snapshot' and 'Default type ondemand; use bid for the interruptible spot auction.' It also draws a firm boundary — 'Observes only; never rents, reserves, or holds.' Missing is any explicit when-to-use-this-vs-a-sibling routing (e.g. vs compute_history), which is the only gap.

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

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

Annotations cover safety (readOnly=false, idempotent=true, destructive=false), but the description adds the crucial non-structured context: it is a paid tool at $25.00 in USDC on Base or Arbitrum One, requires an x402 v2 PAYMENT-SIGNATURE header POSTed to paid_url, and returns a verification report plus a signed receipt. This is rich operational detail beyond the annotations (minor tension with openWorldHint=false given external link checks, but not a real contradiction).

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

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

Purpose and payment mechanics are front-loaded and each sentence is largely functional, but there is a marketing-flavored filler clause ('You pay for the pass, never the method') and the paid URL appears twice ('paid_url' and an explicit 'Paid URL'). Minor redundancy 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?

Given 5 parameters, an enum, and an existing output schema, the description supplies everything needed to invoke it: payment flow, endpoint, required header, and the return shape. It omits no critical calling information, though it never mentions rate limits or the openWorld nuance of external link checks.

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 draft, links, register, required_terms, and idempotency_key. The description reinforces the intent (chosen register, verified links, required terms) but adds no syntax or format detail beyond the schema, which is the expected baseline-3 case.

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 verb (correct) and resource (draft copy) and enumerates the concrete sub-operations: voice-register transformation, formatting normalization, link liveness verification, required-term confirmation, and black-box leak scanning. No sibling among the agentid_*/compute_*/kit tools overlaps, so the purpose is unambiguously distinguishable.

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?

Opens with 'Use correct_copy when you want a $25 correction pass over draft copy,' giving clear context and a cost basis for selection. It does not state when-not-to-use or name an alternative, but no sibling tool competes for this task, so the omission is minor.

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 materially more: this is a paid tool costing $222.00 in USDC on Base or Arbitrum One, requires an x402 v2 PAYMENT-SIGNATURE header, and returns a signed Outcome Receipt. Payment mechanics and cost are exactly the kind of behavioral context annotations cannot carry. It does not describe failure/refund behavior or latency, keeping 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?

Front-loaded with the use case, then payment/auth mechanics and the paid URL. Every sentence carries information (capabilities, transport, payment, price). It is dense but not padded; only the bare docs link is low-value filler.

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

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

With an output schema present, return values need not be explained. The description covers the essentials an agent needs to invoke a paid, non-idempotent-looking-but-idempotent tool: what it does, how to pay, where to POST. Error handling and what the receipt contains are left implicit, which is a minor gap.

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

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

Schema description coverage is 100% and the idempotency_key description in the schema is unusually thorough (replay semantics, per-tool/per-payer scoping). The description adds no parameter-level detail 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?

States a specific composite capability: URL liveness, content verification, TLS fingerprint, x402 trust verdict, and document timestamp composed into a signed Outcome Receipt. That is far more specific than the name 'diligence_pack' or title 'Compute History' (which arguably misleads), and it is distinguishable from single-purpose siblings like trust_report or assurance_check. It stops short of explicitly contrasting itself with those siblings, so not a 5.

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

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

Gives an explicit trigger: 'Use diligence_pack when you need the full proof suite in one call', which implies the alternative is calling the individual checks separately. It does not name those alternatives or state when NOT to use this (e.g. for a single check, or when budget matters), so it is clear context without exclusions.

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

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

Beyond the annotations (readOnly=false, idempotent=true, openWorld=false), the description discloses substantial operational context: it is a paid tool costing $0.25 in USDC on Base or Arbitrum One, requires an x402 v2 PAYMENT-SIGNATURE header, is invoked via POST to a specific paid_url, and that key custody stays with the caller. That meaningfully raises the bar above what the annotations provide, though rate limits and return shape are not discussed.

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 a dense run-on mixing useful facts (cost, payment mechanism, URLs) with unearned promotional asides such as 'Every trap — earned ourselves' and 'Your keys; custody never leaves you.' The seven steps are inlined as prose rather than front-loaded as a scannable list, so the signal-to-noise ratio is poor.

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

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

An output schema exists, so return values need not be explained, and the description covers the invocation essentials: method (POST), payment protocol, price, accepted chains, and the paid URL. What an agent needs in order to call it correctly is largely present, with only minor gaps around failure/refund behavior.

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

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

Schema coverage is 100% and the single idempotency_key is fully documented in the schema itself, so the schema carries the burden. The description adds no parameter-level detail (format, uniqueness scope) beyond what is already structured, which matches the baseline 3 for high-coverage schemas.

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 eventually conveys that the tool delivers a 7-step machine guide for onboarding an agent to Farcaster, with the concrete sub-steps (bridge funding, FID registration, Ed25519 signer, EIP-712 domains, fname claim, profile, publish). However, the purpose is buried under marketing slogans and the title 'Compute History' does not match the name or body, which muddies selection. It never explicitly names or distinguishes itself from the obvious sibling nostr_kit.

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 a loose implied condition ('Get an agent onto Farcaster'), but no explicit when-to-use, when-not-to-use, or named alternative. With 22 siblings, including nostr_kit and the agentid_* family, the absence of routing guidance leaves the agent guessing between near-duplicates.

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 signal readOnly/idempotency/destructive hints; the description adds important invocation behavior: POSTing JSON to a specific paid_url with an x402 v2 PAYMENT-SIGNATURE header, binding the signed quote to the exact amount, and receiving a non-work receipt. It also discloses supported networks (Base/Arbitrum One), which is beyond the schema, with no contradiction of annotations.

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

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

The description is front-loaded and contains all essential mechanics, but the last sentence bundle repeats 'open amount,' the $0.01–$222.00 range, and USDC, adding only the network detail. This minor redundancy keeps it from being a 5, but it remains reasonably compact.

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 payment tool, the description supplies the payment URL, protocol header, amount bounds, networks, and quote-binding behavior, while the output schema removes the need to describe return values. Nothing necessary for a correct call appears missing.

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

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

Schema coverage is 100% and both amount_usd and idempotency_key already have rich descriptions (range, decimals, key generation, replay semantics). The tool description mostly repeats the amount range and open-amount nature, so it adds little beyond the schema; 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 identifies an exact action — making an open-amount patronage gift in USDC — and states concrete parameters (amount range, receipt type, payment mechanism) that distinguish it from any sibling tool. It is far more specific than the name 'give' alone and clearly names the resource supported (Embassy).

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 first sentence states the purpose and the description makes the payment-vs-work distinction explicit with 'patronage receipt, not a work receipt,' providing a clear when-not signal. It doesn't name alternative sibling tools, so it doesn't reach the top score, but the context is clear enough.

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 genuinely useful operational context: it is a paid tool ($0.25), requires a POST to paid_url with an x402 v2 PAYMENT-SIGNATURE header, and settles in USDC on Base or Arbitrum One. That payment/auth requirement is exactly the kind of trait annotations cannot convey, though return behavior is left to the output schema.

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

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

The text is a dense run-on that repeats the $0.25 price twice, stacks marketing filler ('No chain fees, no signup, no recovery', 'Earned from our live presence'), and buries the payment mechanics behind the sales pitch. It is not front-loaded, and several clauses do not earn their place.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description supplies the payment flow and step list, though it never clarifies the form in which the guide is returned.

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

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

The single parameter (idempotency_key) is fully documented in the schema at 100% coverage, so the schema carries the burden. The description adds nothing about the parameter semantics, which is the expected baseline here.

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 concrete deliverable (a 4-step machine guide for onboarding an agent to Nostr) and enumerates its contents: secp256k1 keygen, NIP-11 relay reads, NIP-01 signing, publish order. It does not distinguish itself from the analogous sibling farcaster_kit, and the marketing framing ('Earned from our live presence') obscures the exact output format, but the verb+resource is identifiable.

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

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

Usage is implied by 'Get an agent onto Nostr' and the listed preconditions, so an agent can infer when this applies. There is no explicit when-not guidance or comparison to sibling kits such as farcaster_kit, leaving the choice to inference.

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

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

With annotations present, the description still adds substantial context beyond them: it discloses that this is a paid tool ($0.15 USDC on Base or Arbitrum One), that invocation requires POSTing JSON to paid_url with an x402 v2 PAYMENT-SIGNATURE header, that exactly one fetch occurs at request time, and that a signed receipt with per-condition results is produced. That covers cost, auth mechanism, and execution model — exactly the behavioral detail annotations cannot express.

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

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

The purpose and trigger are front-loaded in the first sentence, followed by execution model and payment logistics. Nothing is wasted, though the payment/docs sentences and the duplicated 'Paid URL' line make it denser than the check semantics require; a payment block would be cleaner separated from the behavioral 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?

For a 6-parameter paid endpoint with an output schema, the description covers purpose, invocation mechanism, cost, and idempotency expectations (the latter also in-schema). It omits failure semantics — what a fail verdict looks like, retry/refund behavior on payment failure, or rate limits — which are the remaining gaps for a tool whose whole output is a 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?

Schema coverage is 100% and the schema already documents defaults, caps, redirect limits, and idempotency-key semantics in depth. The description adds a small amount the schema does not state outright: that the conditions are combined with 'and/or' into a single verdict and that expect_status defaults to 200 when omitted. Meaningful but modest value over a complete schema, so slightly above 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 first sentence states a precise verb and outcome: 'Use ping when you need a pass/fail verdict that a URL serves expected content,' then enumerates the three checkable conditions (status, body substring, JSON field match). An agent can tell exactly what this tool returns without opening the schema, and it is clearly distinct from wallet/identity siblings like agentid_verify or give.

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

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

It gives an explicit use condition ('when you need a pass/fail verdict that a URL serves expected content') and the shape of that verdict. However, it names no alternatives and gives no when-not guidance, even though siblings such as preflight_check, assurance_check, proveit_verified_check, and watch plausibly overlap with URL/endpoint checking, leaving the routing decision to inference.

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

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

The description adds significant behavioral context beyond the annotations: it is a paid operation at $0.25 USDC on Base or Arbitrum One, requires an x402 v2 PAYMENT-SIGNATURE header, POSTs inputs to a specific URL, and returns a signed verdict with a proof envelope. It does not contradict the idempotentHint, and the schema covers idempotency replay 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 front-loads the core purpose and outcome, then supplies cost, network, auth header, and paid URL in compact form. It is slightly run-on and packs many details into dense clauses, but every sentence carries useful operational information.

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

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

Given the nested schema and output schema, the description is reasonably complete: it covers purpose, payment cost, network, endpoint, auth mechanism, and verdict type. The main missing piece is explicit when-not-to-use guidance, but the pre-spend framing and dry_run parameter largely compensate.

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%, with detailed nested descriptions for subject, intent, context, and idempotency_key. The description itself contributes little parameter-level meaning beyond saying inputs are POSTed as JSON, so the baseline of 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 clearly states the tool's function: run a pre-spend check that returns WHO is paid, WHAT is delivered, what CHANGED, the COST, and WHO TAKES A CUT, plus a signed PROCEED/BLOCKED verdict. It is specific about the resource and outcome, though it does not explicitly distinguish itself from sibling verification tools like assurance_check or verified_check.

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

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

The description gives an explicit trigger condition: use preflight_check before spending on a paid tool or endpoint. It also gives practical guidance about the paid nature and the dry-run option in the schema, but it does not state when not to use it or name alternatives, 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses that this is a paid x402 v2 call at $0.25 in USDC on Base or Arbitrum One, the required PAYMENT-SIGNATURE header, and that the receipt is cryptographically signed. That is meaningful context the structured fields do not carry. It omits failure/rate-limit behavior — notably whether the fee is still charged when the check returns non-200 — which prevents 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?

Four sentences, front-loaded with the trigger condition, then payment, then pricing/link, then the endpoint. Every sentence carries information an agent needs to invoke the tool. It is slightly dense with pricing/URL detail that could be trimmed, but nothing is wasted or redundant.

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

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

For a two-parameter paid tool with an output schema (so return values need no explanation), the definition covers trigger, transport, auth, price, and receipt semantics — enough to invoke correctly. The remaining gap is behavioral edge cases such as non-200 outcomes and billing on failure, which a payment-gated tool arguably should state.

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 both url (redirect/timeout/body-cap limits) and idempotency_key (replay semantics, per-payer scoping) in detail. The description adds nothing parameter-specific beyond the generic instruction to POST the inputs as JSON, 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 gives a specific verb+resource: it fetches a URL once and seals the result into a signed Outcome Receipt proving HTTP 200 liveness. That is far more precise than the title alone and an agent can tell what it does. It stops short of 5 because it never distinguishes itself from near-neighbors in the sibling list such as proveit_verified_check, preflight_check, or ping, which plausibly overlap.

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 opens with an explicit trigger condition — 'Use prove_it when you want signed cryptographic proof that a URL is live and returning HTTP 200' — so the agent knows the use case. It also states the transport requirement (POST JSON to paid_url with an x402 PAYMENT-SIGNATURE header). It does not name alternatives or state when NOT to use it, which keeps it at 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 already cover the safety profile (not read-only, idempotent, not destructive, closed-world), and the description adds substantial extra context: $0.25 per check, x402 v2 payment via a PAYMENT-SIGNATURE header, POST to paid_url, and USDC on Base or Arbitrum One. That is exactly the behavioral disclosure an agent needs for a paid tool.

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

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

The description is front-loaded with purpose and conditions, and the operational details are compact. The price is repeated ('$0.25 per check' and '$0.25, USDC on Base or Arbitrum One'), which is minor redundancy but not wasteful.

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

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

With an output schema present and 100% schema coverage on three parameters, the description only needs to add payment/transport and scoping context, which it does fully. Nothing an agent needs to invoke the tool 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 coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema: 'single class when gpu is named' versus 'cheapest rentable ask per class' when omitted, which clarifies how the gpu parameter changes output scope.

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 — producing a signed Outcome Receipt for a compute-price check with a timestamped GPU spot market snapshot. It is clearly distinguishable from siblings like compute_spot_prices (raw prices) and prove_it by the emphasis on a signed, sealed receipt.

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 an explicit trigger: 'Use proveit_verified_check when you need a signed receipt that a compute-price check actually ran.' It does not name alternatives or when-not-to-use, but the condition is clear enough to route an agent.

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 cover read-only, idempotency, and destructiveness), the description discloses that storage is opaque and undecryptable by the Embassy, that the blob enters a human operator review queue, that a signed hash receipt is returned, and that payment is required via an x402 PAYMENT-SIGNATURE header. These are substantive traits the annotations cannot express.

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

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

The trigger condition is front-loaded, followed by behavioral guarantees, invocation format, and payment terms. It is denser than most definitions but each clause carries real information; only the payment URL sentence is mildly redundant with the 'Paid URL' line.

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

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

An output schema exists, so return values need not be explained. Combined with the payment prerequisites, transport instructions, and escrow behavior, an agent has everything needed to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the idempotency-key semantics. The description confirms the blob is opaque and ties the receipt to its hash, but adds no syntax or format 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?

The description states a specific verb and resource: escrow a client-encrypted recovery blob with the Embassy. It further pins down the nature of the operation (opaque storage, human review queue, signed receipt), so an agent can distinguish it from every sibling in the 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 opens with an explicit when-to-use trigger ('when you want to escrow a client-encrypted recovery blob') and details the invocation mechanics. It does not name alternatives or exclusions, but no sibling tool overlaps this function, so there is little to exclude.

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 purchase/licensing nature, the x402 v2 PAYMENT-SIGNATURE header requirement, private delivery with a signed receipt, supported chains (Base or Arbitrum One), and the paid URL. This gives the agent substantial behavioral context not present in 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 purpose is front-loaded and well stated, but the description is a single dense paragraph that repeats pricing and mixes payment protocol, URL, and licensing details. It is informative but could be more tightly structured with separators between pricing, protocol, and delivery behavior.

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

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

Given the rich input schema and output schema, the description covers the essential operational details: cost, payment method, network, paid URL, header, and receipt. It does not discuss explicit alternatives or edge cases like refunds, but those are not critical for correct invocation.

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

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

Schema description coverage is 100%, and the bundle property already documents the $222/$444 tiers and defaults. The description repeats this rather than adding new parameter-level meaning, so the baseline of 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 opens with an explicit 'Use research_paper when you want to buy a research paper' and then specifies the two purchase tiers and their prices. This clearly identifies the tool as a paid purchase action for a specific resource, distinct from verification/provenance siblings like prove_it or verified_check.

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

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

The description explicitly states the intended use case ('when you want to buy a research paper') and provides pricing and delivery tiers. It does not name sibling tools or explicitly say when not to use it, so it stops short of full alternative routing guidance.

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

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

Far beyond the annotations, the description discloses that this is a paid $0.25 x402 tool requiring a PAYMENT-SIGNATURE header, that results carry LIVE/RECENT/SNAPSHOT/UNVERIFIED freshness labels, that empty results return WAIT rather than invented data, that a signed receipt is produced, that quotes may be stale, and that no trades are placed. These are exactly the operational traits an agent needs before spending money.

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

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

It is front-loaded with the price and the request shapes, which is good, but the middle is a chain of em-dash fragments and parentheticals that is denser than it needs to be. Most sentences carry real information, yet the packaging makes it harder to scan than the content warrants.

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 detail is not needed, and the description still covers payment mechanics, idempotency, budget gating, and result labeling. The remaining gap is the absence of any sibling/alternative framing, which matters in a 23-tool surface.

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 query, max_rows, objective, budget_usd, and idempotency_key, including example query strings and supported objective values. The description adds only the informal query phrasing ('COMPARE two tickers', 'BEST a theme'), which largely duplicates 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?

The description states a concrete action (shop an economic idea for $0.25) and enumerates the three request shapes it accepts: a single ticker scan, a COMPARE head-to-head, or a BEST theme. That is enough for an agent to know what comes back (ranked expressions within a budget). It loses a point because the name 'ticker_shelf' and the title 'Compute History' point in different directions and the description never reconciles them.

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

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

It describes the input patterns it supports (ticker / COMPARE / BEST) and notes that an empty set returns WAIT, which implies a budget-gating use case. However, it never says when to prefer this over any sibling (e.g. compute_spot_prices, compute_alerts) or what conditions make it the wrong choice, so routing is left to inference.

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

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

Beyond the annotations, the description discloses meaningful behavioral details: the tool is paid at $0.25 USDC on Base or Arbitrum One, requires an x402 v2 PAYMENT-SIGNATURE header, probes the target unpaid via GET with fallback to POST, and returns a signed verdict. It also explains idempotency behavior consistently with idempotentHint=true, including key-scoping and first-request-wins semantics.

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

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

The description is compact yet information-dense, front-loading the purpose before invocation details. Every sentence adds value: usage trigger, verdict semantics, payment mechanics, cost, networks, and the paid URL, with 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?

For a paid, externally invoked tool, the description supplies all necessary call mechanics: destination URL, required payment signature header, cost, supported networks, and an output verdict type. Since an output schema exists, the description does not need to enumerate return fields, and the included docs link covers deeper protocol details.

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 parameters url and idempotency_key are already fully documented in the schema. The tool description adds no extra parameter-level meaning beyond the schema's own descriptions, so the baseline score of 3 is appropriate.

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

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

The description states a specific action and resource: a buy/don't-buy decision on a candidate x402 endpoint, probed by the Embassy and returning PROCEED, VERIFY_FIRST, or DO_NOT_PAY. 'A decision, never a score' sharpens the boundary against scoring-style verification siblings, making the tool's identity 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 opening sentence gives an explicit trigger condition: 'Use trust_report when you need a buy/don't-buy decision on a candidate x402 endpoint.' It also clarifies the output is a verdict, not a score, and notes the paid nature of the call. It does not explicitly name alternative tools or state when-not-to-use, but the context is clear enough for correct selection.

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

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

Annotations only cover safety/idempotency hints, and the description adds substantially more: scheduled re-checks, receipt-per-change semantics, per-receipt billing with no subscription, the x402 v2 payment-signature header requirement, accepted chains (Base/Arbitrum One), price, and the paid URL. This is exactly the operational context annotations cannot carry.

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

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

The purpose is front-loaded in the first clause, followed by billing and invocation mechanics, which is the right order. Slight redundancy between 'No subscription — pay per fired receipt' and 'Paid tool — $222.00' plus the separate 'Paid URL' line, but nothing is genuinely wasteful.

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

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

With an output schema present, return values need not be explained, and the description fully covers purpose, pricing model, and how to actually invoke the paid endpoint. Combined with 100% schema coverage, an agent has everything required to call this 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%, and all three parameters (url, idempotency_key, check_interval_hours) are thoroughly documented in the schema itself, including replay and scoping rules for the idempotency key. The description adds no parameter-level detail beyond what the schema already provides, 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: it checks a URL on a schedule and fires a signed receipt on every change. An agent can tell it is a standing-monitor tool rather than a one-shot fetch. It does not, however, differentiate itself from siblings like compute_alerts or compute_history, and the title 'Compute History' is a poor match for the name 'watch', which adds friction.

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

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

'Use watch when you want standing coverage on a URL' gives an explicit trigger condition and implicitly contrasts with a one-off check. There is no when-not guidance and no named alternative for agents that only want a single check or a different alerting mode.

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