Stillleaf: Memorial program correction, printing and delivery

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 establish that this is a safe, read-only, idempotent, non-destructive, closed-world operation. The description adds what topics the response covers but does not describe output format, length, or whether the content is static reference material versus dynamic business data.

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

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

The description is short but poorly structured as a single run-on sentence with an oversized parenthetical that interleaves business marketing copy with content coverage. It is understandable but not front-loaded or easy 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?

For a zero-parameter, read-only informational tool with no output schema, the description covers the relevant scope: business description, request handling, deliverables, and request fields with examples. It lacks explicit guidance on when to invoke it, but the content coverage is sufficient for the tool's complexity.

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 tool has zero parameters, so there is no parameter semantics to compensate for. The description does not confuse this by implying inputs; it correctly frames the request fields as returned reference content rather than arguments.

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 the informational content the tool provides: business operations, request lifecycle, deliverables, scope, and request fields with examples. An agent can infer this is an informational overview tool, though it does not explicitly start with a verb like 'Returns' or differentiate itself from the operational 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?

Usage is only implied: an agent may infer this is useful for orientation before submitting a request, since it mentions request fields and examples. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as submit_request or request_status.

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 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?

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.

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

Adds substantial context beyond the annotations: nothing is ordered or committed until terms are agreed, timing/feasibility is only established during review, the submission is answered with a receipt whose id and token must be retained, and contact data retention is stated as 'while we correspond or do business and for 24 months after.' That is exactly the kind of cost/commitment/data-handling disclosure a non-destructive mutation tool needs and the annotations cannot carry.

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

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

Front-loaded with purpose and scoped by parenthetical, and nearly every sentence adds a decision-relevant fact (cost, commitment, receipt, retention). It is dense in a single unbroken block and mildly redundant between 'Nothing is ordered or committed until you agree terms' and 'A requirement is not an order and costs nothing,' which slightly hurts scannability.

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

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

For a 10-parameter, nested-object, no-output-schema tool, the description covers the full lifecycle: submission, file follow-up, review, proposal, and the receipt contract that substitutes for an output schema. The remaining gap is parameter-level coverage for the structured commercial fields (quantity, budget, timing, geography), which an agent must guess at.

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 only 30% schema description coverage across 10 parameters, the description must do more of the work than it does. It explains 'need' ('your requirement'), the continuation id/token intent, and clarifies that contact drives email replies, but action, quantity, geography, specifications and requested_fields get no meaning from the description. Note the schema itself links specifications to 'request_schema describe_business returns,' which is genuinely useful and partially compensates.

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 concrete verb and resource: 'Send Stillleaf a requirement,' then scopes it to memorial program correction, printing and delivery. It also implicitly separates itself from order-submission siblings via 'A requirement is not an order and costs nothing,' though it never names submit_purchase_order or state_purchasing_requirements directly, so full sibling differentiation is left to inference.

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

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

Gives clear situational guidance: use it to open a new requirement, use the continuation id/token to add to an existing one, and use request_status to read progress. It also states the 'when not to use' condition ('not an order and costs nothing') and the human next step when no secure link exists. It does not explicitly route to accept_offer or counter_offer, which are the siblings an agent would need once a proposal arrives.

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