invowerk

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds genuinely useful behavior beyond that: conversion is self-validated, invalid documents are never returned, unreadable input raises an error, the 4 MB decoded limit, and a cost of 3 credits per call. It stops short of describing pagination or timing, but for a stateless converter the disclosure is strong.

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 the validation guarantee, then input, output and cost are separated into labeled blocks that are easy to scan. It is slightly longer than strictly necessary given the schema repeats much of the input detail, 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 four-parameter conversion tool with an output schema, everything an agent needs is present: both input modes, the target syntax, flavor defaulting behavior, the return fields, the validation guarantee, failure behavior and cost. Nothing material is left for the agent to guess.

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 invoice_base64, file, target_syntax and target_flavor, including the 4 MB limit and flavor fallback. The description largely restates those facts and adds no syntax examples or validation rules beyond what the schema carries, making this the baseline case.

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 (convert) and resource (e-invoice) plus the concrete target formats UBL and CII, so the operation is unambiguous. It does not name or contrast with siblings such as parse_invoice, validate_invoice, or generate_invoice, so an agent must infer the boundary itself.

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 through the input alternatives (base64 vs. download link) and the optional target_flavor semantics, which helps an agent call it correctly. However, there is no explicit when-to-use/when-not guidance and no routing advice against the sibling tool set, leaving the choice between conversion and parsing/validation unstated.

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 the readOnly/openWorld annotations: it discloses the no-API-key requirement, deduplication behavior, the failure mode when an unknown code is supplied ('the call fails and names the unknown codes'), and the metering/cost profile. These are exactly the operational traits an agent needs.

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 core purpose and well-sectioned into input/return/credits. Slightly less than ideal because it enumerates the return fields ('title', 'meaning', 'causes'...) that the output schema already documents, which 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?

For a read-only lookup with an output schema present, the description covers everything needed: input format, language, dedup, failure behavior, and cost. Nothing required 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 already 100%, so the baseline is 3, but the description adds real meaning: codes is 'one or more' with a concrete example, duplicates are removed, and lang defaults to 'de' with the two allowed values. The example format adds value beyond the schema's generic string-array description.

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 ('Explain rule codes in plain language') and scopes it to codes emitted by validate_invoice, which distinguishes it from the other invoice siblings. An agent can immediately tell this is a lookup/explanation tool rather than a processing tool.

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?

