agent-embassy

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

Goes well beyond the annotations: discloses that the call is paid ($0.25 USDC on Base or Arbitrum One), that payment is made via an x402 v2 PAYMENT-SIGNATURE header, the exact paid URL, and that unverifiable principals are refused. Annotations cover safety/idempotency, and the description layers the payment and refusal semantics on top.

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 the verify alternative are front-loaded, followed by the payment mechanics; every sentence carries information. It is telegraphic and slightly crowded with endpoint/price detail, but nothing is redundant.

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

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

An output schema exists so return values need not be described. The description supplies the missing operational pieces an agent needs — payment protocol, header, endpoint URL, and the refusal rule — for a 10-parameter 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 all ten parameters are already documented in the schema. The description only restates the validity_days default ('defaults to standard') which the schema also explains, adding no new syntax or constraints. Baseline 3 applies 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?

States a specific verb and resource ('Issue an Agent ID'), defines the artifact as an attestation binding a pubkey to a verified principal, and explicitly distinguishes the neighboring verify operation ('Verify: agentid_verify'). An agent can tell this apart from renew/revoke/verify 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 the alternative for the verification path ('Verify: agentid_verify') and gives a gating condition ('unverifiable are refused'). It does not state when to prefer this over agentid_renew or how it relates to revoke, so it stops short of full when/when-not coverage.

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, and the description supplies the context those flags can't: the old ID is retired, payment is $0.25 in USDC on Base or Arbitrum One, and calls require an x402 v2 PAYMENT-SIGNATURE header POSTed to a specific paid URL. That is meaningful operational detail 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?

Front-loaded with the operation and its alternative, wasting no preamble. It is dense but several clauses are payment boilerplate (docs link, paid URL, currency), which is useful yet repeated information that crowds the core semantics slightly.

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 destructive, paid, signature-gated mutation, the description covers the effect on the old ID, the credential format, payment mechanics, and the alternative tool; return values are handled by the existing output schema, so 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 agent_id, revocation_signature, validity_days, and idempotency_key are already fully documented in the input schema. The description only echoes the validity_days default and hints at signing, adding little 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 ('Renew an Agent ID') plus its core effect ('fresh ID, same chain; the old retires'), which is enough for an agent to distinguish it from agentid_issue and agentid_verify 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 alternative case to a named sibling: 'Retire outright: agentid_revoke,' and the retire-vs-renew distinction is stated up front. It also notes that the renewal is signed 'like a revocation,' telling the caller which credential path applies.

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 destructive=true and idempotent=true, so the safety profile is covered. The description adds genuinely non-structured context: it is a paid call ($0.25 USDC on Base or Arbitrum One) requiring an x402 v2 PAYMENT-SIGNATURE header and a JSON POST to a specific URL. It stops short of saying what is destroyed downstream (credentials, attestations) upon retirement.

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 renew alternative are front-loaded in the first two clauses, and payment mechanics come after. A couple of fragments ("who signs, and how" and the signer pointer that merely redirects to the schema) pad the middle slightly without earning their place.

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

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

With an output schema present, return values need not be explained, and annotations carry the destructive/idempotent profile. The description still covers transport, payment, auth header and the docs link — only the post-revocation consequences are left unstated, which is a minor gap for a destructive 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 already thorough (signature envelope, idempotency scoping, ID format). The description only gestures at the signature ("sign as the revocation_signature field specifies — who signs, and how"), adding no format or signer detail 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?

"Retire an Agent ID instantly, with no successor" names a specific verb and resource plus a decisive scope qualifier (no successor). It also explicitly contrasts with the sibling agentid_renew ("Fresh ID, same chain"), so an agent can pick between the two without reading 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?

The revoke-vs-renew split is stated: revoke leaves no successor, renew gives a fresh ID on the same chain. That is real routing guidance, but there is no explicit statement of preconditions (e.g., when revocation is warranted, what happens to dependents) or exclusions beyond the single sibling comparison.

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

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

Goes well beyond the annotations: discloses that invocation is a POST of JSON with an x402 v2 PAYMENT-SIGNATURE header, the exact price ($0.25 USDC on Base or Arbitrum One), and the key behavioral guarantee that unknown IDs return 'unknown' and never error. This is consistent with readOnlyHint=false (paid write-style POST) and idempotentHint=true.

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

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

