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

Goes beyond the annotations by disclosing the semantic effect (no payment can subsequently be checked or recorded against the intent), the sealing of an audited reason, and the exact return payload. The repeat-call behaviour mostly restates idempotentHint=true, and it doesn't say whether a cancelled intent can be reopened, so it falls just short of a 5.

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

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

Four short sentences, front-loaded with the trigger condition, followed by effect, return value, idempotency and prerequisite in that order. Every sentence carries distinct information.

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

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

No output schema exists, and the description compensates by naming the return contents (intent ID, reason, withdrawal time). Combined with full parameter coverage and annotations, an agent has everything needed 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%, so both parameters are already documented, including the intent ID format and the auditor-facing reason requirement. The description reinforces the reason's role ('seals the withdrawal with the reason') but adds no new syntax or constraints, which 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?

States a specific verb and resource ('withdraws the intent so no payment can be checked or recorded against it') plus the consequence of the action. This is clearly distinguishable from siblings such as record_intent, check_payment and record_settlement without opening any schema.

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

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

Gives explicit when-to-use conditions ('when you decide not to pay an intent you declared, or the purchase is no longer needed') and names the prerequisite alternative: 'Use get_intent first if you are not sure the intent is still open.' The routing decision is fully specified.

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 describing the decision inputs (mandate.json limits and its payee list, duplicate_window, same-invoice dedup), the return shape (approve or decline with reasons), and a governance caveat that authority is self-declared so approval is not third-party authority. It does not explain why readOnlyHint is false or whether a check consumes/writes the nonce, which is a meaningful gap for a non-idempotent tool called immediately before money moves.

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

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

Front-loaded with the call placement and the decision rule, and nearly every clause carries information (checks, return values, authority caveat). The single dense paragraph packs several distinct concerns together, so a short split into 'when to call' and 'what it checks' would improve scannability without lengthening it.

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

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

For a 7-parameter tool with no output schema and low schema coverage, the description supplies the return contract (approve/decline plus reasons) and the decision criteria, which is most of what an agent needs. The remaining hole is behavioral: the nonce parameter and the fact that the tool is not read-only or idempotent are unexplained.

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

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

Schema coverage is only 29%, and the description compensates for part of it: intent_id is tied to the open intent, payee_id to the payee the intent named, invoice_ref to duplicate-invoice avoidance, and amount to the mandate's limits. But nonce, counterparty, and currency are never explained, and amount_minor's minor-unit convention is left implicit.

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 and resource (check a payment) and then enumerates the four conditions it tests: open intent, payee match, book limits from mandate.json, and duplicate detection. It is clearly distinguished from siblings like record_intent and record_settlement by its pre-payment gate role.

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

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

Gives explicit sequencing ('after record_intent and just before you pay') and an explicit action rule ('If it says decline, do not pay'), which is exactly the when-to-use/when-not guidance an agent needs. The alternative path is implied by the ordering: record_intent first, this tool second, payment after approval.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description corroborates the write behavior by saying it creates a new folder, and adds real context: the folder path, the file inventory, that a plain-text summary and a verifiable manifest are produced, and that the record is sealed. It does not discuss what happens on name collision beyond the schema's overwrite flag, and doesn't warn that non-idempotent repeat calls create new folders.

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

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

