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 already declare readOnlyHint and idempotentHint, and the description adds substantial context: it states nothing is stored, costs one credit per call, has an anonymous quota, returns ok=false with error details instead of raising, handles FatturaPA lots with a note, and explains KSeF handling. No contradiction with annotations; the description enriches the safety and operational profile.

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 useful information. It opens with the purpose, then usage routing, then input constraints, then behavior, then special cases, then costs. It is structured and front-loaded; the length is justified by the tool's complexity. It loses a point only for being slightly dense, though not wasteful.

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 the tool's complexity (many formats, validation, credit costs, special cases) and the presence of an output schema, the description covers everything an agent needs to decide and invoke correctly: input formats, size limits, rejection criteria, return shape, error handling, cost, and storage. It does not need to repeat output schema details, and it doesn't.

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% with detailed descriptions, yet the description adds meaningful context beyond the schema: it explains the KSeF number format and why it's not in the XML, clarifies that path is ignored on the hosted server, and details file size limits and accepted formats. This goes well beyond the baseline of 3 and fully compensates for any potential ambiguity.

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 (parse + validate) and a specific resource (e-invoices), and explicitly distinguishes itself from siblings by naming what validate_invoice and rendering tools do. An agent can immediately tell this is the content+verdict tool, not the verdict-only or rendering alternative.

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 when-to-use ('when you need the invoice content together with the verdict') and names the alternatives with their distinct purposes ('use validate_invoice for a verdict-only answer, invoice_to_html / invoice_to_csv / invoice_to_datev for renderings'). It also clarifies input constraints and rejection cases, so an agent knows exactly when to select this tool.

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?

The annotations already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond those hints: unreadable files return ok=false instead of raising an exception, nothing is stored, one invoice credit is consumed per call, and the anonymous quota is 20 invoices per day per IP. No contradictions 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 well-organized, front-loading purpose and usage, then covering return values, input constraints, KSeF specifics, and operational details like credits and storage. Some redundancy with the extensive schema descriptions exists, but every sentence contributes useful context for a complex validation tool.

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 complex tool with an output schema, the description covers all essential operational aspects: accepted inputs, file size limit, error behavior, KSeF handling, cost/quota, storage, and when to choose a sibling tool. Nothing needed for correct invocation appears to be 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. The description adds real value by explaining how the ksef parameter is validated against the invoice and returned on payment.ksef_number, and by clarifying that path is only honoured over stdio while the hosted server ignores it. This goes beyond the schema's already-detailed field 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: 'Validate one European or UAE (PINT AE) e-invoice against the official rule sets' and 'return the verdict without the invoice body.' It distinguishes itself from read_invoice by explicitly noting that read_invoice is for when lines, totals and payment data are also needed.

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?

Provides explicit when-to-use guidance: 'Use it for pass/fail and the list of errors and warnings; use read_invoice when you also need lines, totals and payment data.' It also clarifies input boundaries, including accepted XML/PDF formats and rejection of plain or scanned PDFs without embedded XML.

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