Front-loads the outcome set and the never-error guarantee, then the sibling routing, then payment mechanics and endpoint. Dense but every element is functional; the price/docs/URL sentences are slightly crowded together but all earn their place.

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

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

With an output schema present, return shape needn't be explained, and the description covers payment auth, cost, error semantics, and sibling routing. The only thing an agent might still want — rate-limit behavior — is left entirely to 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%, so agent_id format and the idempotency-key contract (replay behavior, per-payer scoping, example-key rejection) are already fully documented in the schema. The description adds nothing about parameters, so baseline 3 applies.

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

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

States the resource (Agent ID state) and the exact outcomes it returns — valid, revoked, expired, unknown — plus that chain and envelope are included. It distinguishes itself from siblings by pointing to agentid_issue and agentid_renew for lifecycle operations. The verb 'verify' is only implied via the name rather than spelled out, which keeps it just short of a 5.

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

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

Explicitly routes issuing to agentid_issue and extending to agentid_renew, giving the agent a clear sibling split. It also covers the payment mechanics needed to actually invoke it. It doesn't say when *not* to use it (e.g. what a revoke flow should call instead), so no 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?

Goes well beyond the annotations: discloses privacy ('we never see it'), the payment mechanism (x402 v2 PAYMENT-SIGNATURE header, $0.25 in USDC on Base or Arbitrum One), the paid endpoint, and a docs link. That is operational context an agent cannot get from readOnlyHint/destructiveHint alone.

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

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

Front-loads the core purpose before protocol logistics, and every sentence carries actionable information. The payment/protocol sentences are dense but justified for a paid tool, though they read a bit like boilerplate appended to the 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?

Covers purpose, privacy model, payment flow, and endpoint, and return values are covered by the output schema. Remaining gap is the absence of any contrast with attest_work for an agent choosing between the two attestation 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 description coverage is 100%, so the baseline is 3. The description's only parameter remark, 'document_name is an optional label,' restates what the schema already says and adds no syntax or format detail.

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

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

Opens with a specific verb and effect: 'Prove a document existed' via SHA256 hash into a signed, hash-chained attestation. It partially differentiates siblings by routing live URLs to check_url_custom, but never contrasts with the closely named attest_work, leaving the agent to infer the distinction.

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 alternative for a near-miss case ('Live URLs: check_url_custom'), which is exactly the kind of routing guidance that prevents mis-selection. It lacks a when-not-to-use rule for the attest_work sibling, so a small gap remains.

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 idempotent=true, openWorld=true, non-destructive, so the safety profile is covered. The description goes beyond them with the paid nature, the $222.00 USDC price on Base or Arbitrum One, and the x402 v2 PAYMENT-SIGNATURE handshake, which is the behavior an agent most needs to know before calling. It doesn't explain what the minted receipt looks like, but an output schema exists to cover that.

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

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

Purpose is front-loaded, then alternative, then payment mechanics, then the endpoint. It is terse and mostly waste-free, though the payment URL is referenced twice ('paid_url' and 'Paid URL:') and the price is stated separately from the payment protocol, which slightly fragments the call instructions.

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-destructive, idempotent write tool with full schema coverage and an output schema, the description supplies everything an agent needs in order to invoke it correctly: payment protocol, header, network, price, endpoint, and the sibling that covers documents instead.

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 four parameters in detail. The description's only parameter remark ('evidence_urls + evidence_hash optional') merely restates what the required list already shows and adds no 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 opening sentence gives a specific verb and resource ('Notarize work done anywhere... verify it and mint a signed receipt') and explicitly distinguishes itself from the closest sibling by scoping attest_document to document existence. An agent can tell the two attest tools apart 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 (attest_document) and the condition that selects it, and states the payment prerequisite and protocol needed to call it. What's missing is guidance on when to supply evidence_hash versus evidence_urls, or when not to attest at all.

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 billing model ('receipt and charge only on change'), the concrete price ($222.00, USDC on Base or Arbitrum One), the payment protocol version, and the endpoint. What's missing is lifecycle context for a standing subscription: how a watch is stopped, cancelled, or what happens on payment failure.

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

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

Front-loaded with the core concept and the sibling disambiguation, with no filler sentences. It is dense and somewhat run-on (payment, pricing, protocol, and docs link packed into the tail), but every clause carries information an agent needs.

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

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