Clearly establishes the context of use by tying the input codes to validate_invoice findings, and notes it works without an API key. It does not, however, explicitly state when NOT to use it or name any alternative, so it stops short of full when/when-not guidance.

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: discloses the 4 MB input cap, default behavior for `syntax` and `flavor`, the extra requirements for xrechnung (`buyer_reference`/Leitweg-ID BT-10 and `payment_iban`), the critical semantic that amounts are written as given and never computed or corrected, the precondition that the XML is self-checked and invalid documents are never returned, the failure modes (engine_busy, engine_timeout, invalid input), and the cost (5 credits per call). This is exactly the behavioral context an agent needs before invoking.

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 one-line purpose, then input, then output, then errors, then cost — a sensible order for an agent. It is on the long side and the field list duplicates what the schema already carries, but nearly every sentence (validation guarantee, amounts-as-given, xrechnung prerequisites) carries non-redundant information.

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 single-parameter tool with a nested object and an output schema, the description covers everything an agent needs: the input contract, the size limit, flavor-dependent requirements, the correctness caveat, the validation guarantee, and the error/credit model. Return values (`xml`, `syntax`, `flavor`, `self_validation`) are named, and the output schema handles their details.

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% and the nested `invoice` object is already documented, so the baseline is 3, but the description adds real meaning: default values, the enumeration for `flavor`, the conditional dependency between `xrechnung` and two other fields, and the size limit. It also enumerates the main sub-fields (`seller`, `buyer`, `lines`, `tax_breakdown`, `totals`), which largely restates the schema but anchors the shape of the nested object.

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 ("Create a valid EN 16931 e-invoice (UBL or CII XML) from JSON") and pins down the exact output artifact format. The five siblings (convert_invoice, parse_invoice, validate_invoice, render_invoice, explain_errors) are distinguishable from this one because the description fixes both input (JSON keyed on EN 16931 BT) and output (XML).

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 by the input contract (JSON keyed on EN 16931 Business Terms, same schema as POST /v1/generate, cross-referenced to parse_invoice's `model`), so an agent can infer that this is the JSON-to-XML direction. However there is no explicit when-to-use/when-not guidance and no direct routing to convert_invoice (XML in) or validate_invoice (check only), which are the natural alternatives. A reader must infer the boundaries.

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 cover read-only/open-world; the description adds real behavioral context beyond them: input size limits (4 MB decoded, 500 pages, 16 attachments), accepted syntaxes (UBL, CII, ZUGFeRD/Factur-X PDF), the specific failure modes (missing embedded XML, UBL credit note, malformed XML, engine_busy, engine_timeout) and a cost signal (2 credits per call).

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 input, output and error/cost details in compact sections. Dense but nearly every clause carries new information; only the return-field enumeration overlaps slightly with the existing output schema.

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 a two-parameter nested schema, an output schema and read-only annotations, the description covers the remaining gaps an agent needs: input constraints, accepted formats, failure codes and credit cost. 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining what invoice_base64 must actually contain (base64 of a UBL/CII XML or ZUGFeRD/Factur-X PDF) and by framing `file` as the alternative download-link path.

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 (Read) and resource (e-invoice) and names the exact output semantics ('JSON keyed on EN 16931 Business Terms'), which cleanly separates it from siblings like generate_invoice, render_invoice and validate_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 ties the tool to the workflow by noting the JSON output is the input format of generate_invoice, so an agent knows this is the read-back step before editing/regenerating. It stops short of stating when *not* to use it or contrasting it with convert_invoice.

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 readOnlyHint/openWorldHint annotations, the description discloses failure modes (non-invoice XML, malformed XML, DOCTYPE, engine_busy, engine_timeout), input size limit, and credit cost. This is unusually rich behavioral context for a read-only render 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?

Front-loaded with the core purpose, then inputs, outputs, errors and cost in short labeled blocks. Slightly long, and the return-fields sentence partly duplicates the output schema, but every sentence carries information.

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 an output schema exists, the definition need not describe return values, yet it does anyway and additionally covers error conditions, language options and credit usage. An agent has everything needed to call this correctly in one pass.

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 real meaning: the 4 MB decoded cap, the mutual-alternative relationship between invoice_base64 and file, and the rejection of PDFs. The lang default is restated from the schema rather than extended.

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 ('Render an XML e-invoice ... as a readable HTML page') and specifies accepted syntaxes (UBL, CII, XRechnung). It implicitly separates itself from parse_invoice/validate_invoice by framing the goal as showing a person the content, but no sibling is named explicitly.

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 clear context for use ('Use it to show a person what an e-invoice contains') and an explicit exclusion ('PDFs are not accepted'). It stops short of naming alternatives such as convert_invoice or parse_invoice for non-visual needs.

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?

With annotations covering only readOnlyHint/openWorldHint, the description carries real weight: it discloses the KoSIT-vs-local fallback, `verdict_source`, `official_degraded`, `disagreement`, the specific error codes (engine_busy, engine_timeout, document_too_complex), the 4 MB/100k-element limits, credit cost, and that unreadable input yields a finding rather than an error.

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 purpose in the first sentence, then groups input details, result semantics, and failure modes. Dense and largely waste-free, though the run of result-field explanations (:verdict_source, disagreement, pdfa_verdict, hints) is close to restating the output schema.

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 validation tool with degraded-mode behavior and rich output, the description covers inputs, the authoritative-vs-local resolution logic, error conditions, and cost. An agent has everything needed to call it and interpret the outcome.

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 format semantics the schema omits: that invoice_base64 may be UBL or CII XML or a ZUGFeRD/Factur-X PDF, and the 4 MB limit. It also clarifies the effect of explain/lang beyond the schema's one-liners.

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 ('Check an e-invoice') and pins the scope precisely: EN 16931 plus German rules, accepting UBL/CII XML or ZUGFeRD/Factur-X PDF. The follow-up routing to explain_errors makes it distinguishable from the sibling parse/convert/render tools.

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 explains the two mutually exclusive input paths (invoice_base64 vs. `file` download link) and points the agent at explain_errors for codes. What's missing is an explicit statement of when this tool is preferable to siblings such as parse_invoice or convert_invoice.

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