Nestproof: Graded pattern files your LA factory signs off before the cut

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

Annotations already declare readOnly=false, idempotent=true, destructive=false; the description adds the commitment semantics (exact terms hash binding, explicit acceptance flag) and clarifies scope by pushing payment links and verified payment state to inspect_offer. It does not say what happens on a hash mismatch or whether the resulting order can be cancelled, which are the remaining behavioral gaps.

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

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

Three tight sentences, front-loaded with the commitment action and its preconditions before the follow-up pointer. "Follow inspect_offer later" is slightly awkward phrasing but carries 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?

With no output schema and seven parameters, the description covers the commit decision and the post-acceptance path well, but leaves unanswered what success returns (order id? receipt?), how hash mismatch is reported, and the semantics of three optional fields. Adequate for the happy path, incomplete around failure and identity handling.

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 only 29%, so the description must compensate, and it does add meaning for the two highest-stakes parameters (terms_sha256 as the exact inspected-terms hash, accept as an explicit acceptance flag). However, name, organization, and purchase_order are undocumented in both schema and description, leaving the agent to guess buyer-identity and PO-field conventions.

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 verb and outcome ("Place an order") rather than restating the name, and frames it against the offer lifecycle ("terms you have inspected"). It is distinguishable from decline_offer/counter_offer, but the link to the specific offer being accepted is only implied through the required id/hash.

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

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

Gives real preconditions: terms must already have been inspected and the buyer must have authorized acceptance, which is exactly the decision gate an agent needs. It routes to inspect_offer for payment follow-up, but never states when not to use this tool (e.g., instead counter_offer or decline_offer when terms are unacceptable).

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive write, so the description's job is to say what the write actually causes. It explains that the answer is recorded for the business, which applies it on its side, and that an ACCEPT of credit or refund moves no money until the payment processor records it. That is meaningful side-effect disclosure beyond the annotations; only failure/retry behavior is left implicit.

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

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

Three sentences, front-loaded with the action and followed by effect and then payment/money clarification, with no filler. The middle sentence is slightly convoluted in phrasing but still 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?

For a 7-parameter mutation with no output schema and only 57% schema coverage, the description covers the important side-effect semantics but is thin on the optional note and on what the caller receives back after answering. An agent can call it correctly, but some parameter-level semantics are left to the schema or unstated.

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

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

Coverage is 57%, so the schema already documents id, name, token, and terms_sha256 while remedy_id, answer, and note have none. The description usefully explains where remedy_id comes from (the PROPOSED remedy in the offer thread) and what ACCEPT/DECLINE mean at a business level, but leaves note and name unaddressed, which matches the baseline 3 rather than exceeding 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?

Uses a specific verb pair (accept/decline) on a specific resource (a remedy proposed by the business on a placed order), which is concrete enough to act on. It does not explicitly distinguish itself from the sibling tools accept_offer and decline_offer, so an agent must infer that this one targets a remedy object rather than an offer.

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 parenthetical tells the agent exactly where the input comes from (inspect_offer thread.fulfilment.remedies with state PROPOSED), which is genuine when-to-use guidance tied to a prerequisite. It stops short of naming exclusion cases, such as what to do when no remedy is in PROPOSED state.

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

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

Adds substantial behavior beyond the annotations: the original terms remain intact, a later proposal silently replaces an earlier one still awaiting an answer, and the business responds in inspect_offer thread.counteroffers with a revised offer or a reason. The closing 'Nothing here orders or pays' clarifies the non-destructive boundary even though readOnlyHint is 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?

Front-loaded with the purpose, then the changeable dimensions, then the consequence and follow-up path. Dense but each sentence carries information; a few clauses ('on its inspected terms') are jargon-heavy but not wasteful.

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

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

