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

Annotations already mark the tool readOnly and non-destructive, but the description adds meaningful behavioral context: it explicitly states that no user confirmation is required because no raw attribute values are exposed, clarifies the distinct meanings of status versus channelStatus, and explains that itemId is the value to pass to get_marketplace_item_report. No contradictions with annotations exist.

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 dense but organized: it front-loads the core purpose, then gives the exact return shape, then parameter semantics, filters, pagination, and cross-tool usage. Every clause adds information needed to invoke the tool correctly, and there is no filler or repetition of the tool name.

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?

With 8 parameters, no output schema, and no enums, the description carries a heavy burden, and it fully meets it. It specifies the complete return structure, the semantics of status fields, the behavior around confirmation, filtering, pagination, the source of marketplace_id, and the project_id edge case. An agent has everything needed to call this tool correctly and to decide whether a different tool is required.

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?

Although the schema already documents most parameters, the description adds significant meaning: marketplace_id is identified as 'the id from list_marketplaces', project_id is explained as optional and inferred for single-project customers, koongo_status is illustrated with 'e.g. the failed items', and the mapping from return fields to downstream tool parameters is made explicit. This materially exceeds the schema's descriptions.

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: 'List the individual listing items of one marketplace — the per-product rows of what is (or should be) listed on the channel.' It clearly scopes the tool to a single marketplace and distinguishes it from the closely related get_marketplace_item_report, so an agent can tell exactly what this tool returns.

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 gives explicit routing guidance: it says list_marketplace_items needs no confirmation because it never returns attribute values, while get_marketplace_item_report should be used when actual values or full error reports are needed. It also explains how to use filters to 'drive a fix', how pagination works with limit/offset, and when project_id is required versus optional.

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