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

Goes well past readOnlyHint/destructiveHint by disclosing cost ('free, no units'), that nothing is transmitted ('nothing sent'), that nothing is auto-fixed ('nothing is computed for you'), the return shape (ok plus problems carrying field, BR-… rule and message), and the stricter validation that awaits at render. These are exactly the traits an agent needs to plan a retry loop.

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?

Front-loads what it validates, then the cost/offline guarantees, then the problem-then-render workflow, then the caveat about the render validator. Dense but every clause carries information an agent would otherwise have to infer.

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 two-parameter validator with an output schema, the description covers purpose, cost, iteration loop, and the boundary against render-time validation. Nothing an agent needs in order to call it correctly and interpret the result 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 coverage is 100%, so the param details (block contents, profile enum, en16931 default, basic restrictions) are already carried by the schema. The description adds the tie that matters: the same block is what gets passed to render as data._invoice, which clarifies identity and reuse rather than restating the 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?

States a specific verb and resource (checks the _invoice block) plus the scope: offline, mirroring the API's pre-render validation, covering EN 16931 fields, totals, VAT categories, code lists and French domestic rules. It is clearly separable from the render sibling, which it names and contrasts with the stricter full rule set plus PDF/A-3b.

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?

Explicitly positions the tool before render in a workflow: validate, change the values a problem names, check again, then call render with einvoice. It also names the condition that distinguishes its checks from the render-time validator, so the agent knows when this suffices and when it does not.

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