With no output schema, the description usefully explains where the answer appears (inspect_offer thread.counteroffers) and what happens to superseded proposals. For a nested, five-required-parameter mutation tool that is nearly complete, though it says nothing about failure modes or authorization beyond the token carried in 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 coverage is already 100%, and the description still adds meaning by tying quantities to item indices in terms.items and explaining counterparties only applies where items price companies, plus framing total_minor as a price for the whole. It stops short of describing the token/terms_sha256 staleness check, but the schema covers 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?

States a precise verb and resource ('Propose a change to an issued offer') and enumerates the dimensions that can be changed (quantities, companies, delivery date, total, payment plan, note). It immediately frames the act as a proposal rather than a mutation, which separates it from accept_offer without naming it.

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?

Clear about when to use it: when the inspected terms are not acceptable as-is, while noting the terms still stand and can be accepted unchanged. It does not explicitly name accept_offer or decline_offer as the alternatives, so routing is implied rather than stated.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say the decline is final, what happens to the offer or any held funds, or how a terms_sha256 mismatch is handled — all material for an irreversible mutation.

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?

One short, front-loaded sentence with no filler, so there is no wasted wording. However, the brevity comes at the cost of the preconditions and consequences an agent needs, so it reads as under-specified rather than efficient.

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

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

This is a destructive, irreversible mutation with no output schema and only half its parameters documented in the schema. The description should explain the inspect-then-decline flow, the role of the terms hash, and what success or failure looks like; it covers none of that.

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 50%: id and token carry descriptions, while reason and terms_sha256 do not. The phrase 'inspected terms' weakly points at terms_sha256 but never explains that it binds the decline to the exact terms version shown by inspect_offer, nor what happens if it is stale; reason's purpose is left entirely unstated. Baseline 3 given partial coverage, but the gap is not compensated.

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

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

The description names a specific verb ('Decline') and resource ('an issued offer'), which cleanly separates it from siblings accept_offer, counter_offer, and answer_remedy. The trailing phrase 'on its inspected terms' is opaque, but the core action is unambiguous.

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

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

There is no explicit when-to-use guidance, no mention that inspect_offer must run first, and no statement of consequences versus accept_offer or counter_offer. 'On its inspected terms' faintly implies a prior inspection step, but the agent must guess at the prerequisite ordering.

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 safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds two useful traits beyond that: an empty value clears the field, and the payload is applied 'exactly as given: no reading' — i.e. no read-back or validation of the result. It does not explain what happens on revision conflict (base_revision), how op_id interacts with the idempotency hint, whether multiple ops are atomic, or what the call returns despite there being no output schema.

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

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

It is short and packs real information into few words, but it is front-loaded with JSON snippets instead of a plain statement of what the tool does, and phrases like 'exactly as given: no reading' and 'the open question' force the agent to decode intent. Some compaction costs clarity here.

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 5-parameter mutation tool with no output schema and only 40% schema coverage, the description covers the ops payload and the clear-on-empty rule but omits conflict handling via base_revision, the 30-op limit, atomicity of multi-op batches, and any statement of what a successful call returns. Enough to attempt a call, not enough to call it safely in a concurrent setting.

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 40%, and the description compensates for the most complex parameter by enumerating the ops grammar ({"op":"set","values":{...}}, add/update/remove/replace, empty clears) that the schema leaves as an untyped object array. It leaves op_id (80-char limit) and base_revision (optimistic concurrency) entirely unexplained, so the compensation is substantial but incomplete.

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

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

The description states a specific verb and resource: set named fields on a requirement, or add/update/remove/replace list entries, with concrete op payload shapes. 'No reading' implicitly separates it from the read-side sibling get_requirement, though that sibling is never named. An agent can tell what the tool mutates, but the phrasing is telegraphic rather than plainly stated.

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

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

'Use it to answer the open question when the answer is a value' gives a conditional trigger, which is more than nothing. However, it depends on unstated domain vocabulary ('the open question') and never names the alternative path (e.g. interpret_requirement or answer_remedy) for when the answer is not a value. The when-not guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful disclosure about returned state – provenance, what a value replaced, the open question, unread words, sent status, and any offer – which is genuine context beyond the annotations. It says nothing about failure modes (invalid id/token) or pagination/size 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?

