growsurf_refund_transaction

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

Annotations already declare destructiveHint=true and readOnlyHint=false, covering the mutation aspect. The description adds valuable behavioral context: 'Already-paid commissions are not clawed back (recorded for tax only),' which is critical for understanding side effects. It also states it reverses or adjusts the referrer's commission, going beyond the annotation information.

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 concise and well-structured: it front-loads the core purpose and inverse relationship, then adds usage guidance and key behavioral notes. Every sentence contributes meaningful information with no redundancy or 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?

Given the tool's complexity (18 parameters, anyOf constraints), the description covers the essential semantics for a refund operation: how to identify the original transaction, the amendment types, and the commission adjustment behavior. It does not explain every parameter or the return format, but with an output schema present and the core logic well-covered, it is fairly complete for the typical use case.

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 6%, so the description must compensate for the sparse parameter documentation. It explicitly explains amountRefunded (omit for full refund) and campaignId (defaults to GROWSURF_CAMPAIGN_ID), but leaves many other parameters (participantId, externalId, transactionId, etc.) unexplained. The description adds value for the most important parameters but does not fully compensate for the coverage gap.

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

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

The description clearly states the action ('Record an amendment') and the resource ('previously recorded affiliate transaction'), and specifies it covers refunds, partial refunds, and chargebacks. It also identifies itself as the inverse of growsurf_record_sale, which distinguishes it from functionally related tools in the sibling list.

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 provides clear guidance on how to use the tool: identify the original transaction with the same identifier sent when recording, omit amountRefunded for a full refund, and target a specific campaignId if needed. It gives practical instructions but does not explicitly state when not to use it or how it compares to other alternatives beyond the inverse relationship.

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