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

Annotations only declare the generic mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds meaningful behavior beyond that: what the call actually sends, that no funds move at this step, the validation-refusal rule, and the rate-deviation acknowledgement gate with its >10% threshold.

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 step number and the highest-value clarification (nothing is paid yet), followed by eligibility and the gating condition. No filler and no repetition of the schema.

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

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

There is no output schema, yet nothing an agent needs to invoke this correctly is missing: pipeline position (step 3), state prerequisite, failure behavior, the acknowledgement flag path, and the human-escalation requirement are all stated.

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

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

Schema coverage is 100% and the description's explanation of acknowledge_rate_deviation ('strong rate deviation or could not be checked') largely restates the schema text. The >10% threshold is the only genuinely additive detail, so this sits at the baseline the schema already earns.

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 ('accept a quoted order') and immediately clarifies the material consequence: a signed acceptance is sent but nothing is paid yet, with fund_order named as the tool that pays. This distinguishes it cleanly from siblings like request_quote, fund_order, and cancel_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?

Explicit preconditions ('Only for status quoted'), explicit failure routing ('A quote that failed validation is refused'), and an explicit escalation rule ('ask your human first' before acknowledge_rate_deviation). When-to-use, when-it-fails, and who-to-ask are all covered.

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

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

Annotations cover the safety profile (destructive, non-idempotent, open-world), and the description adds behavior annotations cannot: a preview mode that shows the offer and its check, a refusal condition tied to the refund template, and an error condition when no offer exists. These are exactly the preconditions an agent needs before a money-moving call.

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 'Moves money:' to signal stakes, then two dense sentences covering effect, failure mode, preview gating, and prerequisite. Parenthetical examples add length but carry useful context rather than filler.

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

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

For a 2-parameter destructive tool with no output schema, the description covers effect, confirmation gating, refusal semantics, error routing, and the lookup needed to find an offer. Nothing essential for a correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by specifying what the non-confirm path actually returns ('shows the offer and its check'), which the schema only summarizes as 'preview only, nothing happens'. order_id semantics are left entirely to the schema.

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

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

States a specific verb and resource: co-sign and broadcast a cooperative refund the shopper offered, with the effect spelled out (funds return to your wallet). The word 'cooperative' plus 'the shopper offered' distinguishes it from the unilateral sibling refund_after_timelock.

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 concrete trigger scenarios (item sold out, delivery failed) and a prerequisite pointer to get_order, which shows refund_offer when no offer exists. It does not explicitly contrast with refund_after_timelock or accept_quote, so routing is clear but not fully disambiguated.

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 openWorldHint=false, and the description reinforces rather than contradicts them while adding genuinely new context: 'Local, no network, nothing is started.' It could say more about the plan's size or format, but the safety/idempotency profile is well-covered.

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 sentence, front-loaded with the purpose before the content list, and the trailing 'Local, no network, nothing is started' is a useful scoping qualifier. The embedded list is dense but every item earns its place by telling the agent what the plan will contain.

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 read-only, side-effect-free plan generator with no output schema, the description tells the agent the plan's contents, that nothing is executed, and what the follow-up step is. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so all four parameters (name, fee_bps, regions, cash_regions) are already documented in the schema. The description only lightly gestures at them ('card or cash regions', 'fees'), adding no new syntax, format, or constraint detail. Baseline 3 applies.

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

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

States a specific verb and resource ('Return a step-by-step plan to earn fees as a proxy shopper') and then enumerates exactly what the plan contains (requirements, fees/risks, status, config file, listing path). This clearly distinguishes it from action siblings like fund_order or accept_quote, and it names registry_entry as the natural follow-up.

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 context ('Local, no network, nothing is started') and routes the agent onward with 'how to get listed through the registry (then registry_entry)'. It doesn't state explicit when-not-to-use conditions against other informational siblings like network_info, so it falls short of a full 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 it is not read-only and not destructive; the description adds genuinely new behavior: the state-machine precondition, the refusal boundary, a best-effort shopper notification side effect, and the guarantee that no money moves. It stops short of stating idempotency or permission requirements, so 4 rather than 5.

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

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