A single front-loaded sentence with a compact colon list, no filler. Some phrases ('words not yet read') are idiosyncratic and slightly opaque, 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?

For a two-parameter read-only tool with full schema coverage and no output schema, the description carries the return-value burden and does list the key fields an agent would get back. It stops short of explaining response shape or how the provenance/replacement data is structured, but it is adequately complete for invocation.

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

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

Schema description coverage is 100%, so both the uuid id ('from an earlier answer') and the 48-hex token (private receipt token) are already documented in the schema. The description adds no further meaning about either parameter; baseline 3 applies.

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

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

The description is a noun phrase ('A Nestproof requirement as it stands') with no explicit verb, so the read operation is only implied by the title and the 'as it stands' framing. It does enumerate the returned content, which distinguishes it from edit_requirement and send_requirement, but an agent must infer that this is a retrieval call.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no named alternative (e.g., edit_requirement to change values or accept_offer to act on the offer it returns). Usage is only inferable from the sibling list.

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 write-but-non-destructive, idempotent, closed-world profile. The description adds real behavioral context beyond them: acceptance is computed and only holds when nothing is rejected, the business replies with a proposed remedy via the inspect_offer thread, the call is refused if terms have changed since terms_sha256, and no payment or refund occurs 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 purpose is front-loaded, but the prose is telegraphic and grammatically tangled ('with a reason for a rejection, optionally for one portion of the order'; 'Recorded for the business, which answers a rejection in inspect_offer thread.fulfilment'). The content earns its place, yet the phrasing forces the reader to re-parse several clauses.

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

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

For a non-destructive idempotent write with a rich schema but no output schema, the description covers the key downstream consequences (remedy proposed by the business, no payment movement) and the terms-drift refusal. What is missing is how errors or partial rejections surface and how the record relates to later remedy acceptance.

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 71%, so the schema does most of the work, but the description meaningfully clarifies the domain: lines map to indices in terms.items, the portion scopes the inspection to one part of the order, and the rejection reason attaches to rejected quantities. It does not discuss name, note, id, or token, but those are documented in the schema.

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

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

The description opens with a specific verb and resource: recording the buyer's inspection of a placed order, with accepted/rejected quantities per line item. It implicitly distinguishes itself from the read-only inspect_offer by describing what is recorded rather than what is read, though the contrast is never stated outright.

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

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

Usage is only implied: the tool applies after an order has been placed, and a buyer who rejects something should expect a response through the inspect_offer thread. There is no explicit when-to-use or when-not-to-use statement, and no direct naming of alternatives such as release_payment or answer_remedy.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context: the authorization scoping ('exact authorized terms'), the credential model (offer-link token vs. token of a request linked to the offer), and a full inventory of the data surfaced. It stops short of a 5 by omitting what happens when the token is invalid or the request is not linked to the offer.

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 main purpose is front-loaded and the parenthetical groupings (counteroffers, purchasing, fulfilment) keep a dense enumeration readable. The single long sentence is heavy on dotted field paths, but each listed item maps to real returned content rather than filler. Slightly tighter phrasing would make it easier to scan.

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 carries the burden of describing returns and does so thoroughly across terms, order state, payment links and three thread sections. Credentials and authorization scope are covered. Remaining gaps are error/failure behavior for invalid or mismatched credentials, which matter for a token-gated read.

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 id and token are already documented in the schema. The description reinforces the credential meaning of token ('offer link credentials, or credentials of the request explicitly linked to this offer'), which is a modest addition over the schema's 'private token from your receipt'. No format or linkage constraints are added beyond that, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Read the exact authorized terms, terms hash, order state and processor payment links') and then enumerates the thread sub-objects it returns (thread.counteroffers, thread.purchasing, thread.fulfilment). This clearly separates it from request_status and describe_business. It falls short of a 5 because it never names the closely related siblings (inspect_delivery, answer_remedy) even though thread.fulfilment overlaps with their territory.

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

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