An output schema exists and parameters are fully described, so the description only needs to cover routing and payment behavior — which it does thoroughly. The one gap is that recurring-watch lifecycle (cancellation, renewal, what happens when a check fires) is never mentioned.

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 url, idempotency_key, and check_interval_hours are already fully documented — including the max of 168 and min of 1. The description only restates the 24-hour default, which the schema already declares, so it adds nothing beyond the structured fields.

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 ('standing URL check') and immediately names the sibling it is not: 'One-time check: check_url_custom.' The scope distinction between a recurring watch and a one-shot check is unambiguous 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?

Explicit routing is given ('One-time check: check_url_custom'), plus the default cadence (check_interval_hours defaults to 24) and the invocation mechanics (POST inputs as JSON to paid_url with an x402 v2 PAYMENT-SIGNATURE header, with a docs link). An agent knows both when to pick this tool and how to call 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 give a broad safety profile (openWorld, idempotent, non-destructive), but the description adds information annotations cannot: this is a paid call ($0.001 USDC on Base or Arbitrum One), it requires an x402 v2 PAYMENT-SIGNATURE header and a JSON POST to a specific paid_url, and status defaults to 200. That payment/authorization context is material for an agent deciding whether and how to invoke it. Missing: what happens on a failing check (does the fetch still bill?) and any rate limits.

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

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

The sentences are individually short and the payment/pricing information is front-loaded enough to be actionable, but the ordering is choppy: purpose, sibling routing, payment mechanics and pricing are interleaved with no paragraphing. Several fragments ('Default status 200.' 'Public proof: check_url_sealed.') read as telegraphic shorthand rather than structured guidance.

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

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

An output schema exists, so the description need not explain the receipt's structure, and idempotency replay semantics are fully covered in the schema. For a 6-parameter, open-world, paid network tool, the description does cover cost, payment protocol, endpoint handling limits (via schema) and the three assertion modes. The only real omission is failure-mode billing and error 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 description coverage is 100%, so the schema already documents url, expect_status, idempotency_key, expect_json_path, expect_json_equals and expect_body_contains in detail. The description only restates the three condition types and the 200 default, adding no syntax, precedence, or interaction rules beyond the schema. Baseline 3 is the correct ceiling 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 opening clause names the resource (a URL) and the check types (status, substring, JSON value) with a concrete output shape (pass/fail receipt), which is far more specific than a bare 'check URL'. It also gestures at the two siblings (check_url_sealed, check_url_changes), though the labels 'Public proof' and 'Watch' are too terse to fully differentiate the family.

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 names alternatives ('Public proof: check_url_sealed', 'Watch: check_url_changes') but never states the conditions under which an agent should pick this one over them. The reader must infer that 'public proof' and 'watch' mean publishing and recurring monitoring respectively. 'Your conditions, one fetch' implies a one-shot custom assertion but does not say when that is preferred over the alternatives.

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

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

Goes well beyond the annotations by disclosing that the tool is paid ($0.25 USDC on Base or Arbitrum One), requires an x402 v2 PAYMENT-SIGNATURE header, posts inputs to a specific paid URL, and produces a signed receipt from a single fetch. These are material invocation and payment details the annotations do not provide.

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

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

The description is compact and front-loads the proof purpose before naming the alternative and payment mechanics. It is dense with necessary technical terms, though the opening phrase is more marketing-like than direct.

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

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

Given an output schema exists, the description need not explain the receipt structure. It covers the fixed condition, alternative tool, payment protocol, cost, endpoint, and invocation method, leaving no major gap 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%, and the schema already fully explains both url and idempotency_key, including redirects, timeout, body cap, and replay behavior. The description adds call mechanics but no parameter 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?

States a specific capability: prove a URL was live at a given moment by fetching once and sealing the transcript in a signed receipt, with HTTP 200 fixed as the condition. It also names check_url_custom for custom conditions, so the agent can distinguish it from the sibling without opening the schema.

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

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

Explicitly says to use check_url_custom instead when the caller wants their own conditions, and the fixed HTTP 200 scope makes the default use case clear. It does not mention other siblings such as check_url_changes, so it is not fully exhaustive.

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 critical invocation behavior: the tool is paid, costs $0.25 USDC on Base or Arbitrum One, requires POSTing inputs as JSON to the paid URL, and needs an x402 v2 PAYMENT-SIGNATURE header. It also mentions that results come in a signed receipt, which is important behavioral context not present in the annotations or 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 definition is compact and front-loads the core purpose before alternatives and payment instructions. The fragmented phrasing is dense but largely purposeful, though it could be slightly clearer in separating tool behavior from payment mechanics.

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

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

