pipeline_refund

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.