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

Annotations already cover read-only/idempotent safety, and the description adds substantial context beyond them: the two-phase sensitive-value gate, the meaning of each error's source (export = Koongo-side fixable mapping, adapter/api_error = channel-side rejection), and the raw-code vs human-label distinction. The only gap is that it is very dense about the gate flow relative to the rest of the read behavior, but 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?

It is front-loaded with the purpose and then flows into response shape, error semantics, and the sensitive gate. The long inline enumeration of response fields is defensible because no output schema exists, but the single-block paragraph is dense and a few phrases (e.g. restating raw vs human wording twice) could be tightened.

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 read-only diagnostic tool with no output schema, the description supplies everything needed: the returned field set, the meaning of error sources and severity levels, the sensitive-value confirmation flow, and where to get each identifier. Nothing an agent must know to invoke and interpret this 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?

With 75% schema coverage, the description still compensates fully: it documents the provenance of item_id and ad_id, explains that project_id is optional and what to do on project_id_required, and details the acknowledge_sensitive retry protocol including when it should be set (after user approval). Every parameter gains meaning not present in the schema alone, especially the two-step sensitive gate.

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 states a specific verb and resource (get the full error report for ONE ad listing item) and scopes it tightly to a single item, which distinguishes it from the ad-level get_ad_report and the marketplace-side get_marketplace_item_report. It also names the exact response fields, so an agent knows precisely what it will receive.

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?

It gives a clear trigger: 'Use this to explain why one ad listing failed,' and explains how to obtain each identifier (item_id from list_ad_items, ad_id from list_ads, list_projects when project_id_required appears). It stops short of explicitly naming when NOT to use it, e.g. pointing to get_ad_report for whole-ad or aggregate failures, leaving that contrast implicit.

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