archive_listing

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

Annotations already flag destructiveHint=true and openWorldHint=true; the description adds the important qualification that data is not physically deleted and external copies are untouched, effectively softening 'destructive' into a reversible archive. That is real added value. However, it never says whether an archived listing can be restored, nor what happens if the supplied revision is not current, which is exactly the failure mode an agent needs to anticipate.

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 compact sentences with no filler, and the operational constraint is front-loaded ahead of the non-deletion clarification. Structure is good; only the density of the first sentence ('only your user's listing with the current revision, after their explicit instruction') packs three separate conditions into one clause chain.

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 two-parameter mutation with no output schema, the description covers scope, intent precondition, and the non-destructive nature of the operation. The remaining gaps — revision-mismatch behavior and restorability — are meaningful but narrow, and annotations already carry the destructive/open-world profile.

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 0%, so the description must carry the load for two required parameters. It partially does for 'revision' by implying a must-be-current concurrency check, but says nothing about 'id' being the listing identifier or the expected UUID form. Half the parameter semantics remain undocumented.

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 ('withdraw') and resource ('listing'), plus scope ('only your user's listing') and a precondition ('with the current revision'). The second sentence clarifies that 'withdraw' is an archive, not a hard delete. It does not name a sibling to contrast with, but among the given siblings (get_listing, update_listing, create_listing) the operation is 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?

Gives two real usage constraints: only the calling user's own listings may be archived, and it must follow the user's explicit instruction — a meaningful directive for an agent to confirm intent first. It does not name an alternative tool or state what to do when the revision is stale, so it stops short of full routing guidance.

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