firestarter_reprice

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

Annotations only signal destructiveHint=true, readOnlyHint=false, and openWorldHint=true. The description does the heavy lifting: it discloses that shipping is deprecated and always estimated live, that re-firing the verification gate can trip on a price CUT, that it applies to paused/out-of-stock listings, that the listing is moved to draft and stops being buyable, and that the response is a conditional success. This precisely matches and greatly enriches the destructiveHint annotation — no contradiction.

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 dense and long, but every clause earns its place — the verification-gate thresholds ($500, luxury category), the price-cut edge case, the paused/out-of-stock scope, and the conditional-success outcome are all decision-critical for an agent. Purpose is front-loaded before the caveats, so the most important information appears first. Slightly verbose, but not wasteful.

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 6-param mutation tool with no output schema but high behavioral complexity, the description covers the purpose, the destructive consequences, the trigger thresholds, and the response semantics fully. The only gap is procedural guidance on valid parameter combinations (whether listing_id alone suffices and whether price fields are mutually required), which the schema leaves implicit. No output schema means the agent must infer return shape, but the description's dovetailing with annotations keeps it nearly 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 all six parameters are already documented. The description adds some value by clarifying that 'shipping' is deprecated and ignored, and by tying base/floor/ceiling/dynamic_pricing to their intended effects. But it adds no syntax, units, or format details beyond the schema, and doesn't clarify which parameter combinations are valid (e.g., must at least one price field be supplied along with listing_id). Baseline 3 is appropriate when the schema is fully populated.

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?

States a specific verb-resource ('Adjust pricing or rules for an existing listing') and enumerates the exact fields it touches (base price, floor/ceiling limits, dynamic pricing, pricing rules). It clearly separates this from the ~80 siblings that deal with creating, deleting, or shipping listings. Even the title 'Change Listing Price' is rendered specific by the field enumeration.

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 gives strong 'when-it-applies' context — it explicitly covers paused and out-of-stock listings, not just live ones, and explains when the verification gate trips on a price cut. However, it never explicitly differentiates from firestarter_update_listing (the nearest sibling), nor states when one should prefer the other. The follow-up action (firestarter_verify) is named, which is good, but selection guidance versus alternatives is absent, leaving the agent to infer which tool handles general listing edits.

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