compliance_xml

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

With no annotations, the description carries the full burden and does real work: it discloses the tool is side-effect free ('without storing anything'), performs no ruleset validation, and produces lossy output for invalid documents — the single most surprising behavior. What it omits is the shape of the response (raw XML string, encoding, size limits, or whether a download handle is returned).

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-loaded with the outcome, then rationale, then the parameter design note. Every paragraph has a purpose. The syntax rationale runs slightly long for a point that could be one sentence, but it pre-empts a likely caller error, so the length is defensible.

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?

No annotations and no output schema means the description is the only source for behavioral contract, and it does not say what actually comes back from a tool whose entire job is producing an artefact. For a 3-parameter, mutation-free generator the coverage is adequate on intent but incomplete on output.

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 low (33%), so the description must compensate, and it does so for the most confusing parameter: `profile` is explained as a syntax-plus-ruleset bundle, which is why no separate syntax argument exists ('asking a caller for both is asking them to know that Peppol means UBL'). It says nothing about `document_type` or `data`, though the deeply described nested $defs largely cover the body. Net: meaningful but partial compensation.

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 line states a concrete verb+resource: produce the e-invoicing XML for a document, explicitly without persistence. That distinguishes it from `document_create`/`document_render` and pairs it conceptually with the validation path. It stops short of 5 because the counterpart is named by HTTP path (`/validate-compliance`) rather than by sibling tool name (`compliance_check`), so an agent must infer the mapping.

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 gives an explicit workflow: validate first, then take the XML once it passes, and states that refusals belong to the validation endpoint. It also carves out when NOT to expect value here — this will happily emit XML missing mandatory elements rather than erroring. Alternatives and sequencing are both spelled out.

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