build_facturae

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

Beyond the annotations it discloses that totals are computed, the official XSD is checked, invalid data is refused before charging, and the XML is returned unsigned and UTF-8. The credit-charge implication sits somewhat uneasily with readOnlyHint=true, but it is disclosure rather than contradiction, and the description adds real behavioral context.

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 first sentence front-loads purpose and outputs, and the long field listing is justified by the bare schema. The block is dense and compressed into a single unformatted slab, which costs some scannability, but no sentence is wasted.

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 complex nested builder the coverage is strong: field inventory, amount formatting ('1.234,56' or '1234.56'), tax/recargo enumerations, public-administration DIR3 codes, and the signing prerequisite. With an output schema present, return values are covered and the description still names xml, xml_base64, totals, and the validation report.

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 0% and the single parameter is an open object, so the description carries the full burden and does so with a detailed field map: required/optional fields, defaults (EUR, ESP), person-vs-company name shapes, DIR3/FACe face structure, line-level tax types and recargo rates, withholding, and payment blocks.

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 opens with a specific verb+resource+standard: build a Facturae 3.2.2 invoice as XML, with totals computed and XSD validation. It also implicitly separates itself from the sibling validate_facturae (build vs. validate) and from the verifactu_* tools by naming the FACe/Facturae domain.

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 context is clear: it is for turning plain data into a signed-ready XML for FACe, and the closing sentence sets a downstream prerequisite ('Sign the XML (XAdES) before sending to FACe'). What is missing is explicit routing, e.g. when to prefer validate_facturae or whether this can replace a build+validate sequence.

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