create_draft

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

With no annotations provided, the description must carry the full behavioral disclosure. It explicitly states the draft is private until submitted, that 'nothing goes live from this tool,' and that submissions enter a moderation queue as pending_review. This is rich, honest transparency about side effects and lifecycle.

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 a single, well-organized paragraph with three sentences: purpose, parameter constraints, and behavioral notes. It front-loads the most important information and contains no filler. Each clause earns its place.

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?

The description covers purpose, key parameters, lifecycle behavior, and moderation. Given that an output schema exists (though not shown here), the return values are likely structured. It misses a couple of minor parameter details but is otherwise comprehensive for a create tool.

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 explain parameters itself. It covers item_type (values), name (max length), description (min length), and category (source). However, it omits price_cents (likely currency/semantics) and tags (array of strings), and doesn't mention default values. Partial compensation, but not complete.

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: 'Create a new draft listing owned by the seller and return its id and web editor URL.' This clearly states the action and the return value, and it distinguishes the tool from siblings like update_draft and submit_for_review by framing creation and handoff.

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 provides clear context: it tells the agent to use update_draft afterward for 'content fields,' and it points to list_categories for the category slug. It implies that this is the first step in a workflow, but it doesn't explicitly state when not to use this tool or name alternative creation entry points, so it falls just short of a 5.

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