Given the output schema exists and the input schema is fully described, the description supplies the remaining essential context: payment model, authentication header, HTTP method, endpoint, cost, and sibling differentiation. An agent has enough information to invoke 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?

Schema description coverage is 100%, so parameters such as gpu and idempotency_key are already fully documented. The description only restates that limit defaults to 25, which is already in the schema, and adds no extra parameter semantics beyond that.

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

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

The description states a specific resource and scope: significant GPU spot price moves returned as alerts in a signed receipt. It explicitly distinguishes itself from compute_spot_prices for live snapshots and compute_history for past data, so an agent can select it without opening sibling schemas.

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

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

It names the alternatives and the conditions that select them: compute_spot_prices for live snapshots and compute_history for past data. The opening phrase 'significant spot moves' also clarifies that this tool is for alerting on notable moves rather than raw current or historical prices.

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 real behavioral context beyond annotations: a paid POST to a specific paid_url with an x402 v2 PAYMENT-SIGNATURE header, $0.25 in USDC on Base or Arbitrum One, plus a docs link. That explains why readOnlyHint is false despite the tool being a data read. It does not discuss what happens on payment failure / insufficient funds or the receipt's verification semantics, which is the main remaining gap for a paid endpoint.

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 alternatives, then payment mechanics and endpoint — a sensible information order with no wasted clauses. The fragmentary, colon-separated style is compact but slightly reads as notes rather than prose, which 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?

Everything an agent needs to invoke it is present: endpoint URL, transport (POST JSON), auth header scheme, price and chains, plus sibling routing. Return values are covered by the output schema and parameters by the 100%-covered input schema, so no further description content is required.

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%, including the idempotency_key replay semantics, so the schema already carries parameter meaning. The description only restates the 'limit defaults to 50' default and adds no filtering/syntax detail for gpu beyond what the schema provides. 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 the resource precisely (GPU market history: cheapest and median asks per class, delivered as a signed receipt) and names the sibling it must not be confused with (compute_spot_prices for live data). The telegraphic 'GPU market memory' opener lacks an explicit verb, but the following colon phrase removes any ambiguity about what is returned.

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

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

Routing is explicit via 'Live: compute_spot_prices. Moves: compute_alerts.', which tells the agent which sibling to pick for the other two data shapes. It stops short of an explicit exclusion sentence such as 'do not use for real-time quotes', but the contrast is clear enough to act on.

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?

