Attestwire

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: it explicitly states the tool cannot confirm platform registration and that the result says so, plus emphasizes it is free and keyless, which sets expectations about authentication and output limitations.

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 two sentences, front-loaded with the primary purpose and supported by a clear limitation and access note. Every sentence carries necessary information with no redundancy or 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?

For a single-parameter, read-only lookup with no output schema, the description is self-contained: it defines what the tool does, what inputs it accepts, what it confirms (existence and active status), and what it cannot confirm, including where that missing data lives. This is sufficient for an agent to decide when and how to invoke it.

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 already provides 100% coverage of the 'query' parameter, describing it as a 9-digit SIREN, 14-digit SIRET, or company name. The description restates this but adds no new formatting constraints or usage nuances, so the baseline score of 3 is appropriate.

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 clearly states the tool looks up a French company in INSEE SIRENE data by SIREN, SIRET, or name for the 2026-2027 e-invoicing mandate. This is a specific verb+resource combination that distinguishes it from siblings like check_vies_status (VAT status) and list_approved_platforms (platform registry).

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 not to use it: it cannot confirm platform registration, and directs the user to the CAPTCHA-protected DGFiP annuaire as the only source for that. It also sets context for the e-invoicing mandate and notes it needs no API key, making it a clear first-stop lookup 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?

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context: it describes the monitoring cadence (polls every 5 minutes), the specific metrics exposed (status, latency, 24h/7d uptime), and the free/no-API-key requirement, which goes beyond what annotations provide.

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 concise at three sentences, each contributing meaning: what the service is, what data it provides, and when to use it. It is front-loaded with the core purpose and contains no filler or redundancy.

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 simple one-parameter read-only tool with no output schema, the description is sufficiently complete. It states the data returned (status, latency, uptime), the polling interval, the use case, and the lack of authentication, leaving no significant gaps for an agent to invoke the tool 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 already thoroughly documents the optional 'country' parameter with pattern and semantics. The description adds no additional parameter-specific details (e.g., default behavior is already in the schema). Schema coverage is 100%, so a baseline score of 3 is appropriate.

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?

Description clearly states the tool reports current availability of VIES, the EU VAT validation service, with per-member-state status, latency, and uptime. It explicitly ties to its name and distinguishes from sibling validation tools by focusing on service availability rather than VAT number validity.

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 usage guidance: 'Use this when EU VAT number validation is failing, to tell 'their VAT number is wrong' apart from 'that member state's VIES endpoint is down'. This directly addresses when to invoke this tool versus alternatives, though it does not name siblings explicitly.

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 indicate readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral context beyond those: it discloses authentication/access (no API key), and transparently explains behavior for missing rules ('says so and links the rule reference rather than pretending the rule does not exist'). This is exemplary transparency.

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 concise and front-loaded: the first sentence establishes the core purpose, followed by coverage scope, edge-case behavior, and cost/auth. Every sentence carries essential information without fluff or repetition, earning a perfect score.

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 read-only tool with no output schema, the description is remarkably complete. It not only states what the tool does but also describes the content of the explanation (what it requires, why, business term, fix, example), covers edge cases (unwritten rules), and provides access requirements. This gives the agent full context for invocation and expectation setting.

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 provides full coverage of the single parameter rule_id with examples, so the baseline is 3. The description does add some context about the rule families (BR-*, BR-CO-*, etc.) and that some rules are not covered, which helps the agent understand what rule_id values are expected, but it doesn't add significant new semantics beyond the schema.

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 uses the specific verb 'Explain' and clearly identifies the resource: 'one EN 16931 / XRechnung / Peppol BIS rule'. It further details what the explanation includes (requires, why, business term, fix, example), making it distinct from sibling tools like validate_invoice or check_vies_status. This leaves no ambiguity about the tool's function.

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 when to use it (to understand a rule) and notes coverage limitations ('most, not all' rules), providing helpful context for expectations. It also mentions 'FREE and needs no API key', which guides usage by distinguishing it as an accessible option. However, it does not explicitly list alternative tools or when-not-to-use conditions, so it stops short of full 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?

