Chargeback representment

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

The description discloses that the tool 'costs credits from the account wallet,' a resource-consumption side effect that the annotations do not cover (they only state readOnlyHint=false, which implies mutation but not cost). This is genuinely valuable behavioral context beyond the structured annotations and directly affects whether an agent should invoke it. It could add more (e.g., persistence or irreversibility), but the cost disclosure is a strong addition.

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 two short sentences with no filler. The core purpose is front-loaded, and the credit-cost caveat is appended efficiently. It earns a 4 for being tight, though the brevity leaves out parameter and usage guidance that the tool 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?

This is a complex tool (5 parameters, a nested transaction object, an enum, no output schema, sparse annotations), so the description carries a heavy burden. It lists four output types, which helps the agent know what to expect, but it omits output structure, parameter semantics, and usage context. For a tool with no output schema and 20% parameter coverage, this is insufficient.

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 20%, with just 'reason' documented. The description does not compensate: it refers generically to 'dispute details' without explaining context, network, evidence, or the transaction object. The network enum is especially important because reason codes vary by card network, yet nothing in the description maps inputs to the stated outputs. With coverage this low, the description should have explained parameters and did 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?

The description clearly states what the tool produces: given dispute details it generates a representment narrative, evidence checklist, reason code, and win-likelihood. This is a specific transformation that distinguishes it from siblings (e.g., parserail_fraud_flag handles fraud flagging, not representment). It loses a point because the arrow notation ('Dispute details →') is informal and omits an explicit verb for the operation.

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?

No guidance is given on when to invoke this tool versus the many parserail siblings. There is no mention of when a chargeback representment is needed, no exclusions (e.g., 'not for first-time disputes'), and no alternative tools named. The agent is left to infer the use case entirely from the name.

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