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 past the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): it discloses that rule violations return structured issues instead of a file, the free-tier watermark and 5-per-day cap versus the subscription tier, caller responsibility for computing lineNetAmount/vatBreakdown/totals, and the extra obligations for xrechnung. No contradiction with 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-loaded with purpose, then PDF embedding, error handling, billing tier, calculation formula and xrechnung profile — a sensible order. It is a single dense block with no formatting, which makes it harder to scan, but almost every sentence carries information an agent needs.

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 8-parameter, deeply nested tool, the description covers generation paths, validation-failure behavior, licensing limits and the public-sector profile variant. With an output schema present it need not describe return values, and 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 coverage is 100%, so the baseline is 3, but the description adds genuine semantics the schema does not: the rounding formula for percentage allowances (round2(quantity × unitPriceNet × percent / 100)) and the explicit warning that the caller must compute lineNetAmount, vatBreakdown and the totals themselves. It also reinforces the 500 KB / PNG-JPEG-SVG logo constraint.

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?

"Erzeugt eine ZUGFeRD-PDF aus strukturierten EN-16931-Daten (kein LLM)" gives a specific verb, resource, input format and a hard constraint in one clause. It is immediately distinguishable from verify_zugferd (checks) and extract_invoice (reads data out of invoices).

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 three mutually exclusive paths (pdf_base64 vs upload_id vs no PDF, documented as "Höchstens eines von beiden") and when each applies. It also names the recovery branch explicitly: on business-rule violations, correct the invoice (referencing extract_invoice) and re-call with the same source data.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds genuinely useful behavior: uncertain fields appear as 'KORRIGIEREN' / '1900-01-01' placeholders flagged with code EXTRACTION_UNCERTAIN and must be fixed before create_zugferd, source='xml' vs. model reading of the rendered page, and the subscription/credit requirement. It does not mention rate limits or result payload size, but the disclosure is well beyond 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?

Purpose and pipeline role are front-loaded in the first sentence, and the remaining sentences each carry distinct constraints (placeholders, XML branch, account requirement). It is dense and somewhat run-on as a single block, but nothing is redundant padding.

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, return values need no explanation, and the description still covers what an agent needs: prerequisites (upload_id or pdf_base64), the correction workflow, sentinel values to fix, the deterministic XML path, and the billing prerequisite. Nothing material 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 schema already documents both upload_id and pdf_base64, including the mutual-exclusivity rule and base64 size limit. The description reiterates the upload_id reuse for embedding the same source PDF in create_zugferd, which is workflow context rather than new parameter semantics. Baseline 3 is appropriate.

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 — extracting EN-16931 invoice data (fields plus validation issues) from an uploaded PDF — and names its role in the pipeline relative to create_zugferd. An agent can distinguish it from verify_zugferd, parse_bank_statement, and other siblings 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 explicit ordering: run as a correction step before create_zugferd, show fields/issues to the user, correct them, then call create_zugferd with the corrected invoice and the same upload_id. It also covers the branch where the PDF already contains an embedded E-Rechnung, so the agent knows the XML path applies. No inference required.

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 readOnly/idempotent/non-destructive, but the description adds substantially more than the structured fields: rate limits and cost model, the mandatory account (API key or OAuth) requirement, and the 10 MB input ceiling. These are exactly the operational facts an agent needs before invoking and are not derivable from 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-loaded with the purpose and supported formats, then the per-format field breakdown, then the cost/auth rules. It is dense and the long field enumeration is somewhat list-like, but every sentence carries actionable information and nothing is padding.

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?

Covers formats, accepted input forms, size limit, quota/pricing, and authentication, which is complete for a read-only parsing tool. An output schema exists, so the extra field enumeration is redundant but harmless; nothing an agent needs to call 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 baseline is 3. The description adds only marginal parameter meaning — that a ZIP containing multiple XML files may be supplied (relevant to file_base64) and the 10 MB limit — which the schema already documents, so no credit above the baseline is earned.

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 (liest/parses) plus the exact resource family (camt.052/.053/.054/.086 fee statements) and the output (strukturiertes JSON). It implicitly distinguishes itself from the sibling validate_bank_statement by describing extraction into structured data including ZIP batches, so an agent can tell what this tool does versus validation.

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?

Clear operational context: which message versions are supported, batch-via-ZIP support, the free quota (5 calls/month/account), the payments subscription removing the limit, and the credit cost per extra call. However it never names the closest alternative (validate_bank_statement) nor states when to prefer one over the other, so the routing guidance is implied rather than explicit.

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, idempotentHint and destructiveHint=false, so safety is covered. The description goes further by disclosing rate limits/credit consumption and the auth requirement (an account is always needed), plus what each run returns (per-file message, version, rule findings, schema check with line/column, overall verdict), which is context the annotations do not carry.

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 purpose and supported formats are front-loaded, and the semicolon-separated clauses each carry distinct information (formats, output, pricing, auth). It is dense and somewhat long, but little of it 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?

With an output schema present and full parameter coverage, the definition needs only to cover scope, cost and prerequisites, all of which it does. The only gap is the lack of explicit routing against the sibling validate/parse tools.

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 xml, filename and file_base64 are fully documented in the schema. The description only adds that multiple files may be supplied as a ZIP, which matches the base64 field's own text; baseline 3 applies when the schema does the heavy lifting.

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?

Names a specific verb ("Prüft") plus the exact resources validated (Kontoauszüge, Kontoberichte, Avise, Gebührenabrechnungen) and even pins the message types/versions (camt.052/.053/.054/.02/.08, camt.086). This clearly separates it from sibling parse_bank_statement, which reads rather than validates.

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 cost/limit context (free up to 5 calls/day, subscription removes the limit, 1 credit buys 10 checks) and that an account/API key is always required, which is useful operational guidance. However it never states when to choose this over parse_bank_statement or validate_payment_file, so the when/when-not routing is only implied.

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses rate limits (5 free calls/day), the subscription model (feature payments unlimited), the credit-based fallback (1 credit = 10 further validations), and the mandatory account requirement. This is rich behavioral context an agent cannot get from annotations alone.

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 and the output summary is efficient, but the pricing/subscription explanation spans three sentences and is comparatively verbose for a definition where the schema and annotations already carry much of the load.

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, annotations covering the safety profile, and 100% parameter coverage, the description fills the remaining gap (cost/limit/auth) and leaves nothing an agent needs to call it correctly.

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 both input alternatives (xml vs file_base64), the profile enum, and filename are fully documented in the schema. The description adds no parameter detail beyond what the schema already provides; baseline 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 specific verb (prüft/validates) and resource (Zahlungsdatei pain.001) with scope qualifiers (SEPA-Überweisung, Auslandszahlung AXZ, versions .09/.03). An agent can distinguish it from validate_bank_statement without opening either 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?

The description implies usage through the pain.001 scope and the credit note covering 'payment files and bank statements together', but it never names an alternative tool or states when NOT to use this one. Usage guidance is only implicit.

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.