Two dense sentences with no filler, front-loading the eligibility constraint and the failure/alternative path. Every clause carries information an agent needs.

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

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

For a 2-parameter mutation with no output schema, the description supplies the precondition, the refusal case, the fallback tools, and the absence of financial side effects. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so both order_id (32-hex format, source tools) and reason (max length, default) are already fully documented. The description's only added signal is the implied 'best effort' delivery of the reason to the shopper, which is marginal; baseline 3 applies.

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

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

States a specific verb (cancel) and resource (order) and narrows the scope to unfunded orders, enumerating the eligible states (requested, quoted, accepted). An agent can immediately tell this apart from fund_order, refund_after_timelock, or open_dispute without opening any schema.

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

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

Explicitly gives the use condition (order not funded yet), the exclusion (refused once funding has started), and names three concrete alternative tools for the funded case. This is a complete routing rule.

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 destructive=true, readOnly=false, idempotent=false, but the description adds materially beyond them: irreversible, the two-phase preview/confirm flow, the shopper co-sign and broadcast, a warning when the shopper has not reported delivery, and the wait_seconds polling window. That is genuine behavioral detail an agent needs before committing money.

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

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

Front-loads the riskiest fact ('moves money', 'Irreversible') and the preview/commit distinction before the alternative-tool routing. Every sentence carries decision-relevant information; nothing is padding.

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, and the description compensates by describing what the preview returns and what happens on confirm. Combined with annotations covering the safety profile, an agent has everything needed to invoke this correctly or route elsewhere.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds semantics the schema does not: what confirm:true does to the flow (signs and waits up to wait_seconds on chain) and what the preview returns (payout amount, recipient, possible warning). It goes modestly beyond the structured fields.

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

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

States a specific verb and resource: sign the escrow payout to release funds to the shopper. It also positions itself in the workflow ('Step 5, moves money') and contrasts with a named sibling, open_dispute, so an agent can distinguish it 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?

Gives explicit when-to-use ('the items arrived and are right'), an explicit when-not with the alternative ('if the items did not arrive or are wrong, use open_dispute instead'), and the preview-vs-commit condition for confirm. Nothing about selection 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 destructiveHint=true, idempotentHint=false, and readOnlyHint=false. The description adds real value beyond them: it specifies that money moves and the dispute is settled, the refusal condition, and the confirm-gated preview behavior — context an agent cannot get from the annotations alone.

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

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

Front-loads the critical fact ('Moves money') and packs the precondition, preview behavior, and safety directive into a compact block. Dense but every clause earns its place; slightly clausal but no fluff.

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

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

No output schema exists, but the description explains the return behavior (returns the same review as review_ruling when not confirmed) and the main failure mode. Combined with destructive annotations, an agent has enough to invoke it safely; only exhaustiveness of error cases is 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?