Usage is only implied: an agent can infer this is the read path for a specific offer, and the final sentence gives a credential prerequisite ('Use the offer link credentials, or credentials of the request explicitly linked to this offer'). There is no explicit when-to-use/when-not-to-use guidance and no routing to alternatives such as request_status for lightweight status checks or inspect_delivery for delivery-only views.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false; the description goes well beyond them by disclosing what happens to the input (provenance per value, conflicts returned as one question, unread words preserved verbatim) and that no order/send side effect occurs. It stops short of covering token secrecy and retry/dedup behavior, which live in the schema rather than the description.

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?

A single dense paragraph, front-loaded with the core action, then outcome, then continuation rule, then the two routing exclusions. Every clause carries distinct information; no filler or restatement of the title.

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

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

For a mutation-style ingestion tool with a nested continuation object and no output schema, the description supplies the return shape in prose (structured values with source words, a single clarifying question, unread text retained) and the send/no-send boundary. Minor gaps: privacy of the token and retry semantics are only in the schema, and nothing is said about what happens on an expired or invalid requirement handle.

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 real meaning: it explains that 'requirement' is a continuation handle carried from a prior answer and that the utterance is the buyer's own words including corrections/additions. It does not clarify turn_id or timezone, which the schema already documents.

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

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

States a specific verb+resource: take the buyer's words and read them into a structured requirement, including corrections/additions. It also names the two siblings an agent might confuse it with (send_requirement, submit_request) and the condition that separates them, so an agent can pick it without opening the 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?

