finisma – ZUGFeRD e-invoices

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it names the underlying SML/SMP lookup mechanism, clarifies that registered:false is a normal result rather than an error (a real gotcha for retry logic), and notes the call is free.

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 tightly-packed sentences with the purpose front-loaded, followed by accepted input forms and the key behavioral caveat. Every sentence earns its place with zero redundancy.

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 no explanation; the description still adds the important normal-result semantics around registered:false. For a single-parameter, read-only lookup, nothing an agent needs to invoke it correctly 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 description coverage is 100%, so the participant parameter's accepted formats are already documented and the description largely mirrors them (full Peppol identifier, bare GLN, German VAT ID, Leitweg-ID). No additional semantics such as normalization or fallback behavior are added beyond 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: SML/SMP lookup to check whether a partner is reachable in the Peppol network, plus a secondary output (registered document types). This is clearly distinct from sibling check_vat_id, which validates a VAT number rather than network reachability.

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 — you'd call this to verify a partner before sending a Peppol document — but the description never states when to use this versus the closely related check_vat_id sibling, nor any prerequisites or exclusions. The implied context is clear, but no explicit routing guidance is provided.

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

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

Die Beschreibung geht über die Annotationen hinaus: Sie erklärt das Antwortformat (valid, invalid, unavailable), die Live-Abfrage bei VIES und dass VIES nicht erreichbar sein kann. Das ist wertvolle Information, die nicht in den Annotationen steht. Allerdings fehlen Details zu Rate-Limits oder Fehlerbehandlung.

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?

Die Beschreibung ist kompakt und front-loaded: Kernaussage zuerst, dann Details zum Status und der Kosten. Es gibt keine überflüssigen Sätze.

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?

Für ein Tool mit einem Parameter, vollständiger Schema-Beschreibung und Output-Schema ist die Beschreibung ausreichend. Sie erklärt den Rückgabestatus und den externen Dienst. Es fehlt der Hinweis, dass die Prüfung live erfolgt und daher Latenz auftreten kann, aber das ist angesichts der Annotationen (idempotent, readOnly) und des Output-Schemas vertretbar.

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?

Der Parameter vat_id ist im Schema vollständig beschrieben (100% Abdeckung), sodass die Beschreibung keine zusätzlichen semantischen Informationen liefert. Sie wiederholt lediglich, dass eine USt-IdNr. geprüft wird.

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?

Der Beschreibung nennt klar das Verb und die Ressource ('Prüft eine USt-IdNr. live gegen VIES') und grenzt damit die Funktion von den Geschwistertools ab. Allerdings wird nicht explizit erwähnt, dass es sich um eine externe, kostenlose Prüfung handelt, was die Abgrenzung verbessern würde.

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?

Es wird impliziert, wann das Tool zu nutzen ist (Prüfung einer USt-IdNr.), aber es fehlen explizite Hinweise, wann es nicht zu verwenden ist oder welche Alternativen es gibt. Geschwistertools wie check_peppol_participant werden nicht erwähnt.

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

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

Goes well beyond annotations: discloses that structured issues are returned instead of a file on rule violations, describes watermark and daily limit without subscription, specifies percentage calculation rules for allowances/charges, and details XRechnung output constraints (pure XML via REST API, required fields). This is rich behavioral context for a write operation.

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?

Dense but front-loaded with purpose, then structured into error handling, subscription limits, calculation rules, and XRechnung specifics. Every sentence carries useful information, though the length is substantial; for a complex tool this is justified and no major redundancy appears.

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?

Given the presence of an output schema, the description need not explain return values, but it still covers error returns (structured issues), rate limits, watermark behavior, calculation rules, and XRechnung requirements. An agent has enough information to invoke the tool correctly and interpret failure modes.

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?

With 100% schema description coverage the baseline is 3, but the description adds critical semantics: it explains how allowanceCharges amounts may be omitted when percent is set, gives the formula amount = round2(Menge × unitPriceNet × percent / 100), and clarifies that lineNetAmount, vatBreakdown and totals must be computed by the caller. It also names required XRechnung fields.

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?

Starts with a specific verb and resource: 'Erzeugt eine ZUGFeRD-PDF aus visueller PDF und strukturierten EN-16931-Daten (kein LLM).' This clearly distinguishes it from siblings like extract_invoice (extraction) and verify_zugferd (verification).

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?