The description usefully discloses payment requirements — $0.25 USDC on Base or Arbitrum One, an x402 v2 PAYMENT-SIGNATURE header, and POSTing to a paid URL — which is valuable beyond the annotations. However, it directly contradicts openWorldHint=false by stating that the tool POSTs to an external paid URL (https://aemb.pro/v1/check/proveit-verified), meaning it does interact with an external service.

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 contains no filler; each clause carries operational or routing information. It is somewhat telegraphic and repeats a few schema details, but it remains short and functional.

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

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

Given the output schema exists, the description need not explain return values, and it covers the key operational context an agent needs: paid access, payment header, cost, network, endpoint, alternative sibling, and parameter defaults. Nothing essential for correct 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 the schema already documents all three parameters including defaults and idempotency behavior. The description repeats the type default and gpu omission but adds no syntax or meaning beyond the schema, 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 states a specific outcome — GPU price data with a sealed proof, snapshot, cheapest ask per class, and signed receipt — and explicitly distinguishes it from the raw data sibling, compute_spot_prices. An agent can tell what this tool provides and how it differs from the alternative.

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 (compute_spot_prices for raw data) and gives parameter defaults, but does not explicitly say when to prefer the sealed version versus the raw one beyond the implication of 'sealed proof'. The routing hint is clear, though not fully framed as when/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?

Goes well beyond the annotations by disclosing the price ($25 USDC on Base or Arbitrum One), the x402 payment handshake, the required header, and that link verification is HEAD-with-GET-fallback, 8s timeout, redirects not followed. The meaning of 'leaks scanned' is left vague, and the idempotentHint/readOnlyHint semantics are only explained in the schema, not 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?

The value proposition and deliverable are front-loaded, which is good, but the price is stated twice ($25.00 at the start and again in the 'Paid tool — $25.00' clause) and the docs URL plus paid URL stack up at the end. Redundant price restatement and trailing link boilerplate cost it 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, the description needn't enumerate return fields, and it still names the deliverables. Payment flow, auth header, token/network, and the paid URL are all covered; only the vague 'leaks scanned' claim and the absence of any failure/timeout behavior for the paid call leave small gaps.

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

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

Schema description coverage is 100%, so parameters are already fully documented; the description only adds 'register sets the voice,' which mostly restates the enum already in the schema. No additional syntax, interaction, or constraint information is added for draft, links, required_terms, or idempotency_key beyond the schema.

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

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

Names a concrete verb+resource (a $25 correction pass on a draft) and enumerates what it does — formatting, live link verification, required-term checks, leak scanning — plus the deliverable (corrected copy + signed report). It does not distinguish itself from any sibling, though no sibling in the list offers copy correction, so confusion risk is low.

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

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

Usage is implied by the deliverable description rather than stated; there is no 'use this when' or 'use X instead' guidance relative to the 23 sibling tools. The description does give solid invocation guidance (POST JSON to the paid URL with an x402 v2 PAYMENT-SIGNATURE header), which is helpful but is not the same as when-to-use 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 idempotency and non-destructiveness, and the description goes well beyond them: it discloses that this is a paid call ($222.00 USDC on Base/Arbitrum One), the required x402 v2 PAYMENT-SIGNATURE header, the POST-to-paid_url invocation pattern, and a docs link. The one gap is that it does not say the paid action is charged even on a check failure or what happens on payment rejection.

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 value proposition and kept to a few dense sentences with zero filler. The fragment 'One check: the tool alone.' is cryptic and the 'document_hash optional' clause duplicates the non-required schema status, costing a little clarity.

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

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

For a paid multi-check aggregate with an output schema, the description covers cost, payment protocol, auth header, idempotency, and the receipt artifact. Missing only the semantics of the 'trust verdict' field and error/refund behavior, which an agent paying per call would want.

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%, including detailed idempotency-key semantics and the SHA256 pattern, so the schema carries the parameter burden. The description adds almost nothing beyond restating that document_hash is optional and implying the doc timestamp depends on 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 enumerates exactly what is bundled (liveness, content, TLS fingerprint, trust verdict, document timestamp) and the result form (one signed receipt), which is more specific than a vague 'run checks'. However it never names the sibling single-check tools (trust_report, trust_preflight, check_url_custom) it is an aggregate of, so differentiation is only implied by 'One check: the tool alone.'

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

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

'One check: the tool alone' implies that single-purpose checks belong to other tools, but no sibling is named and no explicit when-not condition is given. The payment prerequisites (x402 v2, PAYMENT-SIGNATURE header, price) are clear but they are invocation mechanics, 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 the mutation/idempotency profile, and the description adds genuinely new context: this is a metered paid call at a fixed $0.25 price, requires an x402 payment-signature header, and names the concrete endpoint. That payment/auth requirement is the kind of trait annotations cannot express. It does not describe what the signed receipt contains or what happens if payment fails, which keeps it at 4.

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 endpoint, price, and payment header are front-loaded and useful, but the prose reads as stacked fragments ('agent_wallet optional, on the receipt') inserted in an awkward position, and a docs URL plus a repeated paid URL both appear. Every element is relevant, but the ordering makes the payment mechanics harder to parse than necessary.

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

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

An output schema exists, so return values need not be explained, and the payment path is covered. What remains unclear is the actual artifact — whether the agent receives a document body, a link, or a template ID — and the mention of agent_wallet muddies the contract. Adequate to invoke, thin on what the caller should expect.

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

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

The only real parameter, idempotency_key, is fully documented in the schema (100% coverage), so the baseline would be 3. But the description instead introduces 'agent_wallet optional, on the receipt' — a field that does not exist in the schema, which sets additionalProperties false. That reference is at best confusing and at worst misleading about what the agent should send.

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

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

The description states the deliverable concretely: a fill-in template covering first casts, frame spec, and a launch checklist, delivered with a signed receipt. It also names the sibling it substitutes for (nostr_kit), so an agent can pick between the two Farcaster/Nostr kits. The verb is implicit (you buy/fetch a kit rather than perform an action), which keeps it short of a 5.

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

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

It routes explicitly to the alternative: 'On Nostr instead: nostr_kit'. It also gives the practical precondition for calling — POST to the paid URL with an x402 v2 PAYMENT-SIGNATURE header, $0.25 USDC on Base or Arbitrum One. It stops short of saying when a Farcaster kit is the right purchase versus research_paper or trust_report, so no exclusion guidance beyond the Nostr swap.

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, destructive=false, idempotent=true) but say nothing about payment behavior; the description adds the paid flow, the binding of the signed quote to the exact amount, the "patronage, never for work" receipt semantics, and the protocol doc link. It stops short of failure/refund behavior, so not 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 invocation guidance is front-loaded, but the amount range and USDC/chain detail are restated twice ("$0.01–$222" early, "$0.01–$222.00, USDC on Base or Arbitrum One" later) and the paid URL appears twice, inflating length without new 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 covers the receipt, so return values needn't be explained. The description supplies everything an agent needs to actually execute a paid call — URL, method, header, amount constraint, idempotency semantics — leaving only error-path specifics unaddressed.

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 description's restatement of the amount range and quote binding largely duplicates what the parameters already document. It adds no parsing or idempotency detail beyond the schema, so baseline 3 applies.

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

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