Schema description coverage is 100% and the schema already documents both confirm (preview vs real) and order_id (32-hex from request_quote/list_orders). The description reinforces the confirm semantics but adds little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (countersign/sign+broadcast) and resource (the escrow's ruling transaction), plus the concrete effect — 'Moves money' and 'settling the dispute'. It implicitly distinguishes itself from review_ruling by naming it as the fallback behavior.

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

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

Gives explicit preconditions ('Refused if the transaction does not pay the ruled split'), the preview-vs-execute condition ('Without confirm: true it returns the same review as review_ruling'), and a human-in-the-loop directive ('Ask your human before confirming'). This is close to a full when/when-not/guardrail set.

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?

Discloses critical consequences beyond the annotations: the words persist in the conversation, anyone who sees them can take the funds, and the operation is local with no network. readOnlyHint/idempotentHint correctly reflect that nothing is mutated, so there is no contradiction and the risk disclosure adds real value.

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 dense sentences, front-loaded with what is exported and what it controls, followed by the gating condition and the risk. 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?

For a no-output-schema secret-export tool, the description covers the risk, the confirm gate, and network locality. It leaves the preview mode (confirm omitted/false) unmentioned, a minor gap for an agent deciding whether a bare call is safe.

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

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

Schema coverage is 100%, so the confirm boolean and its semantics are already documented in the schema. The description reinforces the confirm: true requirement but omits the schema's 'omitted or false = preview only' behavior, so it adds little beyond the baseline.

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

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

States a specific verb and resource ('Show this agent's 12-word BIP39 mnemonic') and immediately scopes what it controls (identity and every order's escrow key). This is clearly distinguishable from siblings like wallet or registry_entry 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?

Gives a clear selection condition ('use only when your human asks for a backup') and a hard gate ('Only with confirm: true'). It does not name an alternative tool for non-backup identity inspection, so it is clear context rather than full when/when-not routing.

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

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

Annotations already cover readOnlyHint, openWorldHint and idempotentHint, so 'Read-only' is redundant. However the description adds real behavioral context: an empty list has a specific meaning (nobody serves that shop/region yet), and it enumerates what each offer carries (fee, delivery days, cash regions, order limit, escrow fees, dispute SLA, vouching operator list) in the absence of an 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?

Front-loads the essential 'Step 1 of...' framing and keeps the reader on a clear workflow path. It is dense and slightly long due to the offer-field enumeration, but each clause carries useful information rather than 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, the description takes on the burden of describing return contents (offer index, fees, delivery days, escrow SLA, operator list) and explains how to consume the index. Combined with the sibling routing, an agent has everything needed to call it and act on the result.

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

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

Schema description coverage is 100%, so the schema already documents region prefix-matching, the payment enum and shop_url format. The description reinforces the coupling of shop_url/region/payment across find_offers and request_quote but adds no new per-parameter syntax beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb and resource: list proxy shopper × escrow combinations serving a given shop, region and payment method. This is clearly distinct from siblings like network_info (what exists) and request_quote (the next step), which the description itself names.

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

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

Explicitly frames itself as 'Step 1 of buying from a cash-only or crypto-unsupported shop', names the follow-up tool (request_quote) and what to pass to it, and routes the no-results case to network_info. When-to-use, next-step and fallback are all covered.

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

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

Annotations already flag destructive/non-idempotent/openWorld, and the description goes well beyond them by disclosing what the call does in each mode (preview returns recipients, amounts, network fee; confirm signs and broadcasts), the custody conditions under which funds can leave (2-of-3, shopper after T1, agent after T2), and the approval requirement. That is substantive behavioral context an agent cannot infer from the annotations.

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

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

Front-loads the core action ('Step 4, moves money: pay the quoted lock amount...') before the conditions and modes. It is dense with several clauses per sentence, but each clause carries operational or safety information rather than filler.

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

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

For a destructive, non-idempotent money-moving tool with no output schema, the description supplies the state precondition, the preview/execute duality, the approximate return contents, the custody/timelock release rules, and the human-approval requirement. Nothing material to calling it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds workflow meaning the schema does not: confirm=false is a preview that should be called first, and confirm=true signs and broadcasts. order_id is only referenced indirectly via 'this wallet'/'per-order', so it is not fully compensated, but the two-phase semantics of confirm are clearly enriched.

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: paying the quoted lock amount into the per-order 2-of-3 escrow (BTC P2WSH or USDC Safe) plus the escrow fee. It is unmistakable against siblings like request_quote, accept_quote, or confirm_receipt, and even labels itself as step 4 in the flow.

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 preconditions ('Only for status accepted/funding'), an explicit ordering rule for the preview mode ('Without confirm: true ... call it first'), and an explicit human-in-the-loop gate ('Ask your human before confirming'). Both when-to-use and how-to-sequence are covered.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, so safety is covered. The description adds genuine context beyond that: the optional bounded wait until a target status is reached, and that state is local and kept current by the running session — useful behavior an agent cannot get from annotations alone.

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

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

Front-loads the returned contents before the waiting behavior in two dense sentences with no filler. It is somewhat run-on in the first sentence, but each clause (returned sections, next_steps, bounded wait) 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?

With no output schema, the description usefully enumerates the returned sections and the next_steps routing hint, and it explains the wait semantics. Pitch and pagination details are absent but not critical for a single-order read, so coverage is close to complete.

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

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

Schema description coverage is 100% and the schema already documents order_id origin, the wait_for enum, and wait_seconds bounds/default. The description largely restates the wait_for example already present in the schema, so it adds little beyond the baseline expected when the schema does the heavy lifting.

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

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

States a specific verb (show) and resource (one order) and enumerates exactly what is returned — status, quote/validation, funding, purchase, tracking, dispute, ruling, refund, settlement, timeline, next_steps. The singular 'one order' plus the sibling list_orders makes the scope unambiguous without opening either schema.

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

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

Gives clear context: use it to inspect a single order and get next_steps telling which tool to call next, and it explains the wait_for case ('after request_quote'). It does not explicitly name when NOT to use it versus list_orders or a more targeted sibling, but the intended usage is easy to infer.

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 and closed-world, and the description restates read-only while adding useful behavior: source is the agent's data dir and results come newest first. It does not discuss pagination or result-size limits beyond what the schema already documents.

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 tight sentence for purpose/scope/returned fields, one for usage and the alternative, and a two-word safety tag. No wasted text, front-loaded.

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

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

With no output schema, the description enumerates the returned fields (status, shop, items, lock amount, next steps), covers usage and the sibling, and annotations cover the safety profile. Nothing needed to call it correctly is missing.

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

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

The schema documents both parameters at 100% coverage (limit default, status enum list), so it carries the burden. The description's mention of 'status' refers to a returned field rather than the filter, adding no syntax or meaning 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?

States a specific verb (list) and resource (this agent's orders) plus scope, ordering ('newest first') and the fields returned. It is clearly distinguishable from get_order, which 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?

Gives explicit when-to-use cases ('find an order id', 'see what needs attention') and names the alternative tool (get_order) with the condition that selects it (one order in full).

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, and openWorldHint, so the safety profile is covered. The description adds real behavioral context on top: re-reads trust lists from relays/registry unless refresh is false, and returns a summary plus JSON details. It does not cover failure modes or latency, but the added refresh semantics are valuable.

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

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

Front-loads the core purpose before the dense enumeration of reported fields, and every sentence carries information (purpose, contents, routing advice, refresh behavior, return shape). It is dense with domain jargon and longer than needed, which keeps it out of the top tier.

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

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

No output schema exists, so the description must characterize returns—and it does ('Returns a summary and the details as JSON'). Combined with the session-first guidance and refresh semantics, an agent has enough to call it correctly. Some network-state detail (e.g., regions/operators) is described but not elaborated, leaving minor 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 100%, so the refresh parameter's meaning is already fully documented in the schema. The description restates refresh indirectly via 'unless refresh is false' but adds no syntax or default detail beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Show) and a concrete resource (which proxy-shopping network this server is on), then enumerates exactly what is reported: relays, coordinators, chains, timelock policy, and trusted shopper × escrow combinations. It also distinguishes itself from the sibling find_offers by explaining the dependency relationship between them.

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

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

Gives a clear directive: 'Call it first in a session,' and explains the consequence of skipping it (on a new network find_offers returns nothing). This is strong when-to-use guidance tied to an outcome. It stops short of explicit exclusions or naming alternatives for adjacent cases, so it falls just below the top tier.

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 give the generic mutation profile (readOnly=false, idempotent=false, destructive=false). The description adds genuinely non-obvious behavior: no funds move now, the claim ships signed order messages copied to the shopper, and a decryption key for the delivery address is transmitted, plus that omitting confirm only previews.

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 tightly packed sentences, front-loaded with the core action and consequences before the workflow pointer. Every clause carries information; nothing is redundant filler.

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

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

For a 5-param, nested, non-idempotent mutation with no output schema, the description covers purpose, evidence payload, side-effect timing, follow-on calls, and the preview gate. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so all five parameters (including the claim enum, requested_split shape, and confirm semantics) are already documented in the schema. The description reinforces the confirm behavior but adds no format or constraint detail beyond it, so baseline 3 applies.

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

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

States a specific verb+resource ('ask the escrow to decide a funded order') and enumerates the triggering conditions (not delivered, wrong item, not released). It also names the downstream siblings (review_ruling, countersign_ruling) so an agent can place it in the dispute workflow.

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

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

Gives explicit when-to-use conditions and the follow-on sequence ('the escrow later rules a split, which you check with review_ruling and execute with countersign_ruling'). It also clarifies the preview-vs-real toggle, which governs whether it should be invoked at all.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context: the two-mode preview/execute behavior, what the preview returns (T2, current block height or chain time, whether T2 is reached, amount), and the hard failure condition before T2. It stops short of stating permission/irreversibility details beyond the timelock gating, so it is strong but not exhaustive.

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

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

Front-loaded with the core action and its 'last resort' framing, then the preview semantics, then the failure/alternative routing. Three dense sentences with no filler; every clause carries decision-relevant information.

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

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

No output schema exists, and the description compensates by describing what the preview returns and when the operation is rejected. With full schema coverage, annotations, and these additions, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters (confirm, order_id) are already fully documented in the schema, including the preview-vs-execute meaning of confirm. The description restates that preview behavior rather than adding new parameter-level detail, so baseline 3 applies.

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

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

States a specific action (take locked funds back to your wallet), the trigger (after the T2 timelock), and the actor (you alone), naming the scenario it exists for (shopper disappeared). It is clearly distinguishable from siblings like accept_refund_offer and open_dispute, which it explicitly points at.

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 ('last resort', 'after the T2 timelock'), when-not ('before T2 the chain rejects it'), and named alternatives ('prefer accept_refund_offer or open_dispute while the shopper responds'). An agent has a complete decision rule without reading any schema.

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 and openWorldHint=false, and the description is consistent with them. Beyond the annotations it adds genuine behavior: no pull request is opened, the local data dir identity pubkey is used by default, and a shopper entry must carry the shopper node's key. It stops short of describing validation or failure behavior.

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

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

A single front-loaded sentence delivers purpose, then a compact per-role field enumeration, then the pubkey default and the 'opens no pull request' caveat. It is dense and the inline JSON shapes are hard to scan, but nearly every clause carries non-redundant 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?

There is no output schema, so the description must explain what comes back, and it does: the exact file and path to commit. Combined with the per-role shapes, the local-only boundary and the pubkey rule, an agent has enough to call it correctly; only error/validation behavior is 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: which fields each role's file must contain (e.g. shopper requires escrows and payments, escrow requires sla_days, operators use regions) and the pubkey default rule. That per-role requirement mapping is the main value beyond the flat property list.

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 deliverable: return 'the exact JSON file and path to add in a pull request' to a named registry repo. It also frames the outcome (the entity gets listed once the maintainer merges), which no sibling tool does, so an agent can distinguish it from become_shopper or report 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?

Usage context is clear — use this when a shopper, escrow, operator or coordinator needs to be added to the registry — and it explicitly bounds the action with 'Local; opens no pull request itself.' It does not, however, name an alternative (e.g. become_shopper) or state when not to use it, which matches the rubric's 'clear context, no exclusions' level.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the description is not carrying the whole load. It still adds real value: it explains that one signed message is sent, that no funds move and the order is otherwise unchanged, and that the operator may remove the reported party.

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 action and target before the evidence and side-effect details. No filler, though the parenthetical examples add some length.

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

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

With no output schema, the description usefully covers outcome effects (no funds move, order unchanged, operator may delist) for a moderate-complexity action. It omits only repeat-call behavior and failure handling for an explicitly non-idempotent tool.

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

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

Schema description coverage is 100%, with the order_id format sourced to request_quote/list_orders already documented in the schema. The description only reinforces that the order's signed messages are attached as evidence; it adds no new per-parameter semantics beyond the schema baseline.

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

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

States a specific verb (report), a specific target (the order's shopper or escrow), and the recipient (the operator that listed them). This is distinguishable from siblings like open_dispute or review_ruling without opening any schema.

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

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

The evidence examples ('a dishonest ruling, a quote that failed validation, no delivery') imply when this tool applies, but no alternative is named and no when-not condition is given. An agent must infer that this is the escalation path distinct from open_dispute.

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

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

Annotations declare the mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), which is typical for a create operation, and the description does not contradict them. It adds real behavioral value: signed/encrypted Nostr order request, address encrypted end-to-end with escrow able to read only in a dispute, 'nothing is paid', and the timeout behavior (order stays open).

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 the key selection rule, then the behavioral disclosure, then the return summary and next steps. Dense but every clause carries information; slightly long, though 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, the description still covers what is returned (order id, price breakdown, rate deviation, recomputed 2-of-3 escrow address, timelocks T1/T2) and what happens on timeout, plus the follow-up tool. Nothing material is missing for a 9-parameter flow tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-call semantics the schema cannot: offer_index must reference the last find_offers result with the same shop_url/region/payment, and shopper+escrow are the alternative to offer_index. It does not restate field formats, which the schema already handles.

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 ('create an order', 'request a quote') with scope ('one shopper × escrow combination') and explicitly frames itself as 'Step 2' of the flow. It distinguishes itself from find_offers, accept_quote and cancel_order by name.

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

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

Gives explicit routing: offer_index must come from the last find_offers with matching shop_url, region and payment, or supply both shopper and escrow pubkeys instead. It names the next alternatives (accept_quote or cancel_order) and the fallback (get_order) if no quote arrives.

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 and idempotentHint=true, so 'Read-only.' is largely redundant. The genuinely additive behavior is that this tool cross-checks the escrow's on-chain transaction against the declared split rather than merely displaying it, but that is stated implicitly through the matching logic rather than spelled out as a verification step or its failure modes.

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

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

Purpose is front-loaded in the first clause and the decision rule follows immediately. The standalone 'Read-only.' sentence duplicates the annotation and is the one element that does not earn its place, but the rest is dense and waste-free.

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 return-value burden and does so: the split breakdown, the reason, and the match verdict. Combined with annotations covering safety and idempotency, an agent has everything needed to call and act on the result.

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

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

Schema description coverage is 100% and the single order_id parameter is documented in the schema with its 32-hex format and provenance (request_quote or list_orders). The description adds no format, sourcing, or constraint detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Show the escrow's ruling for a disputed order') and enumerates exactly what the result contains: the split across the three parties, the reason, and whether the escrow transaction actually pays that split. This is clearly distinguishable from countersign_ruling (executes) and report (escalates).

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 branching guidance: if the ruling matches the transaction, countersign_ruling executes it; if it does not, do not countersign and consider report. Names both alternatives and the condition that selects each, leaving nothing to inference.

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

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

Adds context beyond annotations: 'Read-only: queries the chain, never signs' reinforces readOnlyHint and clarifies no transaction signing occurs. 'The key is created on first run in the data dir' is important side-effect/lifecycle info not in annotations, and the pointer to export_backup is useful. Could have said more about chain latency or rate limits, but this is solid.

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

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

Front-loads the main purpose and usage. However, the second sentence contains a grammatical error ('where the network has USDC its EVM address') that hurts readability, and the key-creation detail is buried at the end. Still reasonably compact.

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

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

For a zero-param read-only tool with no output schema, the description covers what is returned, when to call it, safety, and first-run key behavior. One awkward sentence reduces polish, but an agent has enough to invoke 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?

No parameters, so baseline is 4. The description complements by specifying exactly what identity/balances are returned, which is valuable since there is no output 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?

Specific verb+resources: shows identity (Nostr pubkey), BTC signet address and balance, and EVM address with USDC/ETH balances. Distinguishes itself from siblings like network_info and export_backup through concrete output contents. Slightly impeded by an awkward grammatical slip ('where the network has USDC its EVM address').

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: 'Use it before fund_order to check that the wallet can pay the quote, and to get the address to fund'. Names the alternative funding paths (signet faucet; on the lab: lab_faucet). Routes the agent clearly.

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