update_listing

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

Annotations only declare destructive=true, openWorld=true, readOnly=false; the description adds substantial behavior beyond that: omitted fields and photos are preserved, new photos append, keepPhotoIds controls retention, and the listing returns to moderation afterward. The only notable gap is that it never says what happens on a revision mismatch (error shape) or what 'moderation' entails for the user.

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?

Three dense sentences with no filler, and the primary verb-plus-resource is front-loaded before the constraints. The telegraphic fragments ('Returns to moderation.', 'Omitted fields/photos stay') trade a little readability for compactness but each clause carries distinct information.

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, nested-object mutation with no output schema, the description covers the state semantics an agent most needs: partial-update behavior, photo merge rules, moderation re-entry, and revision staleness handling. Minor omissions are the failure mode on stale revisions and the fact that acceptance is mandatory on every call, which only the schema reveals.

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 description coverage is only 8% across 12 parameters, so the description must carry the load. It does explain the semantically hard ones — revision currency, acceptance as fresh explicit consent, photos appending, and keepPhotoIds selecting retained photos — but says nothing about the field-level parameters (title, description, price, city, country, category, contactUrl) or how they interact with the partial-update rule.

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 and resource ('Edit your user's listing') and immediately names the three inputs that make the edit valid: current revision, fresh publication consent, and changed fields. It is clearly a partial-update tool, distinguishable from create_listing and archive_listing by implication, though it never names a sibling explicitly.

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 real preconditions — use the current revision, obtain fresh explicit consent, and 'Never retry a stale revision silently' — which is meaningful when-to-use guidance for a mutation. It does not, however, route the agent between this and siblings (e.g. when to archive versus edit), nor state what to do after a revision conflict beyond not retrying blindly.

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