States a concrete purpose ("Support the Embassy") plus what it transacts: an open-amount USDC gift bounded $0.01–$222 with the paid URL named. No sibling among the agentid/attest/trust tools does payments, so it is trivially 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?

Explains the invocation mechanics (POST inputs as JSON to paid_url with an x402 v2 PAYMENT-SIGNATURE header) and the buyer-chosen-amount model, which is the when/how. It doesn't explicitly rule out alternatives, but no sibling overlaps this capability, 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 already give readOnlyHint=false, destructiveHint=false, idempotentHint=true, so the safety profile is covered; the description adds genuinely non-redundant context — it is a paid tool with a specific price, chain, payment protocol version, and paid URL, and it returns a signed receipt. It does not explain what happens on payment failure or whether the kit is regenerated or cached across calls.

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 with useful facts (sibling routing, price, protocol, URL) but reads as telegraphic fragments rather than a front-loaded statement of purpose, and the payment mechanics are interleaved with the purpose statement. Nothing is grossly padded, but structure could be cleaner.

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 payment/prereq mechanics are well covered. However, the ambiguous "agent_wallet optional, on the receipt" and the dangling "paid_url" reference leave an agent unsure whether those are inputs, outputs, or just documentation artifacts.

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

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

Schema coverage is 100% with a single idempotency_key, so the baseline would be 3 — but the description never mentions idempotency_key and instead introduces items that are NOT parameters ("agent_wallet optional", "paid_url") under a schema with additionalProperties:false. That risks an agent trying to pass agent_wallet or paid_url as inputs.

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

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

"Nostr from zero: first notes, profile, relays, launch checklist in one fill-in template with a signed receipt" clearly names the resource and its deliverables, and the line "On Farcaster instead: farcaster_kit" explicitly distinguishes it from its closest sibling. What it lacks is an explicit verb — an agent must infer that the tool generates/returns a template kit rather than performing some Nostr action.

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

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

The description routes the agent: use this for Nostr, use farcaster_kit for Farcaster, and it states the payment prerequisite ($0.25 USDC on Base or Arbitrum One via x402 v2 PAYMENT-SIGNATURE). It stops short of saying when not to use it (e.g., versus trust_preflight or similar onboarding/attestation siblings), leaving some 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 it discloses the price, currency, chains, the payment protocol and endpoint, and the idempotency contract (a replayed key returns the original receipt and the first request wins even with different inputs). That is exactly the kind of cost/side-effect/failure-mode context annotations cannot express, and nothing conflicts with readOnlyHint=false or idempotentHint=true.

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

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

The scoping rule and the endpoint are front-loaded and every clause carries information (scope, payment, price, URL). The 'Skip the sweep' opener is promotional filler and the payment details are packed into a single dense run-on, but overall it is tight for the amount of operational detail conveyed.

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 description is unnecessary, and the description covers the two things an agent most needs and cannot infer: how to pay and how idempotency behaves. What remains unstated — what 'signed receipt' verification should look like or how the ranking is ordered — is partially recoverable from the schema and output shape, so nothing essential 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 all three parameters are already documented in detail, including the surface slug examples, the UUID v4 idempotency rules, and the include_unverified default. The description only restates the 'omit surface = full directory' rule already in the schema, adding negligible new meaning — 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 concrete resource — a ranked directory of ranking surfaces covering methods, integrity, freshness and the provider's own standing — delivered as a signed receipt, which is far from a tautology of the name. It is slightly obscured by marketing framing ('Skip the sweep') and by never stating the operation as a plain verb, but an agent can still tell it returns a directory entry set rather than a trust check or attestation like the sibling tools.

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

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

