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

Goes well past the readOnly/idempotent/non-destructive annotations: it warns that conversion invents nothing, that a target profile like XRechnung may lack required source data and surfaces `warnings`, and that unreadable documents return an error result with a reason. It also discloses local execution ("nothing is sent anywhere"), corroborating openWorldHint=false.

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 what the tool does, then alternatives, then input forms, then behavioral caveats and failure mode — a logical escalation with no filler. Each sentence supplies information the agent would otherwise have to infer.

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?

Even though an output schema exists and return values needn't be spelled out, the description covers the parts that matter for a conversion tool: input acceptance, lossy-conversion risk, warning inspection, and error behavior. Nothing an agent needs in order to call this 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 enum and per-parameter descriptions already carry the load, and the description correctly does not repeat them. It still adds useful framing that only one of xml or pdfBase64 is supplied and that Factur-X/ZUGFeRD PDFs are accepted as input, plus concrete example target syntaxes.

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 ("Rewrites an existing e-invoice in another syntax") and grounds it with concrete conversions (CII to UBL, EN 16931 to XRechnung or Peppol BIS). An agent can immediately tell this apart from create_invoice or parse_invoice 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?

Explicitly scopes usage to when the caller "already hold[s] an invoice document" and routes the other cases: build from data → create_invoice, XML to PDF → parse_invoice then create_invoice_pdf. It also names the follow-up step (validate_invoice on the result) and the accepted input forms.

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/local, and the description adds substantive behavior beyond them: the tool runs locally and sends nothing, a failure is atomic ("produces nothing") and returns an error enumerating every problem by path, BT id and message. It also discloses a real limitation not in any annotation — the official rule sets are not run, so validate_invoice must be called separately.

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?

Six tight sentences, front-loaded with purpose then routing then input conventions then failure behavior. No filler, though the minor-units and computed-totals guidance partially repeats per-field schema descriptions and could be trimmed to one clause.

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 two-parameter tool wrapping a very large nested schema with an output schema available, the description covers the essentials: format choice, input conventions, atomic failure, locality, and the validation handoff. It does not mention format-specific field requirements (XRechnung mandatory seller contact, Peppol/France electronic address), but those are documented in the schema itself.

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; the description earns an extra point by stating conventions that matter at call time but are easy to miss across a 100-field schema: `invoice` is an object not a JSON string, every money field is an integer in minor units, and totals/VAT breakdown must not be sent because they are computed.

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?

Opens with a specific verb and resource ("Builds e-invoice XML from structured invoice data") and enumerates the supported syntaxes (EN 16931 CII/UBL, XRechnung, Peppol BIS 3.0) selected by `format`. It explicitly differentiates itself from create_invoice_pdf and convert_invoice, so the agent can choose 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?

States the use case ("for a new invoice that software will read") and names three alternatives with the exact condition that selects each: create_invoice_pdf for PDF, convert_invoice for changing syntax, validate_invoice before sending. When-to-use, when-not-to-use, and alternatives are all present.

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 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.

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description still adds real behavioral context beyond them: unknown ids are not errors but yield `found` false with an empty `official` list, and the tool reads bundled rule sets with no network access. That said, it does not describe result sizing or how large the official wording list can get, so it is useful but not exhaustive.

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 dense paragraph, front-loaded with the verb/resource and the id formats, then usage, then the negative case, then data sourcing. Every clause earns its place; the 'does not check an invoice' sentence is a deliberate disambiguation rather than 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 one-parameter, read-only lookup with an output schema, the description covers purpose, routing, edge-case behavior and data provenance. Return values are backed by the output schema, and the description goes further by naming the `found`/`official` fields for the miss case so an agent knows what to report to the user.

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% and the single `ruleId` parameter is already documented with its own example, so the schema carries the parameter burden. The description reinforces the id format with several additional naming conventions (PEPPOL-EN16931-R003, BR-FR-05), which helps an agent recognize valid ids but adds no new constraints. 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 ('Explains one validation rule id') and immediately grounds it with concrete id examples (BR-CO-15, BR-DE-15, PEPPOL-EN16931-R003, BR-FR-05), making clear it is a lookup/explanation tool, not a validator. It explicitly distinguishes itself from validate_invoice, so an agent can route correctly without opening schemas.

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 triggering conditions ('after validate_invoice reports a rule you need to explain or fix, or when a user asks what a rule means') and an explicit exclusion ('It does not check an invoice; call validate_invoice for that'). The alternative sibling and the condition that selects it are named outright, leaving nothing 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 already cover readOnly, idempotent and the closed-world nature, but the description adds real context beyond them: a data-quality caveat that 'unverified' entries are not confirmed from an official source and must be disclosed, plus the meaning of the `conformoSupport` field. Minor overlap exists in restating 'no network', which duplicates openWorldHint=false.

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 alternatives, then caveats; nearly every sentence carries distinct information. Slight redundancy in 'Reads a bundled dataset; no network' echoing the openWorldHint annotation, but overall tight.

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 needn't be explained, yet the description still clarifies the key embedded field (`conformoSupport`) and the trust caveat for unverified entries. 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 coverage is 100%, so the baseline is 3; however the description adds the supported country domain (BE, DE, ES, FR, IT, NL, PL) that the schema does not encode via enum. That materially constrains valid inputs beyond the ISO-code description in 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 gives a precise verb and resource ('Looks up the e-invoicing rules for one country in a sourced dataset') and enumerates the returned content (B2G/B2B mandates, start dates, thresholds, formats, sources). It is immediately distinguishable from siblings like validate_invoice and create_invoice.

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?

