InvoiceIn

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

Annotations declare readOnlyHint and idempotentHint, but the description goes further: it discloses the exact return format (CSV as a string, comma-separated, header row, LF endings), error behavior for unreadable files, credit cost, anonymous quota, and the fact that nothing is stored. It also notes the path parameter is ignored on the hosted server, a behavior not implied by the schema. No contradiction with 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?

The description is long but every sentence serves a purpose. It front-loads the core purpose and output format, then progressively covers inputs, behavior, costs, and alternatives. There is no redundancy; each clause adds critical operational detail that an agent needs to use the tool correctly.

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 tool with four parameters, multiple input formats, and specific output formatting and quota rules, the description covers everything an agent must know to invoke it correctly: input paths and base64, level options, accepted XML/PDF types, size limits, return format, error handling, cost, and storage guarantees. It even accounts for the path parameter's environment-dependent behavior, leaving no 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains the KSeF number format and its source, clarifies that path is only honored over stdio, details the level parameter's row structure, and specifies accepted file types and size limits for file_base64. This significantly enriches the agent's understanding of each parameter.

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 ('Export one European e-invoice as a flat CSV table') and immediately names its sibling tools (invoice_to_datev, read_invoice) with distinct purposes, making differentiation explicit. It also details the exact output format and accepted inputs, leaving no ambiguity about what the tool does.

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 explicitly instructs when to use alternatives: 'Use invoice_to_datev for DATEV bookkeeping and read_invoice for the full JSON.' It also defines clear exclusions (plain/scanned PDFs rejected) and the file size limit, so an agent knows exactly when this tool is appropriate versus when to route elsewhere.

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 signal read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: one credit consumed per call, anonymous quota of 20 invoices per day per IP, nothing stored, unreadable files returning a tool error, and the account mapping being a default to confirm with a tax advisor. No contradiction with 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?

The description is long but every sentence carries real operational information, from usage scope to output layout to quota limits. It is slightly redundant with the schema's file_base64 description, which already lists accepted formats and the 25 MB limit, so it is not maximally lean.

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 tool with this complexity, the description is highly complete: it covers when to use it, accepted input formats, rejected inputs, output structure and encoding, post-processing requirements (UTF-8 with CRLF), error behavior, cost/quota, and privacy. An agent has enough context to call it correctly without needing 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?

The schema already covers all parameters at 100%, so the baseline is 3. The description goes further by explaining how skr influences expense account selection with concrete examples (SKR03 3400 for 19%, 3300 for 7%, etc.) and how creditor_account maps to Gegenkonto in the output. This is useful but partly overlaps with schema descriptions.

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: 'Convert one received (purchase) e-invoice into a DATEV Buchungsstapel import file (EXTF format 700)'. It also clearly distinguishes the tool from siblings by naming invoice_to_csv, read_invoice, and validate_invoice and their different purposes.

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 explicitly scopes usage to 'only for incoming invoices booked on the German side' and names alternatives with their conditions ('use invoice_to_csv for a generic table, read_invoice for the raw data, validate_invoice for rule checks'). It also warns that scanned PDFs are rejected and that no OCR is performed.

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 and idempotentHint=true, but the description adds significant behavioral detail beyond that: the output is a self-contained HTML string with inline CSS and no external assets, an unreadable file returns a tool error with the reason, each call costs one invoice credit, anonymous quota is 20 invoices per day per IP, and nothing is stored. These operational traits are not inferable from the annotations and materially affect how an agent uses the tool. No contradiction with 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?

The description is long but every sentence earns its place. It front-loads the purpose, then moves to usage guidance, input constraints, output format, error behavior, cost, quota, and storage. The structure is logical and scannable: purpose → alternatives → input → output → operational notes. No filler or redundant phrasing; the density is justified by the tool's complexity.

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 tool with many input formats, output requirements, and operational constraints, the description covers all essential aspects: input types and size limits, rejection criteria, output format (HTML string, inline CSS, no external assets), error behavior, cost, quota, and data retention. Since an output schema exists, the return value structure is already documented. The description also explicitly points to sibling tools for validation and export, making it complete for an agent to decide and invoke 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?

