invowerk

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

With annotations only declaring readOnlyHint and openWorldHint, the description carries real behavioral weight: it discloses the 4 MB decoded size limit, that the output is self-validated and invalid documents are never returned, and the error behavior for unreadable/unconvertible input. It also states the 3-credit cost, which annotations never surface.

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, then clean Input/Returns/Credits sections that are easy to scan. Slight redundancy in stating twice that the result is checked/validated before returning, but overall every sentence earns its place.

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 3-parameter conversion tool with an output schema, the description covers inputs, defaults, limits, validation guarantees, failure behavior, and cost. 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 0%, so the description must compensate, and it does: invoice_base64 is explained as base64 XML or ZUGFeRD/Factur-X PDF with a size cap, target_syntax values are given as "ubl"/"cii", and target_flavor is explained as optional with its default (source flavor retained) plus its "en16931"/"xrechnung" values.

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 ('Convert an e-invoice to UBL or CII') and scopes it to a well-defined transformation. It is clearly distinguishable from siblings like parse_invoice, generate_invoice, and validate_invoice, which do different jobs on the same resource.

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 the conversion context and clarifies acceptable inputs, but offers no explicit when-to-use guidance or exclusions relative to siblings such as validate_invoice. An agent can infer the purpose, but routing decisions are left 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?

With readOnlyHint=true already covering the safety profile, the description adds real behavioral context beyond annotations: no API key required, free/not metered, duplicate codes are removed, and the call fails naming unknown codes. It does not detail rate limits or payload size limits, but the added disclosure is substantial.

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 contract, then return shape and failure behavior, then cost. Slightly long, and the return-field enumeration partly duplicates the output schema, but every sentence carries useful 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?

An output schema exists, yet the description still usefully names the failure mode (unknown codes abort the call) and the cost model. Combined with the schema and annotations, an agent has everything needed to invoke this 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 0%, so the description must carry both parameters, and it does: `codes` is a list of one or more codes with duplicates removed (with an example), and `lang` is 'de' (default) or 'en'. It compensates well for the empty schema, though enum values for lang are only implicitly given.

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+resource ('Explain rule codes in plain language') and enumerates the code families covered (EN 16931, XRechnung, ZUGFeRD, IW-*). It also ties itself to the sibling validate_invoice by naming whose findings it explains, so it is distinguishable from the other invoice 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?

The description clearly establishes the context of use: decoding codes surfaced by validate_invoice findings and hints. It gives no explicit when-not-to-use or alternative-tool routing, but the usage context is unambiguous.

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?

Adds substantial behavior beyond annotations: 4 MB input cap, an explicit non-behavior ('invowerk writes your amounts as given. It does not compute or correct them.'), a self-validation guarantee ('never returns an invalid document'), the failure path (invalid input or failed check returns an error), and cost (5 credits per call). This is exactly the kind of context readOnlyHint/openWorldHint cannot express.

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 contract, then input field inventory, then return/error behavior, then cost. Dense but mostly non-redundant; the field enumeration is a long list that could be compressed, keeping it just short of the top mark.

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 one parameter, nested objects, an output schema, and annotations covering safety, nothing an agent needs to call this correctly is missing: input shape and limits, conditional requirements, failure behavior, cost, and returns are all stated.

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 single top-level parameter `invoice` has 0% schema description coverage, so the description carries the burden and largely succeeds by enumerating syntax (ubl default / cii), flavor (en16931 default / xrechnung), invoice_number, issue_date format, currency, parties, lines, tax_breakdown and totals. It still defers nested field detail to an external schema reference ('same schema as POST /v1/generate') and doesn't state which nested fields are required beyond the xrechnung 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 concrete verb and resource with format precision: create an EN 16931 e-invoice (UBL or CII XML) from JSON keyed on EN 16931 Business Terms. Input/output contract is clear enough to separate it from parse_invoice/validate_invoice, but no sibling is named, so the 5-level 'distinguishes from siblings' bar is only implicitly met.

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 rather than directed: the description notes equivalence to POST /v1/generate and gives a conditional prerequisite (flavor "xrechnung" requires buyer_reference / Leitweg-ID BT-10). There is no explicit when-to-use/when-not and no routing to convert_invoice, validate_invoice, or render_invoice, which the agent must infer.

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 readOnlyHint/openWorldHint annotations by disclosing hard input limits (4 MB decoded, 500 pages, 16 attachments), cost (2 credits per call), and failure behavior (errors prefixed with an error code, with named failure modes). This is exactly the operational 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 purpose, then input, then returns, then failure modes, then cost. Every sentence carries information; no filler or restatement.

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?

