firestarter_seller_disputes

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

Annotations only provide readOnlyHint: false and destructiveHint: false, so they don't disclose state changes. The description adds valuable behavioral context: that refund 'lift[s] the escrow freeze', that listing returns dispute_id, and the exact semantics of each action (refund, contest, split). This goes beyond the annotations. It doesn't mention side effects like emailing the buyer or irreversibility, but the action descriptions are informative enough.

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 longer than ideal but every sentence contributes: purpose, exclusion, usage pattern, action definitions, and trigger phrase. It is well-structured, moving from what it does to when to use it to how to invoke. It could be tightened slightly, but it earns its length with high information density.

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?

The tool has two modes (list vs act), five parameters, and a sibling to disambiguate. The description covers both modes, all three actions with examples, and the listing behavior (shows dispute_id). It doesn't describe the output format beyond that, but no output schema exists, so the description provides a reasonable hint. Given the complexity, it is quite 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 coverage is 100%, so baseline is 3. The description adds orchestration semantics not explicit in the schema: calling with NO arguments lists disputes, and acting requires dispute_id plus an action. This clarifies the dependency between dispute_id and action, which the schema does not enforce. It also reiterates the split constraint (percentages sum to 100), but that's already in schema descriptions. The added usage pattern justifies a 4.

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 starts with a specific verb+resource: 'View and resolve disputes on orders the user is SELLING', immediately clarifying scope. It explicitly differentiates from sibling tool firestarter_disputes by naming it and contrasting seller vs buyer side, which is exactly what the dimension requires.

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 explicit when-to-use guidance ('Use when a seller mentions a dispute, complaint, refund, chargeback, or return') and an explicit when-not-to-use with a named alternative ('If the user is asking about something they BOUGHT ... use firestarter_disputes instead'). This is textbook usage guidance.

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