Explicitly states when to use it ('before create_invoice to decide which format a buyer needs') and draws a clear exclusion boundary ('It says nothing about a specific invoice; use validate_invoice to check one'). This is the when/when-not/alternative pattern done fully.

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 cover readOnly/idempotent/non-destructive, and the description adds behavior beyond them: output is the same object create_invoice accepts with money in integer minor units, unreadable documents return an error result with a reason, and it runs locally. The visibleTotals disclosure for PDFs (page totals vs embedded XML, exposing tampering) is precisely the kind of non-obvious behavioral detail an agent cannot get from 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 accepted formats are front-loaded in the first clause, then usage, sibling routing, PDF caveat, and error behavior follow in descending priority. Every sentence carries distinct information; the 'exposes a tampered or mismatched PDF' clause is a short payoff, not 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?

For a two-parameter read tool with a full output schema and complete annotations, the description supplies everything else an agent needs: accepted syntaxes, output contract, failure mode, and the three sibling-routing decisions. Nothing material is left to inference.

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% and both parameters already document the 'provide this OR pdfBase64' exclusivity, so the baseline is 3. The description reinforces that a PDF path exists and explains what the embedded XML yields, but it adds no format or precedence detail beyond what the schema states.

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 and resource (reads an e-invoice into a structured invoice object) and enumerates the exact accepted syntaxes (CII, UBL, XRechnung, Peppol XML, Factur-X/ZUGFeRD PDF). It goes further by tying the output to create_invoice's input shape with integer minor units, which lets an agent distinguish it from validate_invoice and convert_invoice 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?

It gives explicit use cases (answer questions about a received invoice, edit one, re-issue it with create_invoice) and explicit exclusions with named alternatives: no rule checking, so use validate_invoice; to change syntax directly, use convert_invoice. This is the full when/when-not/alternative triad.

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 read-only, idempotent, non-destructive and closed-world, and the description still adds substantial context: rule-set detection from the document, that `valid` only means the listed `ruleSets` passed and implies no tax-authority acceptance, that non-invoice input yields an error rather than an invalid verdict, and that the check is offline with no upload. This is exactly the kind of scope-limiting detail annotations cannot convey.

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 each sentence carries information — the valid/ruleSets caveat and the error-vs-invalid distinction are high-value. It is somewhat dense and the accepted-input sentence sits mid-paragraph rather than next to the purpose, but 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?

An output schema exists, so return values needn't be explained, yet the description still pre-empts the main misinterpretation risk (over-claiming acceptance) and notes that failures carry the publisher's message plus plain-language fixes. Nothing an agent needs in order to call it and report results 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 baseline is 3, but the description adds real meaning: it clarifies that syntax and profile are auto-detected unless overridden, and that for a Factur-X/ZUGFeRD PDF the embedded XML is what gets checked. The remaining parameters (xsd, country) are left entirely 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?

States a specific verb and resource — checking an e-invoice against named rule sets (XSD, EN 16931 Schematron, KoSIT XRechnung/Peppol BIS) — and explicitly distinguishes itself from parse_invoice and explain_validation_rule. An agent can identify the tool without opening the 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 when-to-use guidance (before sending an invoice you created, and when receiving one) and names both alternatives with the condition that selects them. No inference required.

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