firestarter_cancel_drop

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds valuable behavioral context beyond annotations: the cancellation is permanent (stops being visible, can never be approved), and it is state-dependent (only pending requests). However, it doesn't disclose any additional side effects like whether it triggers notifications or affects related records, but given annotations cover destructive intent and idempotentHint=true, a 4 is appropriate — the description adds meaningful state-specific behavior that annotations don't.

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?

Two sentences pack all essential information: what the tool does, preconditions, permanence, and the fallback action. Front-loaded with the primary action and scoped immediately. No fluff or redundancy.

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 destructive, state-dependent mutation with two simple string parameters, the description covers: the precondition (pending, own market), the effect (invisible to seller, never approvable), the fallback (re-create), and the invalidity states. With annotations covering the destructive/idempotent profile and full schema coverage, this is nearly complete. A minor gap: it doesn't state what the response looks like, but since there's no output schema and the state outcome is clear, a 4 is fair rather than 5.

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 both parameters (program_id and drop_id) are documented with descriptions and source references. The tool description aligns with the schema by explaining the drop_id comes from create_drop or market_drops, and program_id from my_markets. Since the schema already carries the semantic weight, the description doesn't need to add much. Baseline 3 is correct.

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 (withdraw a drop request you created) and the specific context (pending seller approval on a market you own). It defines who can use it, what it acts on, and the exact state required. It distinguishes itself from siblings like firestarter_approve_drop and firestarter_reject_drop by focusing on cancellation by the creator, not the seller. The verb+resource is specific and unambiguous.

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?

Explicitly states when to use: only on still-pending requests you created on a market you own. Explicitly states when not to use: if already live, expired, exhausted, or already decided, it can't be cancelled. It even references the alternative action (create a new request with firestarter_create_drop) if the agent changes its mind. This is exemplary usage guidance.

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