Despite an output schema existing, the description usefully previews `model`, `detection`, and `source`, and adds limits, error semantics, and cost. Nothing needed to call this 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?

Schema description coverage is 0% for the single parameter, so the description must carry the burden — and it does, specifying that `invoice_base64` is base64 of UBL or CII XML or a ZUGFeRD/Factur-X PDF, plus decoded-size, page, and attachment caps.

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 and resource ('Read an existing e-invoice into JSON') and even states the output convention (EN 16931 Business Terms). It relates itself to the sibling generate_invoice as a round-trip pair, though it does not explicitly distinguish itself from convert_invoice or 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?

Gives clear usage context: the result is the input format for `generate_invoice`, so it can be edited and re-submitted. This tells the agent when the tool fits in a workflow, but offers no explicit exclusion criteria against the other read/convert siblings.

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 real behavioral traits: a 4 MB decoded size cap, PDF rejection, DOCTYPE rejection, failure on malformed XML, the exact response fields, and a 1-credit cost per call. These are the kind of operation-specific constraints annotations cannot express.

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 content is front-loaded with the purpose, then input constraints, then outputs and failure modes, then cost. Every sentence carries information an agent needs; 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?

Inputs, limits, failure modes, credit cost, and return fields are all covered, and although an output schema exists the description still names the returned fields helpfully. Nothing needed to invoke this 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?

Schema description coverage is 0%, so the description must fully carry parameter meaning, and it does: invoice_base64 is defined as base64 of the XML with a 4 MB decoded limit and no PDFs, and lang is documented with allowed values 'de' (default) and 'en'.

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 states a specific verb and resource ('Render an XML e-invoice (UBL or CII, e.g. XRechnung) as a readable HTML page') and adds the intent 'show a person what an e-invoice contains', which implicitly separates it from parse_invoice or validate_invoice. It does not explicitly name a sibling or contrast itself with the conversion tool, so it falls short of a 5.

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?

'Use it to show a person what an e-invoice contains' gives a clear condition for selecting this tool versus machine-oriented siblings. There is no explicit when-not guidance or named alternative, so it does not reach 5.

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 declare readOnlyHint=true and openWorldHint=false. The description says an external KoSIT validator decides XRechnung outcomes and may be unreachable, implying an open-world external dependency that conflicts with openWorldHint=false. Otherwise it richly describes fallback, verdict_source, disagreement, findings, pdfa_verdict, hints, and cost.

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 purpose and input requirements, then behavior. Dense but mostly useful; some return-field detail (verdict_source, disagreement, pdfa_verdict) may duplicate the output schema, making it slightly longer than necessary.

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 formats, size limit, fallback behavior, output meaning, and cost, which is sufficient for a complex validation tool. The unresolved openWorldHint contradiction and absence of sibling routing beyond explain_errors are minor gaps.

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 0%, so the description carries the full burden. It documents invoice_base64 format (base64 XML UBL/CII or ZUGFeRD/Factur-X PDF, max 4 MB decoded), the explain boolean effect, and lang allowed values ('de'/'en').

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 ('Check'), resource ('e-invoice'), and validation standards (EN 16931 and German rules). It distinguishes itself from the explanation sibling by directing rule codes to explain_errors, though it does not explicitly contrast with parse/convert/render siblings.

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: validate XML/PDF e-invoices against standards, with input limit and explain/lang options. Mentions explain_errors as a follow-up for findings, but does not explicitly state when not to use it versus 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.