Explicit when-to-use ('give the buyer's requirement... in their own words'), explicit when-not ('Nothing is sent or ordered'), explicit alternative ('When you already have the fields in structured form, use submit_request instead'), plus the continuation rule ('Pass the requirement (id, token) from the first answer to continue it'). Nothing about routing is left to inference.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world, so the bar is lower; the description still adds genuinely useful behavior: the call records approval only and does not move funds. It omits whether a failed or duplicate release is rejected, and says nothing about what the confirm/terms proof guarantees.

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, zero filler, with the confirmation action front-loaded and the critical non-effect (does not pay the processor) placed where it will be read before 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 6-parameter mutation with five required fields and no output schema, the description covers intent and the not-a-payment caveat but leaves the majority of required inputs semantically undefined. An agent can tell why to call it, but not confidently construct terms_sha256 or payment.

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 only 33% — id and token are documented, but name, payment, terms_sha256 and confirm are bare. terms_sha256 in particular is opaque (a 64-hex digest of what terms?) and the description never explains what must be hashed or why the release requires it, nor what the 'payment' string should contain.

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 pairs a specific verb (records approval / confirms a payment condition) with the resource and explicitly bounds scope by excluding processor payment: 'This records approval; it does not pay the processor.' It distinguishes itself from settlement tooling but does not name or differentiate from near siblings like accept_offer or submit_purchase_order.

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

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

It states a real precondition — 'only where the inspected order allows the customer to release it' — which routes the agent to an inspection step (inspect_offer/inspect_delivery) before calling. There is no explicit when-not guidance or named alternative, so it stops short of a 5.

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

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

Annotations already declare this is a mutation (readOnlyHint=false) that is idempotent and non-destructive, so the basic safety profile is covered. The description adds real value beyond that by characterizing the write as the buyer's own statement and pointing to where the counterparty's answer appears, but it is silent on what happens on a repeat report (overwrite vs. supersede) and on any authorization requirements.

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 dense sentences with the action and its allowed values front-loaded, then the recording semantics. No filler; the only mild awkwardness is the trailing 'thread.purchasing' fragment, which reads as a raw path rather than prose.

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 mutation with no output schema, the description supplies what the schema cannot: that the act is an attestation by the buyer and that the resulting answer is found in the inspect_offer purchasing thread. Combined with the schema's explicit terms_sha256 refusal note, an agent has enough 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 coverage is 67%, and the description reinforces the meaning of status, reference, and documents_requested (including tying documents to the DOCUMENTS_REQUESTED state). It adds nothing for buyer_vendor_id, which also has no schema description, and says nothing about the id/token/terms_sha256 prerequisites beyond what the schema already documents.

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

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

States a specific verb (report) and a specific resource (the seller's vendor standing) and enumerates the exact status values the call records, so the agent knows precisely what effect it has. It does not explicitly contrast itself with siblings such as answer_remedy or state_purchasing_requirements, 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?

The line 'Recorded as the buyer's own statement; the business answers it in inspect_offer thread.purchasing' tells the agent this is a buyer-side attestation whose outcome is later visible in the offer thread, which implies the context of use. However, there is no explicit when-to-use/when-not guidance and no routing versus the many other write siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds two non-obvious facts beyond that: access requires private receipt credentials (an auth condition), and contact details are deliberately withheld/separated from the returned record. It does not cover error behavior for a bad token, but the added context is substantive.

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

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

Three short sentences with the action front-loaded and no filler. 'Contact details are kept apart' is compact but slightly cryptic in isolation, which keeps it just below the top mark.

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 must convey what comes back; it does so only at a high level ('the recorded requirement and any linked offers') without indicating structure, whether offers are summarized or full, or what happens on an invalid token. For a read-only, fully documented two-parameter tool this is adequate but not thorough.

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%: 'id' is documented as the request or offer id from the receipt or customer link, and 'token' as the private token to retain for later visits. The description's 'using the receipt credentials' merely restates that provenance, adding no new meaning about format or scope.

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

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

The description says it resumes/reads a 'requirement' and any linked offers using receipt credentials, which conveys a read of a stored record plus its associated offers. However, the vocabulary ('requirement', 'resume') does not map cleanly onto the tool name request_status, and it never distinguishes this from sibling readers like inspect_offer or inspect_delivery, which plausibly return overlapping data.

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

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

The only usage signal is the implicit requirement for receipt credentials. There is no statement of when to choose this over inspect_offer, inspect_delivery, or report_vendor_status, and no mention of what to do if the token is invalid or expired.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world, so safety is covered. Beyond that, the description adds real behavioral context: the exact contents returned (text, hash, version, sources, shortfall) and the notable pre-payment response state, which an agent could not infer from 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 payload description is front-loaded in the first clause, followed by the availability caveat and the credential note. Every sentence carries information; the phrasing is dense but not padded.

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?

There is no output schema, so the description correctly carries the burden of describing returned fields, and it does so with reasonable specificity. Combined with the auth prerequisite and pre-payment behavior, an agent has enough to call this correctly, with only sibling disambiguation left implicit.

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, setting the baseline at 3. The description adds a little meaning by tying credentials to 'the offer link or linked request', clarifying that the id may be either an offer or a request identifier, but it adds no format or constraint detail 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 gives a specific verb and resource (retrieve a paid order's deliverable) and enumerates the payload: exact text, SHA-256, version, sources, and any shortfall. The parenthetical constraint 'where the business produces it itself (a report)' narrows scope, which implicitly separates it from a sibling like inspect_delivery, but no sibling is 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?

It describes a precondition ('Before payment is confirmed it says it is not yet available') and tells the agent what credentials to supply, which implies the correct usage context. However, it never states when to choose this tool over inspect_delivery or request_status, nor any exclusion besides the unpaid case.

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

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

Adds real context beyond the annotations: the first send creates the request and its token doubles as the receipt token used by request_status and offers, resends create a revision, and 'This orders nothing' pre-empts the natural but wrong assumption that sending commits a purchase. Consistent with idempotentHint=true and destructiveHint=false, though it says nothing about the op_id idempotency key or contact handling.

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 action and tightly written, with the crucial 'orders nothing' caveat placed last for emphasis. The first sentence is long and parenthetical-heavy, which slightly slows parsing but 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?

For a 6-parameter mutation tool with no output schema, it covers the essential semantics: what gets created, how revisions work, and that no order is placed. The undocumented contact and op_id parameters are the remaining gap, but the core mental model an agent needs is present.

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 50%; the schema already documents id, token, and action, and the description reinforces revision ('name the revision the buyer saw') and the token's dual role. It adds nothing about op_id or the required contact object, so it only partially compensates 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 ('Send the requirement to Nestproof') and goes further by explaining the two modes: first send records the request, later send records a revision of the same request. It does not explicitly name the nearest siblings (edit_requirement, submit_request) to distinguish itself, so 4 rather than 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?

'Once the buyer says to' gives a clear precondition, and the first-send vs later-send split tells the agent when to use this versus keeping a draft. It stops short of naming alternatives like edit_requirement or submit_request, leaving the sibling routing to inference.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the record is framed as the buyer's statement, it is later surfaced under inspect_offer thread.purchasing, and it explicitly does not place orders or move money. It does not describe what a successful call returns, but that is minor against the annotation coverage.

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

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

Two sentences, front-loaded with the purpose before the enumeration and scope disclaimer. The six-item list is dense but each item corresponds to a real field the caller must supply, so nothing is padding. The middle clause 'Recorded as the buyer's statement' is slightly awkwardly spliced in but still earns its place.

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

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

For a six-parameter, nested-object mutation with no output schema, the description covers purpose, scope boundaries, and where the recorded data is later read. The concurrency guard on terms_sha256 is documented in the schema, so its absence from the description is acceptable. Only the success/response behavior is 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 83%, so the baseline is 3. The description nonetheless adds meaning for the nested requirement fields that the schema leaves bare — vendor_approval_required, purchase_order_required, buyer_vendor_id, and payment_terms_days — by explaining them in plain business terms. Identity and integrity parameters (id, token, terms_sha256, name, organization) are left entirely to the schema, which already documents them.

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 ('Tell the business how the buyer's purchasing works for this offer') and then enumerates exactly which facts are recorded: vendor approval, PO requirement, documents, vendor id, order/invoice route, payment terms. The closing line 'Nothing here orders or pays' separates it from submit_purchase_order, so an agent can pick between them 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?

Usage context is clear: this is the buyer's statement of purchasing requirements, and the counterpart read is 'the business answers it in inspect_offer thread.purchasing', which tells the agent where the data surfaces afterwards. There are no explicit exclusions or named alternatives (submit_purchase_order is only implied via 'Nothing here orders or pays'), so it falls short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the key behavior: the PO is reconciled against accepted terms, differences are recorded as exceptions visible in inspect_offer rather than silently accepted, and revision semantics govern changes. With annotations already covering safety and idempotency, this adds meaningful context; only the refusal-on-stale-terms condition lives in the schema rather than the description.

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 tight sentences with the purpose stated first, followed by the reconciliation behavior and the two negative guarantees. The field enumeration in sentence one slightly overlaps the schema, but it earns its place by framing what makes up a PO.

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

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

For a six-parameter nested mutation with no output schema, the description covers purpose, the matching/consequence model, and where to see the outcome (inspect_offer thread.purchasing). It does not describe what a successful submission returns or whether multiple POs may be sent against one offer, which are the remaining 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 coverage is 83%, so the baseline is already high, but the description adds real meaning: it enumerates the PO content the caller must supply (number, revision, lines, total, currency, payment terms) and explains that a changed PO reuses the number with a higher revision, which clarifies how 'revision' is meant to be used in practice.

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

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

The description states a specific verb and resource ('send the buyer's purchase order') and scopes it to 'an issued offer or a placed order', which separates it cleanly from accept_offer, counter_offer and release_payment in the sibling list. An agent can identify both the action and its object without opening the schema.

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

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

It gives clear usage context (send a PO against an issued offer or placed order) and explicit exclusions ('does not accept the offer and pays nothing'), which steers the agent away from accept_offer and release_payment. It also routes exception review to inspect_offer thread.purchasing. It stops short of an explicit when-to-use versus when-not-to-use contrast with every sibling, so a 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.