The description discloses important behaviors beyond annotations: validation-before-generation with refusal on invalid invoices, the lack of KoSIT validation at call time, cost and API key requirement, and the CII vs UBL syntax differences. 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 densely packed with necessary details, and it is front-loaded with the core purpose. Each sentence contributes value, though a bit more trimming could improve readability.

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 one nested parameter and no output schema, the description thoroughly covers validation flow, profile selection, credit note behavior, PDF caveat, and authentication/cost requirements. It leaves no critical 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?

The schema already covers the parameter thoroughly (100% coverage), and the description adds meaningful context: credit note handling via invoiceTypeCode '381', profile-specific requirements for XRechnung, and the note that amounts remain positive on credit notes.

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 clearly states the tool's function with a specific verb and resource: 'Generate compliant e-invoice XML from a JSON invoice.' It also lists supported profiles and distinguishes itself from sibling validation tools by focusing on generation.

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 provides clear context on when to use the tool, including handling credit notes and the XML-only limitation (never PDF). It also explains profile-specific behavior, but it does not explicitly name alternatives like validate_invoice for validation-only tasks.

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 annotations (readOnlyHint=false, idempotentHint=false), the description discloses critical behavioral traits: it creates a checkout link, charges nothing, requires a human to complete payment, and costs no documents. This goes well beyond the structured metadata and clarifies side effects and limitations.

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?

Every sentence earns its place: it starts with the core purpose, then highlights critical warnings, gives usage context, and ends with the document cost. The structure is front-loaded and the length is appropriate for the 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?

The tool has no output schema, but the description adequately explains the return type (hosted checkout URL) and covers the full flow: link creation, human confirmation, non-purchase side effects, and usage trigger. For a two-parameter tool, this is fully complete.

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 already describes both parameters with full coverage, including key optionality and plan enum values with prices. The description adds some context about plan limits (2,500 vs 25,000 documents) but largely reiterates schema information. Thus the schema carries the semantic weight, and the description provides marginal extra value.

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 uses a specific verb and resource: 'Return a hosted checkout URL for upgrading an Attestwire key to a paid plan.' It also distinguishes the tool from siblings by detailing the plans (starter/scale) and emphasizing it only creates a link, not a purchase. This is unambiguous and unique among the sibling 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 explicitly states when to use it: 'Use this when a key has hit its quota or the user asks to upgrade.' It also provides clear exclusions: 'THIS DOES NOT BUY ANYTHING' and 'You cannot complete the purchase and must not report it as completed.' This gives the agent firm guidance on when and how to invoke.

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 description is exemplary in disclosing critical behavioral traits: the key is returned only once and cannot be recovered, only a SHA-256 hash is stored, and it explicitly instructs the agent to show the key verbatim and tell the user to save it. This goes far beyond the annotations, which only provide basic hints. The 100 documents/month limit also adds valuable context.

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 concise yet complete, with a clear front-loaded purpose. The critical warning is emphasized with caps and a dash structure. Each sentence contributes: purpose, usage context, security warning with actionable instruction, and constraint. No wasted words.

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 no output schema, the description covers the most essential context: the purpose, the constraint, and the irreversible key return. It could explicitly state the output format, but the instruction to 'show it to the user verbatim' implies the key is returned in a usable form. This is nearly complete.

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 provides complete coverage for the only parameter, email, including a format and description. The tool description reinforces the one-key-per-address rule but does not add technical details beyond the schema. Baseline 3 is appropriate since the schema handles the semantics fully.

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 specific verb and resource: 'Mint a free Attestwire API key'. It clearly differentiates this from sibling tools by explicitly stating that this key enables validate_invoice and generate_invoice. The scope (100 documents/month, no signup flow) adds precision.

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 states 'so validate_invoice and generate_invoice can be used', which establishes when this tool is needed. It also provides constraints like 'One key per email address' and sets expectations with 'no signup flow, no card'. It doesn't explicitly mention alternatives because no alternative exists, but the context is clear.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds value beyond annotations by stating the data comes from a 'published open dataset' and that it is 'FREE and needs no API key', which are behavioral/access traits not covered by annotations. No contradictions.

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 two concise sentences that are front-loaded with the core purpose. Every phrase adds value: official list, data source, optional filter, and access requirements. No redundant or filler text.

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 simple read-only list tool with one optional filter, the description fully covers usage, data source, and access constraints. There is no output schema, but the tool's return value is a list of platforms, which is evident. The sibling tools are clearly distinct, so no additional context is needed.

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 only parameter ('query') is fully described in the schema as an optional filter by platform name or SIREN, which the description echoes. With 100% schema coverage, the description does not need to add much; the baseline 3 is appropriate. No additional semantic nuance is provided beyond what the schema already contains.

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 uses a specific verb ('list') and clearly identifies the resource ('DGFiP-approved French e-invoicing platforms'). It also specifies the data source ('published open dataset') and distinguishes itself from sibling tools by focusing on listing approved platforms rather than checking readiness or validating 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?

