firestarter_disputes

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

Annotations already declare readOnlyHint=false and destructiveHint=true, lowering the burden. The description adds meaningful behavioral context beyond that: it explains what each action does ('withdraw' = drop the dispute, 'escalate' = ask Firestarter to review), which behaviors change state, and the operational pitfall that images must be passed as public URLs rather than base64 because a photo 'is far too large to survive being printed into a tool call.' It does not, however, fully describe response structure or side effects such as rating impacts, so it stops just short of 5.

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 dense paragraph, but every sentence earns its place: audience, triggers, invocation patterns, and the sibling alternative. The key scoping statement (buyer side) is front-loaded. It is long, but the length is justified by 11 parameters and 8 actions; only a modest amount of tightening could remove without losing signal.

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 complex tool with 11 parameters, 8 actions, and no output schema, the description covers the full decision space: when to call, what to pass for each use case, which parameter combinations are valid, and what the user is expected to see (list of disputes, status of one order, or full thread). An agent has everything needed to select, compose, and invoke the tool correctly.

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 the baseline is 3. The description genuinely adds beyond the schema by documenting the calling idioms: how the tool behaves with no arguments, how execution_id can look up a dispute, and how execution_id can stand in for dispute_id on action parameters. The 'never rebuild it as base64' guidance in the description foreshadows and reinforces the schema's image_urls note, adding operational meaning the schema alone would not convey.

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 opens with a specific verb-plus-resource statement: 'open, check, and resolve disputes on orders the user BOUGHT.' It sharply differentiates itself from firestarter_seller_disputes by naming the sibling and stating 'This is the BUYER side,' so an agent can distinguish the two without needing to inspect their schemas.

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 explicit triggers ('Use this whenever a buyer asks...') with concrete examples like 'item never arrived, arrived damaged / wrong / not as described'), enumerates the exact actions available (post a note, accept/reject/counter, withdraw, escalate), and gives a clear exclusion: 'for disputes on orders the user is SELLING, use firestarter_seller_disputes instead.' The when and when-not guidance is complete.

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