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

Annotations only declare the safety profile (non-read-only, idempotent, non-destructive); the description adds substantial behavior: per-document totals validation, automatic job-reference assignment, retention of the original, cross-supplier price-change comparison, duplicate skipping, and non-atomic 'held back' outcomes. That held-back/needs_check behavior is especially valuable because it tells the agent a call can partially succeed.

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?

Three sentences, front-loaded with purpose and input forms, then pipeline behavior, then return values. The long middle sentence is dense but every clause conveys a distinct behavior (validation, job reference, original retention, price comparison); nothing is padding.

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 does explain the return shape (one result per document with four possible statuses), and annotations cover safety, so the agent has what it needs to call and interpret results. The only gap is the absence of a stated remediation path when a document comes back needs_check, which a sibling tool likely handles.

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?

Reported schema description coverage is 0%, so the description must carry parameter meaning; it does map input forms to the payload (email, PDF, photo, pasted text) and states the 25-item cap, which is the key constraint. It adds nothing about the optional job_reference or supplier_name overrides or how multiple pasted emails are separated, so the compensation is only partial.

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?

States a specific verb and resource ('add supplier invoices to the book') and immediately enumerates the accepted input forms — raw emails with PDF attachments, text/scanned PDFs, photos, pasted text — with a batch cap of 25. This is clearly distinguishable from siblings like list_invoices or review_invoice without opening any schema.

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?

Guidance is clear on what input forms are accepted and how many per call, and the outcome statuses (added, needs_check, duplicate, failed) implicitly point to review_invoice as a follow-up. However, it never explicitly states when to prefer this over review_invoice or assign_job_reference, nor any preconditions.

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