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

Beyond the annotations (readOnlyHint, destructiveHint), the description discloses the sensitive-gate behavior — first call withholds currentValue, returns a sensitiveGate, and requires re-call with acknowledge_sensitive:true after user approval. It also explains the return payload semantics: raw codes vs human labels, error fields, source values, and level meanings. This is substantial behavioral context the annotations alone would not provide.

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 long but every sentence earns its place. It front-loads the core purpose, then packs return semantics, gate behavior, parameter sourcing, and the sibling distinction into a dense but scannable format. There is no filler or repetition of schema details.

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 no output schema, the description carries the full burden of explaining return values — and it does so thoroughly, covering status fields, error entries, enumeration values, the sensitiveGate flow, and parameter dependencies. Nothing needed to invoke the tool correctly is missing.

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 25%, but the description compensates fully: it explains item_id and marketplace_id provenance, project_id optionality and inference, and the acknowledge_sensitive two-call flow. Every parameter's meaning and usage is clarified beyond the bare 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?

The description opens with a specific verb/resource pair — 'Get the detailed report for ONE listing item of a marketplace' — and immediately states the tool's purpose. It also explicitly distinguishes itself from the sibling get_marketplace_report ('For the marketplace-wide breakdown'), so an agent can select it without ambiguity.

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 clear when-to-use guidance: single item vs marketplace-wide, and names the alternative tool. It also tells the agent where the IDs come from (list_marketplace_items, list_marketplaces), explains when project_id is needed, and routes to list_projects when required. This is explicit, actionable selection guidance.

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