The input schema covers 100% of the parameters with detailed descriptions (e.g., the KSeF format, the lang enum, path vs. file_base64 usage). The tool description adds little beyond the schema: it mentions 'labels in lang' and references the input formats, but these are already captured in the parameter descriptions. With full schema coverage, the baseline of 3 is appropriate; the description does not meaningfully enhance parameter understanding beyond what the schema already provides.

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 opens with a precise verb–resource pair ('Render one European e-invoice as a self-contained, printable HTML page') and enumerates exactly what the HTML contains (header, seller/buyer, line items, VAT, totals, payment details). It also names the siblings it is not: 'it does not validate (use validate_invoice) and is not an accounting export (use invoice_to_csv or invoice_to_datev)', so an agent can immediately tell it apart from the other invoice tools without inspecting their 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?

The description explicitly states when to use this tool ('to show an invoice to a person or to print it to PDF from a browser'), when not to use it (validation and accounting export), and gives concrete exclusions (plain or scanned PDFs without embedded XML are rejected, no OCR). It also provides input format limits (25 MB, specific XML syntaxes, hybrid PDFs) and cost/quota details, so the agent has full context for choosing this tool over alternatives.

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 cover safety (readOnly/idempotent/non-destructive), and the description adds substantial operational context beyond them: cost of one invoice credit per call, an anonymous 20/day/IP quota, 'nothing is stored', error semantics (ok=false with error.code/message/hint rather than raising), the FatturaPA first-invoice-only caveat, and no-OCR rejection of plain/scanned PDFs.

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 action before usage and constraints, and each sentence carries distinct information (formats, size limit, error behavior, credit cost) rather than filler. It is dense and long, but nearly every clause 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?

With an output schema present, return values needn't be explained, and the description still covers input formats, size/OCR limits, error handling, cost/quota, and the KSeF and FatturaPA special cases. Nothing needed 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% and the schema's own parameter descriptions are extremely detailed (ksef format/lifecycle, lang enum, path stdio-only restriction, file_base64 accepted syntaxes). The description largely restates these (formats, 25 MB, ksef checked/returned on payment.ksef_number), so it adds little beyond what the schema already provides — baseline 3.

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 states a precise verb+resource+output ('Parse one European or UAE (PINT AE) e-invoice into canonical EN 16931 JSON and validate it') and immediately contrasts it with the verdict-only sibling. An agent can distinguish it from validate_invoice and the rendering tools 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 names the selection condition ('when you need the invoice content ... together with the verdict') and routes to alternatives for each other need: validate_invoice for verdict-only; invoice_to_html/csv/datev for renderings. Nothing is 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds material context beyond them: one invoice credit per call, anonymous quota of 20 per day per IP, 'nothing is stored', the 25 MB cap, and the error contract (ok=false with error.code/message/hint instead of raising). That is exactly the operational detail an agent needs for a read-only tool with quota costs.

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 routing to the alternative, then inputs, return shape, and cost model — a sensible ordering with little waste. It is dense though: the return-value sentence packs a long parenthetical list of report fields that could be tightened.

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 annotations covering the safety profile and an output schema plus a full-coverage input schema, the description only needs to add routing, limits, and failure semantics — and it does all three. 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 description coverage is 100%, so each of the four parameters is already fully documented in the schema, including the ksef identifier format and the stdio-only behaviour of `path`. The description restates the accepted input formats and the ksef cross-check but adds no syntax or constraint beyond the schema, so the 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?

Names a specific verb (validate) and resource (one European or UAE PINT AE e-invoice) and enumerates the actual rule sets applied (XSD, EN 16931, XRechnung, Peppol BIS, PINT AE, FatturaPA, KSeF, arithmetic). It also explicitly distinguishes itself from the sibling read_invoice, so an agent can route 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?

Gives an explicit when-to-use ('use it for pass/fail and the list of errors and warnings') and names the alternative with the selecting condition ('use read_invoice when you also need lines, totals and payment data'). It also states a negative case (plain or scanned PDFs without embedded XML are rejected, no OCR), covering when the tool will refuse.

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