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

With no annotations, the description carries the full burden and does so well: it discloses the trial allowance, that every call returns the hub's signed receipt, that the hub answers 402 once allowance is spent, and that the tool reports the 402 honestly rather than fabricating a result. It also names all three paid-access routes (X-API-Key header, payment_channel + secret, on-chain x402), covering auth and rate-limit behavior.

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

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

Front-loaded with the core purpose and free of filler; every clause about trials, 402 handling, and payment routes is substantive. It is one dense paragraph where a short list of payment modes would scan faster, but nothing is wasted.

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

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

For a 12-parameter, no-annotation, no-output-schema tool, the description covers the essential behaviors: trial limits, 402 fallback, receipt signing, and all payment paths. The per-parameter details are mostly handled by the 75%-covered schema, so the remaining gap is minor.

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 already 75%, so the baseline is 3. The description adds genuine value by grouping parameters into coherent payment modes (X-API-Key, payment_channel + secret, x_payment + nonce + secret), clarifying which params travel together in a way per-field schema text does not.

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 (invoke) and resource (a capability found via market_search), making the search-then-invoke workflow unambiguous. It is cleanly distinguishable from the sibling market_search, which finds rather than calls capabilities.

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?

Makes clear this is the call that follows market_search and explains the trial-then-paid escalation path, including what happens when the free allowance runs out (402 + next_steps). It does not address when to prefer pipeline_invoke over this tool, leaving one sibling relationship unaddressed.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It explains the search behavior ('by what you need, in plain words') and precisely describes the match result contents, including price and input fields. It does not mention auth, rate limits, or error behavior, but for a read-only search tool the disclosed behavior is sufficient.

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 a single, efficient sentence with no filler. It front-loads the core action, then immediately states the output contract and relationship to market_invoke. Every clause 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 and no annotations, the description compensates by describing the key return fields and their purpose. It covers the main information an agent needs: search input style, result fields, pricing, and downstream invocation. It does not cover edge cases like empty results or exact matching behavior, hence not a perfect 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a bit of context by tying results to market_invoke and explaining what `input` represents, but it does not meaningfully expand on parameter semantics 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?

Description opens with a specific verb and resource: 'Search this hub's catalogue of live data and computation'. It clearly defines the tool's purpose and differentiates it from siblings like market_invoke by stating that results contain IDs to pass to market_invoke.

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

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

The description clearly implies when to use the tool: when you need to discover marketplace offerings before invoking them. It names market_invoke as the follow-up tool, providing a usage context. It does not explicitly state when not to use it or mention alternatives, so it misses full explicit 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?

With no annotations, the description carries the full burden and does so well: it declares payment-mode mutual exclusivity, that 'pending is not failure', that the same run should be repeated rather than rerun from scratch, and that a replacement purchase must not be created after a lost response. This is exactly the idempotency/retry context an agent needs. It stops short of covering error surfaces, rate limits, or what a successful response yields.

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?

Telegraphic and front-loaded: the core action leads, followed by param selection rules and then retry safety. Nearly every clause carries an instruction, though the staccato style makes the workflow rules slightly harder to parse on first read than plain prose would.

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

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

For a two-phase payment workflow with no annotations and no output schema, the description supplies the mode-selection logic, the retry/pending semantics, and state retention guidance. The main remaining gap is what the caller should expect back and how failures other than 'pending' manifest, but the critical call-time decisions are covered.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the critical ambiguity: it explains when to populate authorizations versus transactions versus neither. run_id and access_token roles are only loosely implied by 'retain run_id/access_token', but the hardest parameter decision is fully resolved.

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 ('Execute or continue the SAME prepared graph') and implicitly distinguishes itself from pipeline_prepare (which prepares the graph) and pipeline_status (which it names as the read-only alternative). The word 'SAME' and 'prepared' make the relationship to siblings inferable, though the description never spells out what the graph actually accomplishes.

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

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

Explicitly routes the agent: submit authorizations when the signed quote enables gas_sponsorship, otherwise buyer-signed transactions, and none for free steps, with a hard exclusion ('Never submit both payment modes'). It also names pipeline_status as the fallback when awaiting a pending result, giving both when-to-use and when-to-use-something-else.

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?

With no annotations, the description carries the full burden and does so well: it discloses that no work or payment occurs (dry-run nature), the wallet requirement branching on free vs paid steps, the gas_mode semantics, the output fields to inspect (ready/blockers, gas_sponsorship), and a security constraint (sign offers locally, never supply a private key).

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 outputs, then prerequisites, then the security note, then the follow-up tool. Six short sentences with no filler; every one adds an actionable fact.

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 compensates by naming the response fields to inspect (ready/blockers, gas_sponsorship). Combined with the wallet/gas_mode rules and the next-step pointer, an agent has enough to call it; only max_budget_usd semantics remain unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate. It meaningfully explains wallet (only needed for paid steps) and gas_mode (required vs auto), and implies nodes via 'validate a graph', but max_budget_usd is never mentioned and node structure/limits 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 (validate) and resource (a graph) plus the concrete outputs (signed quote, payment offers). It explicitly positions the tool relative to the sibling pipeline_invoke ('Then call pipeline_invoke'), so an agent can separate the two 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 sequencing guidance ('Then call pipeline_invoke') and conditional usage for gas_mode=required vs auto. It stops short of stating when not to use it or what to do on failures, but the context for selecting it is unambiguous.

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?

