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

Beyond the readOnly/idempotent annotations, the description discloses behavior an agent could not get from structured fields: extraction runs in memory, sensitive identifiers are removed from the response, the document is not retained by Boncourant, uncertain fields require confirmation, and crucially that during the test phase extraction is performed by DeepSeek in China with no transfer guarantees. This is exactly the kind of non-obvious, decision-relevant context the description should carry.

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 what the tool does, then the privacy constraint and the retention/confirmation caveats. Every sentence carries information and none is padding, though the run-on first sentence packs three distinct behaviors together.

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?

An output schema exists, so return values need not be described, and the annotations already cover the safety profile. Given that, the description supplies everything an agent needs to invoke it responsibly: what it ingests, what it does with the data, the third-party transfer risk, and the non-retention guarantee.

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 33%, so the description needs to compensate, but it only vaguely alludes to 'un PDF ou un texte' without distinguishing document_file / document_base64 / document_text, and never mentions document_kind, segment, or evaluation_date at all. The oneOf input-alternative structure and the enum values that shape the analysis remain undocumented in prose.

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 names a specific verb (extrait) and resource (PDF/texte de facture ou contrat) and adds that it strips sensitive identifiers and immediately runs the applicable deterministic methods, so an agent understands it is an extract-plus-analyze entry point. It does not, however, name or contrast itself with obvious siblings like analyze_bill or decompose_invoice, so sibling differentiation is left implicit.

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?

Usage is implied rather than stated: the agent can infer this is the ingestion step for invoices/contracts, and there is a real when-not-to constraint ('n'envoyez pas de document contenant des données personnelles réelles'). But nothing tells the agent when to pick this over analyze_bill, decompose_invoice, or annualize_invoice, nor any prerequisites.

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