It gives explicit operating context: omit `surface` for the full directory, and payment is required via POST to paid_url with an x402 v2 PAYMENT-SIGNATURE header at $0.25 USDC. It does not contrast with any sibling (e.g. trust_report or diligence_pack), but none of the listed siblings appears to be a direct substitute for a paid ranking directory, so the missing exclusion is a minor 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 already flag the write (readOnlyHint=false), idempotency, and non-destructiveness, and the description materially adds to that: opaque storage, no server-side decryption, a signed receipt over the blob hash, quorum-governed release, and a mandatory $1.00 USDC payment via x402 header. It does not state retention/permanence of the escrowed blob or what happens on payment or validation failure, so it falls short of the top mark.

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 its key guarantees are front-loaded in the first sentence, followed by the invocation mechanics and then price/endpoint. Every sentence carries information the agent needs; the only minor redundancy is restating the paid URL after the price 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?

For a paid, write-effect tool this covers everything needed to call it correctly: what is escrowed and how it is protected, the receipt behavior, the quorum governance, the transport (JSON POST to paid_url with an x402 v2 PAYMENT-SIGNATURE header), the exact price and chains, and the endpoint. Return values are covered by the output schema, so nothing essential 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 baseline is 3. The description reinforces that quorum_rules govern release and that the receipt covers only the blob's hash and byte count, but these points are already stated verbatim in the property descriptions, so it adds little beyond the schema.

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

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

The description opens with a specific verb and resource — 'Escrow an encrypted recovery blob' — and immediately constrains what the server does with it ('stored opaquely — we cannot decrypt it'). No sibling tool (agentid_*, attest_*, trust_*) does escrow/recovery registration, so the operation 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?

Usage is implied by the wording 'for operator review' and 'quorum_rules govern release', which tells the agent this is a release-governed escrow operation. However, there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. when to choose this over a plain attest_document), leaving the agent to infer the trigger condition.

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

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

Annotations already declare the tool is not read-only and is idempotent. The description adds critical context: it is a paid tool requiring x402 payment, with specific pricing tiers and idempotency key behavior (replays return original receipts). This goes well beyond the annotations.

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

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

The description contains necessary payment details but is repetitive with pricing information and lacks logical flow. It does not front-load the core action, instead starting with a price fragment.

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 presence of an output schema and annotations, the description provides sufficient behavioral context for a paid tool: payment workflow, licensing, and idempotency semantics. It does not explain the paper's content, but that is likely outside scope.

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 parameters are documented in the schema. The description adds minor semantics—mentioning bundle defaults and prior receipt upgrade pricing—but does not significantly expand on parameter meanings 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 identifies the resource (a research paper) and its pricing tiers, but lacks a clear action verb like 'purchase' or 'retrieve'. The agent must infer that this is a paid acquisition tool. It does not distinguish from siblings.

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

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

No guidance is given on when to use this tool versus alternatives. There is no context about scenarios that call for purchasing a research paper, nor any exclusions or comparisons to sibling tools.

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

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

The description adds substantial context beyond the annotations: it discloses that this is a paid tool ($0.25 USDC on Base or Arbitrum One), explains the x402 v2 PAYMENT-SIGNATURE header requirement and paid_url invocation, and clarifies that no orders are placed. These are exactly the operational and safety details an agent needs for a non-read-only 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 most sentences carry necessary operational information: paid status, price, payment mechanism, documentation link, and the no-orders boundary. The opening is slightly cryptic, but there is little wasted text overall.

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 and full parameter descriptions available, the description does not need to explain return values or parameter formats. However, for a complex paid tool, it still leaves the core concept of 'delayed scan' and 'expressions' underdefined, so an agent understands the payment flow better than it understands the actual delivered result.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including query examples and the supported budget values. The description only reinforces that omitting budget_usd means uncapped, which is already stated in the schema, so it does not add meaningful semantics beyond the structured field.

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

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