The description explains when to use the tool (to get the official list of approved platforms) and how to optionally filter by name or SIREN. It also notes that it is FREE and requires no API key, which helps in choosing it over paid/key-requiring tools. However, it does not explicitly mention when to use an alternative tool, though the sibling names make that implicit.

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 state readOnly and idempotent, but the description adds substantial behavioral context not visible in structured fields: the tool consumes one document against a monthly quota, requires an API key, and returns teaching errors with rule IDs, business terms, requirements, and fixes. It also details credit-note behavior (same object, invoiceTypeCode 381, positive amounts), which is a critical behavioral edge case.

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 concise yet information-dense: first sentence states purpose and standards, second describes return format, third covers prerequisites and quota cost, fourth explicitly references an alternative tool, and fifth provides schema URL. Every sentence earns its place, with no redundant 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?

Given the tool's complexity (multiple CIUS profiles, quota cost, authentication) and the absence of an output schema, the description is complete. It explains what the return contains (teaching errors), the full depth of the invoice object via a linked OpenAPI spec, and the credit-note exception. It also notes the sibling explain_rule for free rule lookup, covering the broader context.

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 already describes the single 'invoice' parameter in depth, including required fields, profile enum, and the credit note handling. The tool description reinforces those details but adds no new parameter-specific meaning beyond what the schema provides. With 100% schema coverage, the baseline of 3 is appropriate.

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 'Validate an invoice against EN 16931 and its national CIUS rule sets,' naming the specific standards (XRechnung UBL/CII, Peppol BIS 3.0, Factur-X). It clearly distinguishes from siblings by pointing to explain_rule for rule ID explanations and implying validate_invoice_xml handles XML input vs. this object-based validation.

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: validating an invoice object. It states prerequisites ('REQUIRES AN API KEY') and directs users to issue_api_key first. It also names the alternative for rule ID lookup ('use explain_rule instead: it is free'), making the choice between tools 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?

With annotations declaring readOnly and idempotent, the description adds valuable context: requires an API key, costs 1 document, decides syntax from the root element, reports unmodeled content, and refuses PDFs with an explanation. No contradiction with annotations; behavior is fully disclosed beyond what annotations alone indicate.

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 dense but every sentence contributes: input constraints, accepted formats, error behavior, return values, cost, and limitations. It is slightly long but warranted given the tool's complexity and the need to prevent common misuse (e.g., sending PDF containers). Structure is logical: definition, usage trigger, exclusions, caveats, requirements.

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 having no output schema, the description enumerates expected return elements (syntax, BT-24/BT-23, teaching errors, unmodeled content) and clarifies edge cases (credit notes accepted, PDFs refused, pre-flight not authoritative). It also mentions API key and cost. This makes the tool's behavior and constraints complete for an agent to decide and invoke appropriately.

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 already covers the 'xml' parameter (complete text, not a path, allowed root elements, not PDF bytes). The tool description goes further by instructing to send the file as-is without pre-determining syntax or document type, explaining why (tool decides from root element), and reinforcing that a PDF should not be sent. This adds operational meaning beyond the schema.

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 clearly states the tool validates an existing e-invoice file (UBL or CII) and returns teaching errors, syntax, BT-24/BT-23, and unmodeled content. It distinguishes itself from sibling validate_invoice by explicitly saying it returns the same errors plus additional file-specific information, making its scope clear.

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 when someone says 'this invoice was rejected, why?' and hands you a file." It also gives clear exclusions (XML only, not PDF; extract XML from Factur-X/ZUGFeRD; PDFs are refused and should not be retried) and notes credit notes are accepted. The pre-flight disclaimer (not an authority) further calibrates expectations.

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