Create a Factur-X / ZUGFeRD PDF

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds concrete behavior the agent could not otherwise know: writes are confined to the server working directory, an existing file is never replaced unless overwrite is true, output is byte-deterministic, nothing leaves the process, and the default base64 payload can be large enough to warrant outputPath. These are exactly the operational facts a caller needs before invoking a file-writing tool.

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?

Every sentence is front-loaded with purpose and carries a distinct fact: what it builds, when to use it, when not to, input contract, language behavior, output channel, overwrite safety, determinism, and verification. No sentence repeats the schema or the annotations, and nothing is 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?

For a six-parameter tool with a deeply nested invoice schema and an output schema already present, the description covers the decision-relevant surface: artifact choice, input reuse, output channel trade-off, filesystem safety, determinism, and next-step validation. Return-value shape is correctly left to the output schema.

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 baseline would be 3, but the description adds real meaning: it explains that `language` affects only printed labels while the embedded XML is identical, that `outputPath` switches the return channel from base64 to a file, that writes are sandboxed to the working directory, and that the `invoice` object is shared with create_invoice and uses integer minor units. Only per-parameter details like profile/template semantics are left to 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?

The first sentence names the exact artifact (a Factur-X / ZUGFeRD PDF/A-3b page with EN 16931 XML embedded), which is far more specific than the name alone, and the second sentence distinguishes it from the sibling create_invoice (XML only). An agent can tell instantly which of the two produces a human-readable document.

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 states the positive trigger ("when the invoice goes to a person or by e-mail") and the negative one ("For XML only, such as an XRechnung uploaded to a German public-sector portal, use create_invoice"), naming the alternative explicitly. It also routes post-generation verification to validate_invoice with the pdfBase64 argument.

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