The description gestures at the tool's function with 'Shop an idea: delayed scan' and lists ticker/comparison/theme inputs, but the core output remains vague because terms like 'delayed scan', 'shelf', and 'expressions' are not defined. It does distinguish idea generation from order placement, but an agent cannot confidently state what the tool returns without opening the output 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 gives a scenario ('Shop an idea') and a boundary ('Ideas only — no orders placed'), plus a budget default, but it does not say when to choose this tool over siblings such as research_paper, diligence_pack, or trust_report. There is no explicit when-to-use, when-not-to-use, or 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?

Annotations cover safety, idempotency and open-world reach, and the description adds real context beyond them: it is a paid call ($0.25 USDC on Base or Arbitrum One) requiring an x402 v2 PAYMENT-SIGNATURE header against a named paid URL. That payment/auth mechanics detail is exactly what annotations cannot express; it stops short of covering failure modes or payment-expiry 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?

Front-loaded with the purpose and the possible verdicts, then transport details, then price and URL — a sensible priority order with no filler. The shorthand style ("Verdict: trust_report. Terms: trust_preflight.") is terse to the point of ambiguity but every sentence carries information.

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

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

For a paid, open-world gate the essentials are present: what is probed, the four outcomes, that a receipt/verdict comes back (output schema covers its shape), payment protocol, price, chain and endpoint. Missing only operational details such as what happens on payment failure or expiry.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, including the idempotency-replay semantics. The description only echoes endpoint, action, amount and permissions and says nothing about idempotency_key or context, so it does not exceed 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?

"Action gate" with the enumerated outputs (ALLOW, RESTRICT, ASK_HUMAN, QUARANTINE) states a specific verb and scope, and it explicitly separates roles from siblings: trust_report produces the verdict artifact, trust_preflight covers terms. The telegraphic phrasing requires a second read, but an agent can distinguish it from siblings without opening a schema.

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

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

It implies usage (pre-action risk gating) and points to trust_preflight for terms, but never states when an agent should call this instead of trust_report or trust_preflight, nor any preconditions. The routing hints are present but the when/when-not decision rule 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?

Adds substantial context beyond annotations: the $0.25 USDC price on Base/Arbitrum One, the x402 v2 PAYMENT-SIGNATURE header requirement, POSTing inputs as JSON to paid_url, and that dry_run is intercepted before the payment gate. Annotations already declare openWorld/idempotent/non-destructive, so the remaining gap is minor (e.g., failure/timeout behavior on payment).

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

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

Front-loads the core purpose and the free-vs-paid decision, then the transport details. Dense and mostly waste-free, though the raw URL and docs link add some visual clutter.

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?

Output schema exists, so return values needn't be explained; the description supplies the payment protocol, endpoint, and the dry_run bypass. Given the 'Paid tool' claim it could say more about what happens if payment fails, but the essentials for correct invocation are covered.

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

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

Schema description coverage is 100%, so the schema already documents subject, intent, policy, context, dry_run and idempotency_key. The description echoes dry_run and the payment mechanics but adds no field-level syntax beyond what the schema states; baseline 3 applies.

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

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

States a specific verb+resource ('preflight' check producing a 'signed verdict against your policies') and frames the decision it supports (who is paid, what's delivered, what changed). It explicitly distinguishes itself from the sibling trust_report ('Endpoint verdict: trust_report'), though the phrasing is somewhat compressed and sales-like.

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 ('Before paying') and names the alternative for a related need ('Endpoint verdict: trust_report'), plus the free path ('dry_run=true'). No explicit when-not guidance, but the routing information an agent needs is present.

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

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

The description adds important behavior beyond annotations: the endpoint is probed unpaid, results are signed verdicts, and the tool is paid via x402 with a specific price and networks. It also explains the required POST and PAYMENT-SIGNATURE header, though it does not cover every operational detail such as rate limits or payment failure 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 purpose and payment model are front-loaded, and most sentences carry useful information. The sibling mapping is terse to the point of being slightly cryptic, but the description avoids unnecessary length.

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, existing output schema, and annotations covering safety and idempotency, the description provides enough additional context about payment, invocation, and verdict type for an agent to call the tool correctly. No critical missing piece stands out.

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 well documented. The description does not add meaningful semantics for url or idempotency_key beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: a buy/don't-buy verdict on an x402 endpoint, including the possible signed outcomes. It also distinguishes the tool from trust_preflight and trust_assurance by assigning those siblings to terms and action-gate roles.

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 frames the tool as the verdict step and names trust_preflight and trust_assurance as related tools, giving useful context for when to use it. However, it does not explicitly state exclusions or the precise conditions that should route an agent to a sibling instead.

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