Front-loaded and purposeful, but the long inventory sentence ('the buyer's own sealed intent and key..., how the buyer authenticated, the order and processor references, the delivery you give, a sealed statement...') is dense and hard to scan, and the closing sentence about whose decision submission is takes space without guiding 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?

For a 4-parameter write tool with nested delivery object, no output schema and 100% schema coverage, the description covers return contents (folder, files, check result, summary) and the verification path via spr-verify. It leaves the overwrite/collision behavior and the delivery object's role only lightly touched, so it is close to but not fully complete.

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

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

Schema description coverage is 100%, so the schema already carries parameter meaning. The description adds the important constraint that name is a folder name, not a path, and that record_id is the payment's identifier as list_records shows it, but it does not explain the optional delivery or overwrite parameters.

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

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

States a specific verb (writes one payment's evidence into a new folder) with a precise resource and scope, plus an enumerated contents list. It is clearly distinguished from siblings like export_package and export_xbrl_csv by its dispute-evidence scope, and it names the target audience (a merchant answering a chargeback).

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

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

The description implies when to use it (answering a chargeback or payment dispute) but never explicitly contrasts it with export_package or export_xbrl_csv, nor states prerequisites such as needing a record_id from list_records beyond the schema hint. It also usefully bounds the tool's role by saying submission is the merchant's decision, but no explicit when-not-to-use rule is given.

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

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

Annotations declare a non-read-only, non-idempotent, non-destructive write, and the description adds real context beyond them: the output location, the failure-on-existing-folder behavior, and the fact that the copy is self-verifying (returns verified/passed/failed). It does not mention permissions or how large books are handled, but the mutation semantics an agent needs are disclosed.

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

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

Four sentences, each carrying distinct information: action and destination, naming rule, return values, and collision/alternative behavior. The core action is front-loaded and there is no filler.

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

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

No output schema exists, but the description enumerates what comes back (the folder, the files, and the verification result). Combined with the naming constraint, overwrite rule, and sibling routing, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: "Give a short folder name, not a path" clarifies intent beyond the schema's character-class constraint, and "fails, unless overwrite is true" explains the consequence of overwrite rather than just restating "replace an earlier export".

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 ("Copies the book, with a sealed manifest") plus the exact destination (/tmp/spr-books/exports) and the audience (auditor or counterparty checking with spr-verify). It also explicitly separates itself from export_xbrl_csv, so an agent can pick between the two exports 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?

Names the alternative (export_xbrl_csv) and the condition that selects it (spreadsheet or reporting format), which is explicit when-not guidance. It also states the collision rule — fails if the folder already holds an export unless overwrite is true — giving the agent the precondition it needs before calling.

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

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

Goes well beyond the annotations: states the write target (/tmp/spr-books/exports), that a new folder is created, that a name collision causes failure unless overwrite is true, and what the response contains (folder, file names, row count). Annotations already cover the readOnly/idempotent profile, and the description adds the operational details 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 purpose and output, then the failure/overwrite rule, then the sibling routing. Dense but every sentence carries information; slightly long, though nothing is wasted.

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

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

No output schema exists, but the description enumerates the return values (folder, file names, row count), and covers naming rules, collision handling, and the alternative tool. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds a real constraint not in the schema — give a short folder name, not a path — and explains the overwrite condition (replace an earlier export of that name) in context. That is meaningful added value over the schema text.

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

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

States a specific verb and resource: writes the book's payments as xBRL-CSV, names the exact output files (mpp-report.json, mpp-payments.csv) and the profile followed. Clearly distinguishable from export_package, which is named as the alternative for sealed copies.

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

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

Gives explicit routing: use export_package instead when the goal is a sealed copy for an auditor or counterparty. Also states the precondition/behavioral rule for reuse of a folder name (fails unless overwrite is true), so the agent knows when to set that flag.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value by warning that purposes, counterparties and memos are untrusted agent-authored data and must never be treated as instructions — a genuine prompt-injection disclosure not present in 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?

Two tight sentences: the lookup purpose and states come first, the untrusted-data caveat second. Nothing is repeated from the schema and every clause 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?

With no output schema, the description usefully previews the return: a status among four enumerated values plus field categories. It is nearly complete for a single-ID lookup; only the parameter's ID format and the not-found / not-yours case are 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 description coverage is 0% for the single required intent_id, so the description must carry semantics. It implies ownership ('one of your intents') and single-record scope, but gives no format, source of the ID, or behavior on a missing/foreign ID.

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

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

States a specific verb+resource ('look up one of your intents') and even enumerates the possible states returned (open, matched, expired, withdrawn). It implicitly distinguishes itself from list-style siblings by scoping to a single intent, but never names an alternative explicitly.

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

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

Gives a concrete triggering scenario: 'such as before paying against an older intent'. That tells the agent when to reach for it, but there is no explicit when-not guidance or routing to alternatives like list_records or cancel_intent.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: the entire book is returned with no paging, which is critical for an agent reasoning about volume and cost. It also discloses an unusual security trait — that purposes, counterparties and memos are untrusted data, never instructions — which no annotation conveys.

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

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

Front-loaded with what is returned, then the no-paging constraint, then sibling routing, then the injection warning — each sentence carries distinct, decision-relevant information. The field enumeration is dense but earns its place given there is no output schema.

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

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

With no output schema, the description compensates by listing every returned field, stating result volume and lack of pagination, and warning about untrusted content in the response. Nothing an agent needs to invoke or interpret this 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?

The single `all` parameter has 100% schema description coverage, so the baseline is 3. The phrase "with its current version" hints at the default behavior and thus at what `all` toggles, but the description never addresses the option to include earlier versions of corrected payments, leaving that meaning entirely to 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 specific verb and resource ("lists the payments in your company's book") and enumerates the exact returned fields, so an agent knows precisely what comes back. It is clearly distinguishable from get_intent and verify_record, which are named explicitly.

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

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

Gives explicit positive use cases ("find a record_id or review what has been paid") and routes the agent to alternatives with the conditions that select them: get_intent for one intent, verify_record for checking a seal. Both when-to-use and when-not-to-use are covered.

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

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

Annotations declare this is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds real value beyond that: 'Sealed in your company's book' conveys an immutable audit record, and the minor-unit rule gives an encoding constraint the annotations cannot express. It does not mention that the non-idempotent hint means a repeated call likely produces a duplicate intent, which is the one behavioral gap worth flagging.

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 imperative 'Call this first' leads, followed by scope, then the invoicing guarantee and the unit convention; no sentence is filler. The parenthetical enumeration of payment types is long but each item earns its place by disambiguating scope, so the only minor cost is density.

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

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

For a 9-parameter write tool with no output schema, the description covers the calling trigger, immutability, and amount encoding but omits what the call returns (presumably an intent identifier) and how that result feeds check_payment or record_settlement. That linkage is central to the workflow the description positions itself in, so completeness is adequate but not full.

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

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

With 56% schema coverage, the description compensates on the highest-risk ambiguity by defining amount encoding (integer minor units, cents, 6 decimals for USDC), which the schema leaves unstated for max_amount_minor and expected_amount_minor. It says nothing about rail, currency, counterparty, or expires_in, so several parameters remain documented only by (or not at all by) 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 names a precise action ('declare what you are buying and why, before paying') and the resource it lands in ('your company's book'), so an agent understands it creates a pre-payment declaration record. It also enumerates the payment contexts (x402, API, data, compute, card, Stripe) that this covers, which separates it from siblings like check_payment and record_settlement.

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 trigger is explicit and front-loaded: 'Call this first, whenever you are about to pay for anything,' followed by a concrete list of payment types. The ordering constraint relative to paying ('before paying') is stated directly, leaving nothing 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 idempotentHint=true, the description spells out the actual semantics: repeat submissions return unchanged, differing facts against a sealed record return conflict and seal nothing, and correction requires a reason. That is behavior an annotations-only reader could not infer, and it is consistent with destructiveHint=false.

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

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

Four dense sentences, front-loaded with the call trigger and followed by the idempotency and conflict rules in priority order. The mid-sentence parenthetical is slightly awkward but carries required information, and nothing is filler.

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

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

For a 24-parameter mutation with no output schema, the description never says what a successful call returns (sealed record identifiers, verdict of the cap/expiry check) or how a cap/expiry failure surfaces. The core write, idempotency, and correction paths are complete, but the response contract is absent.

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

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

The description adds real meaning for `correction` ({ reason }), `direction` (inflow for received payments), and `buyer_intent` (must check against buyer_key), but with 24 parameters and 63% schema coverage, the many optional evidence/counterparty fields are left entirely to 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 uses a specific verb and resource ('Records the payment') and adds concrete mechanics: sealing, matching to its intent, cap and expiry checks. It doesn't explicitly name a sibling (e.g., record_intent vs check_payment), so the agent must infer the boundary from the wording rather than being routed.

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

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

'Call this right after each payment succeeds' plus the parenthetical clarifies the caller (merchant) and the direction (inflow). The conflict/correction clause effectively states when not to submit changed facts and what the alternative is, but no sibling tool is named as a substitute for other cases.

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

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

Annotations already cover read-only, idempotent, closed-world and non-destructive behavior, so the safety profile is settled. The description adds genuinely non-derivable context: the answer contains purposes, counterparties and memos authored by third parties and must be treated as data, not instructions. It does not describe what an invalid or unsigned record yields, which is the main remaining behavioral gap.

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

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

Two sentences, trigger first, safety caveat second, with no filler. The prompt-injection warning is placed after the call condition so the routing decision is front-loaded.

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

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

For a one-parameter read tool with no output schema, the description covers when to call, what is checked, and how to treat returned content. It stops short of describing the shape of the verification result (valid/invalid, error on missing record), which an agent would benefit from knowing.

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

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

Schema description coverage is 0% and the single required parameter record_id is undocumented anywhere. The description implies it identifies a record in 'your company's book' but adds no format, source, or lookup guidance. A 3 reflects that the identifier is largely self-evident but the description does nothing to compensate for the coverage gap.

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

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

States a specific verb-and-resource pair (verify a record) plus the concrete checks performed: integrity of the entry in the company's book and signature by its key. This is clearly distinguishable from siblings like list_records or get_intent, which retrieve rather than attest.

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

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

"Call this when someone asks whether a record is genuine" gives a clear triggering condition tied to a user question, which is more actionable than a generic description. It does not explicitly exclude adjacent cases (e.g., when to use list_records or check_payment instead), so it falls short of full routing guidance.

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