create_listing

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

Annotations only declare readOnly=false, destructive=true, openWorld=true; the description adds materially different facts — the listing is always created in a pending state, there is no publish or moderation path from this tool, and uploads are restricted to user-selected local images. It does not describe what happens on rejection or consent mismatch, and does not explain the destructiveHint, so it stops short of full behavioral coverage.

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?

Four tightly packed sentences, front-loaded with the action and immediately followed by the consent prerequisite, so the most safety-critical instruction is not buried. Every sentence carries a constraint or prohibition; density is high but no sentence is filler.

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 9-parameter, 8-required tool with a nested acceptance object, no output schema and thin schema descriptions, the description covers the highest-risk areas (consent provenance, image sourcing, pending outcome). It leaves the optional country parameter and the contactUrl format unexplained, but no critical gap remains for correct invocation.

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 11%, so the description has to compensate and it partially does: it constrains photos (user-selected local files, 1-6, 8 MB combined, adding a minimum the schema lacks) and ties the acceptance/version and fullName fields to get_publication_rules and to the user. Parameters such as title, description, category, city, contactUrl and country still receive no semantic guidance beyond the schema.

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 and resource ("Create your user's listing") plus the resulting state ("for moderation"), which separates it cleanly from update_listing and list_my_listings. The follow-on sentence adds scope boundaries (pending only, no publish or moderation capability) so an agent knows exactly what the call does and does not accomplish.

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 explicit preconditions: show the final text, photos, contact and city to the user and obtain each consent via get_publication_rules before calling. It names the alternative sibling to consult and includes negative guidance (never fabricate consent or name, never import someone else's listing or photos), which is exactly the when/when-not coverage this dimension rewards.

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