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 beyond the sparse annotations: it discloses the 4 MB input cap, the amount ceiling, that amounts are written as given and never computed or corrected, that failures return rule-named errors (e.g. BR-CO-15), that output is always self-validated, and that engine_busy/engine_timeout errors and a 5-credit cost per call apply. That is exactly the operational context annotations cannot supply.

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 sentence, then input, then behavior, then return and cost. Dense but every block carries information; the main fields list is the only slightly enumerative 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?

Covers input shape, constraints, failure modes, return fields and cost — more than enough for a single-parameter tool with an output schema. The only missing piece is routing guidance versus the four sibling invoice 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 coverage is 100% and there is only one parameter, but the description still adds real meaning: defaults for syntax and flavor, the conditional XRechnung requirements (buyer_reference/Leitweg-ID BT-10 and payment_iban), date format and the field inventory. It supplies conditional logic the schema's free-form object cannot express.

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 concrete verb (create), resource (e-invoice) and concrete output format (UBL or CII XML from JSON), so the agent knows exactly what the tool produces. It does not, however, state how it differs from siblings like convert_invoice, parse_invoice or validate_invoice, which all operate on 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?

Usage is only implied: you use this when you have a JSON model and need XML. There is no explicit guidance on when to prefer validate_invoice (check without generating) or convert_invoice (change syntax of existing XML), and no statement of prerequisites beyond the XRechnung field requirements.

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.