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

Annotations only declare readOnlyHint=true, and the description adds substantial behavioral context beyond that: the events are not yet synced to the ledger, the pipeline is paused for them, and they are excluded from P&L reports until approved. It also reveals what fields each item carries so the agent knows this is a zero-further-query consumption pattern. No contradiction with annotations.

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 every sentence earns its place: definition, business impact, payload contents, resolution path, and pagination. It is front-loaded with the core purpose and maintains high signal-to-noise throughout with no 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?

Combined with the 100%-covered input schema, an output schema, and the read-only annotation, the description leaves nothing essential missing. An agent knows what the tool returns, why it matters, how to paginate, and what sibling tool to call next.

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 100%, so the schema already documents all three parameters. The description adds real value by explaining how cursor relates to next_cursor for pagination, how limit and total_count interact, and how org_id defaults to the authenticated API key's organisation, which goes beyond the schema's basic 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 states a specific verb and resource: it lists classified events that the rules engine could not confidently categorise, with needs_review = true and not yet synced to the ledger, ordered newest first. It clearly distinguishes this from generic list tools by tying it to the review/approval workflow and naming the exact condition that defines the set.

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 explains when this queue matters: the pipeline is paused for each event, and they are missing from P&L reports and the ledger. It also gives the explicit next action by directing agents to approve_classification with classified_event_id and the correct category, and explains pagination via next_cursor.

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