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

Goes far beyond the annotations by disclosing the multi-call protocol, the 3+ photo requirement, the £10.99 fee with launch-promo waiver, the OAuth scope `listings:publish`, and the 24h undo email. The idempotentHint annotation is given operational meaning ('keep calling with the same draftId until step:"live"'). Consistent with destructiveHint=true since publishing is a state-changing, fee-bearing action.

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 opening sentence states the purpose immediately, then flow, idempotency, auth, and example follow in logical order. Every sentence carries non-redundant information, though the example flow partially restates the earlier sequencing.

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 15-parameter, multi-call, payment-bearing tool, this is strong: flow, auth, fees, and idempotency are all covered, and an output schema covers return values. Minor gaps: no error-path guidance (e.g., stolen-bike flag from frameSerial, fewer than 3 photos) and ambiguity about whether listing details must be re-sent with draftId on subsequent calls.

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 only 33%, so the description carries the burden — but it only compensates for draftId by explaining its lifecycle (omit on first call, reuse until live). The remaining ~10 parameters (groupset, willShip, frameSize, knownIssues, priceGbp, etc.) receive no added meaning from the description. The two enum parameters are self-describing via their values.

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: 'Publish a Cyclesite listing on the user's behalf.' The multi-step explanation adds concrete meaning and the example flow ('sell my Trek Domane') anchors the tool's role. Clearly distinct from draft_listing in the sibling list — drafting vs publishing.

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 sequencing (first call without draftId, subsequent calls with draftId) and a usage example. Explains when step:'live' versus step:'payment_required' occurs, and instructs the agent to keep calling until step:'live'. However, it never names an alternative tool or states when not to use it — no explicit exclusions.

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