With no annotations, the description carries the full burden and does substantial work: it names the recipient (original buyer), the amount (paid step price), the gas payer (sponsor), idempotent resume behavior via authorization preservation, and the return (separately signed credit note with the original bill unchanged). Missing only explicit permission/auth requirements and rate/limit 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?

Three dense sentences, front-loaded with the primary action, no filler. Every sentence adds information (action, money flow, idempotency, return).

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

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

For a mutation tool with no annotations and no output schema, the description supplies the key behavioral context an agent needs: who pays, who receives, idempotency handling, and the return format. The remaining gap is parameter-level documentation for the three required identifiers.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the 'authorization' parameter's purpose (preserving/resuming after a lost response), which is genuinely useful, but leaves run_id, step_id, and access_token undocumented with no format hints.

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: 'Submit the original seller's refund authorization or resume the SAME refund.' This clearly distinguishes it from prepare/status siblings, though it does not name those siblings explicitly. An agent can tell this is the execution/lifecycle step for a refund.

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?

Implies two usage modes (submitting an authorization vs. resuming an existing refund) and hints at the lost-response recovery scenario. However, it never names pipeline_refund_prepare or pipeline_refund_status as alternatives or states the preconditions that select this tool over them.

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?

With no annotations, the description carries the full burden and does disclose meaningful traits: 'This moves no money' (despite the refund name) and the hard security constraint 'never send a private key.' It still omits what state preparation creates (reservation, expiry, idempotency) and what the seller-approval flow requires of the caller afterward.

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

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

Four short sentences, front-loaded with the core action, each carrying distinct information (what it does, that no money moves, the auth requirement, the prerequisites). No filler or restatement of the name.

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

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

Covers the safety profile and preconditions well, which is the critical part, but with no output schema and no annotations it should also signal what preparation yields and how to proceed (the follow-on pipeline_refund call). That workflow context is absent.

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

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

Schema description coverage is 0% and the description says nothing about run_id, step_id, or access_token. The run_id pattern ('^paid_...') in the schema hints at format, but the description does not explain that run_id identifies the finished pipeline run, that step_id must be a verified paid step, or how access_token relates to the caller.

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+scope: 'Prepare a cash refund for a verified paid step of a finished pipeline,' and clarifies it is a preparation step, not the execution. It does not, however, name the sibling it is distinguished from (pipeline_refund / pipeline_refund_status), so an agent must infer the routing rather than being told.

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?

Provides real preconditions ('seller must approve the authorization locally', 'refunds require seller cooperation and a configured gas sponsor'), which implies when the call can succeed. But it never states when to use this versus pipeline_refund or pipeline_refund_status, nor the ordering of the refund workflow, so the routing guidance is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that no private key or RPC is required and that no transaction is broadcast, and it clarifies the meaning of a pending status. It still does not mention required permissions or the access_token, but it covers the most important non-obvious behavioral traits.

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, each earning its place. The core read-only nature is front-loaded, followed by a useful operational constraint and a critical pending-status instruction. There is no filler.

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

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

For a tool with three required, undocumented parameters, no output schema, and no annotations, the description is incomplete. It covers key behavioral points about non-broadcasting and pending handling, but it says nothing about input meaning, authentication details, or what the signed credit note return looks like.

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

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

Schema description coverage is 0% and the description does not mention any of the three required parameters (run_id, step_id, access_token). It adds no meaning, format expectations, or constraints beyond the bare schema names.

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 ('Read') and resource ('saved cash-refund status and signed credit note') and explicitly distinguishes this from a broadcasting operation ('without broadcasting a transaction'). It does not name a sibling tool directly, but the contrast with pipeline_refund is clear enough.

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

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

The description gives important in-state guidance ('Pending means resume the same refund, never send a replacement transfer'), which tells the agent what to do when status is pending. However, it does not state when to use this tool versus pipeline_refund, pipeline_refund_prepare, or pipeline_status, so broader usage context remains implied.

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

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

With no annotations, the description carries the safety profile itself and does it well: it is a pure read, does not broadcast payments, does not invoke providers, and needs no wallet signer or blockchain RPC. That is meaningful behavioral context for a mutation-adjacent domain. It stops short of stating whether access is scoped or whether the cached result can be stale.

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, purpose front-loaded, each adding distinct value: what it does, the constraints under which it runs, and a pointer to the actionable recovery.action field. No filler.

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

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

No output schema, but the description compensates somewhat by naming the cached signed result and the recovery.action field. However, for a tool with two fully required, wholly undocumented parameters and no annotations, it leaves the auth token's origin and the run_id's source unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate for two undocumented parameters and does not: neither run_id nor access_token is explained, nor is where the access_token comes from or the paid_ hash format. The schema's regex and length bounds partially cover the gap, but the text adds nothing.

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 (Read) and resource (an existing pipeline), and the read-only framing implicitly distinguishes it from the pipeline_prepare/pipeline_invoke siblings. It never names those siblings, so an agent must infer the routing rather than being told 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?

"Inspect recovery.action for unresolved work" hints at the retrieval use case, and 'without broadcasting payments or invoking providers' implies when to prefer this over an execute-style sibling. There is no explicit when-not or named alternative, so usage is only implied.

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