Explains the retry workflow when EN-16931 business rules are violated, mentions extract_invoice as the correction counterpart, and gives conditional guidance (subscription status, profile='xrechnung' for public sector). It lacks explicit when-not-to-use or full alternative routing, but provides strong context.

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

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

Annotations only supply the generic profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), while the description adds real operational context: uncertain fields are emitted as 'KORRIGIEREN'/'1900-01-01' placeholders flagged with issue code EXTRACTION_UNCERTAIN, the XML path sets source='xml', and the call requires an active subscription or credit. That is meaningful disclosure beyond the structured fields, and it does not contradict the annotations.

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 the action and the correction workflow, and nearly every clause carries new information (placeholders, issue code, XML fallback, billing requirement). It is a dense multi-clause construction rather than a tight set of sentences, which costs a point but not readability of the core intent.

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 no prose, and the description still covers the workflow, the sentinel-value/error semantics, the source-of-truth branch, and the account prerequisite. For a two-parameter extraction tool with annotations and an output schema, nothing an agent needs 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 description coverage is 100%, so upload_id vs pdf_base64, the base64/25 MB constraint, and the mutual exclusivity are already fully documented in the schema. The description reinforces the upload_id reuse across create_zugferd but adds little syntax or format meaning beyond it, so the baseline of 3 applies.

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 precise verb and resource: extraction of EN-16931 invoice data plus validation issues from an uploaded PDF. It also distinguishes itself from sibling create_zugferd by positioning itself as the correction step that precedes it, so an agent can place it in the pipeline without opening another schema.

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?

Gives an explicit ordered workflow: extract, show fields and issues to the user, let them correct, then call create_zugferd with the corrected invoice and the same upload_id. It also defines a condition branch (embedded ZUGFeRD/Factur-X XML vs. LLM reading of the print image), leaving little to inference.

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

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

Annotations only declare the safety profile (readOnly=false, idempotent=false, destructive=false); the description adds the lifespan ('kurzlebige'), the two operating modes, the exact multipart field name and curl form, and a real environmental prerequisite (finisma.de must be reachable, and added to the sandbox allowlist). That is substantive operational context beyond the structured fields.

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?

Purpose is front-loaded in the first sentence, followed by rationale, then the two paths and the prerequisite. Every sentence carries information, but the path/sandbox explanation runs long and could be tightened without loss.

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 re-explained, and the description still adds the prerequisites and workflow an agent needs. Nothing required to invoke this zero-parameter tool correctly 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description names the returned identifiers (upload_url, upload_api_url, upload_id), which helps but is not required since the schema has no inputs.

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 ('Erzeugt einen kurzlebigen Upload-Link für eine PDF-Rechnung') rather than restating the tool name. It also explicitly positions itself against siblings by framing the link as an alternative input to create_zugferd/verify_zugferd, so an agent can distinguish it without opening any schema.

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?

Gives an explicit when-to-use trigger ('Nötig für Chat-Clients ... die eine angehängte Datei nicht zuverlässig als pdf_base64 übergeben können') and then enumerates two concrete usage paths with the conditions that select each (browser upload vs. client-side multipart POST). The alternative route (reusing pdf_base64 with create_zugferd) is also named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful information beyond that by disclosing the depth of validation performed (structure, EN 16931 rule conformance, PDF/A-3 attachment checks), which tells the agent what a positive or negative result means.

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?

A single front-loaded sentence with zero filler: verb, resource, and scope in order of importance. It is arguably thinner than a multi-step validation tool warrants, but nothing is redundant or padded.

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?

With an output schema present the description need not explain return values, and annotations plus full schema coverage handle safety and inputs, so the remaining burden is small. The one real gap is task routing – nothing tells the agent when to prefer this over extract_invoice – which keeps it short of a 5.

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 100% – both upload_id and pdf_base64 are documented in the schema, including the 'exactly one of the two' constraint and the 25 MB limit. The description adds no parameter detail of its own, so the baseline of 3 for schema-driven parameters applies.

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 ('Prüft') and a precise resource ('ZUGFeRD-/Factur-X-PDF') and enumerates the validation scope (Struktur, EN-16931-Regeln, PDF/A-3-Anhänge), so an agent immediately knows this is a validator, not a generator or extractor. It does not, however, distinguish itself from siblings like extract_invoice or create_zugferd by naming them or contrasting scope.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The only routing hint in the whole definition lives in the schema for pdf_base64 (call request_upload_link first for chat clients), not in the description itself, so an agent gets no help choosing between this and extract_invoice or create_zugferd.

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