StanzaAPI

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

No annotations are provided, so the description carries the full behavioral-disclosure burden. It names the regulation and calculation scope but says nothing about determinism, required inputs beyond the schema, error handling, side effects, rate limits, or what the returned values represent.

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?

A single front-loaded sentence with zero waste. The regulation citation and input list are all useful and nothing is repeated unnecessarily.

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?

This is a complex regulatory calculation with no annotations and no output schema. The description explains what is calculated but not what the result contains, how emissions or liability are returned, or what units/format to expect. An agent would be left guessing about the output contract.

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 all nine parameters in detail. The description lists several inputs but adds no syntax, units, or meaning beyond what the schema 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?

States a specific verb (Calculate) and a specific regulated resource (EU CBAM embedded emissions and liability), with the exact inputs it consumes. Sibling tools are all validators/parsers/decoders, so this calculation tool is clearly distinguished.

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 by the name and description: use this when calculating CBAM emissions and liability. However, it does not state when to prefer it over alternatives, nor does it provide any exclusion or prerequisite 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?

No annotations exist, so the description carries full behavioral burden. It discloses the accepted encodings and the fields returned, but says nothing about error behavior on malformed element strings, whether GTIN check digits are validated, or whether parsing is deterministic/side-effect free. Useful but incomplete for a zero-annotation 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?

A single front-loaded sentence that packs the verb, supported formats, and output fields with no filler. Nothing needs trimming.

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 no output schema, the description helpfully names the returned fields (GTIN, lot, serial, expiration), and input formats are fully covered. It leaves error handling and check-digit validation unstated, which is a minor but real gap for a parser.

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 only 2 parameters, so the schema already documents both 'data' and 'domain'. The description restates the same format list for 'data' and adds nothing about how 'domain' affects short-key resolution, 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?

States a specific verb ('Decode') paired with a precise resource and enumerates the accepted input encodings (GS1-128, DataMatrix, FNC1, bracketed AIs, Digital Link URI) plus the output fields. Closest sibling decode_udi is clearly a different standard, so the agent can distinguish this tool without opening the 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?

The accepted input forms imply when the tool applies, but there is no explicit when-to-use guidance, no prerequisites, and no routing hint toward decode_udi or the validate_* siblings. Usable by inference rather than by instruction.

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 no annotations, the description carries the full burden. It discloses the outputs produced and the optional live-registry verification, but leaves compliance checking vague: it doesn't say what FDA GUDID / EU MDR checks are performed, what happens on a non-compliant or unparseable UDI, whether 'live' requires network access, or whether failures raise errors or are reported in the result.

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?

A single dense sentence that front-loads the core action and layers optional detail after semicolons; nothing is wasted, though the sentence is long enough that a period before the optional live-verify clause would read slightly better.

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 low-complexity two-parameter read tool with no output schema or annotations, the description covers the input formats, the decoded output fields, and the optional live path, which is most of what an agent needs. Remaining gaps are failure semantics and the specifics of the compliance checks.

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 both 'udi' and 'live' are already documented in the schema with an example string. The description restates the live-verification behavior but adds no syntax, format, or edge-case detail beyond the schema, matching the baseline of 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?

States a specific verb (Decode) and resource (UDI string), names the three supported carrier standards (GS1, HIBCC, ICCBBA), and specifies the decoded outputs (DI, lot, serial, expiration). It also clearly differentiates itself from the sibling decode_gs1 by spanning multiple carrier formats and adding compliance checks.

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 (decoding a UDI carrier) and notes the optional live-GUDID path, but never states when to prefer this over the sibling decode_gs1, nor any exclusions or prerequisites. Usage is inferable rather than explicit.

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 no annotations provided, the description has to carry the behavioral load. It does disclose two useful traits: automatic message-type detection and structured JSON output. However it says nothing about error/failure behavior, whether parsing is side-effect free, permission needs, or what 'structural checks' in validate mode actually covers.

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?

A single dense sentence that front-loads the verb and resource, then qualifies scope. It is efficient, though the parenthetical message list plus 'with automatic...' clause makes it slightly long for one sentence.

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-param tool with no annotations and no output schema, the description should clarify return shape more than 'structured JSON output'. Parse mode is covered at a high level, but the structure of validation results and failure modes remain unspecified.

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 xml, operation, and messageType with defaults and allowed values. The description only echoes the parse/validate and auto-detection semantics already present in the schema, adding no syntax or format detail beyond it.

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 (parse/validate) plus the exact resource family (ISO 20022 XML) and enumerates the concrete message types handled (pacs.008, pain.001, camt.053). The domain is narrow enough that an agent can immediately distinguish it from parse_x12_edi or decode_gs1 despite no explicit sibling reference.

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 makes the parse-vs-validate choice implicit by bundling both operations, and it hints at applicability to 'payment reconciliation', but it never states when to prefer this tool over adjacent format parsers or when validation is warranted instead of parsing. Usage is inferable, not spelled out.

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 no annotations, the description bears the full behavioral burden. It does disclose useful behavior: output is structured JSON with interchange envelopes, delimiters, SNIP levels 1-4, and per-segment error diagnostics. It does not mention authentication, input size limits, error exception behavior, or whether validation is strict or advisory.

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 a single front-loaded sentence with no filler. It packs a lot into one sentence, which slightly reduces readability, but every clause provides substantive information about scope and output.

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 or annotations, the description summarizes the return shape (structured JSON with envelopes, delimiters, diagnostics) and the validation modes. It could say more about error responses or operation defaults, but it is largely complete for this parser/validator.

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 all four parameters are already documented in the input schema. The description mentions SNIP levels and parse vs validate, but adds no syntax, constraints, or defaults beyond what the schema provides. Baseline 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 states a specific verb pair (parse or validate) and resource (ANSI X12 EDI healthcare transactions), then enumerates the transaction types (837P, 835, 270/271) and outputs. This is specific enough to distinguish it from siblings like parse_iso20022, which handles a different standard.

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 domain (healthcare X12 EDI) implicitly indicates when to use this tool, and the operation parameter clarifies parse vs validate. However, there is no explicit when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as validate_dscsa or parse_iso20022.

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 no annotations, the description carries the full burden, and it does disclose the actual checks performed (NDC/GTIN checks, expiry validation) and that an optional reference date defaults to today. It says nothing about return format, what a failed validation looks like, or whether the GTIN check digit is validated, which are notable gaps for a verification tool with no output schema.

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?

A single sentence with the core action front-loaded and no filler. Both input modes are compressed into one parenthetical clause, so nothing needs trimming.

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 description usefully compensates for the otherwise dangerous fact that all six parameters are optional by signaling the two valid input shapes. However, with no annotations and no output schema, it never states what the verification returns, leaving the agent to guess at the result contract.

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 every parameter's format and constraints are already documented in the schema. The description groups the four DSCSA elements and identifies barcode as an alternative, but adds no syntax or exclusivity rules beyond what the schema states — 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?

States a specific verb (Verify) and resource (pharmaceutical product identifier) with the governing standard (FDA DSCSA) named. It also distinguishes itself from generic siblings like decode_gs1 and decode_udi by specifying the DSCSA identifier set it validates.

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 makes the two accepted input modes explicit ('a GS1 DataMatrix barcode or the GTIN + serial + lot + expiration element set'), which tells the agent how to invoke it. It gives no explicit when-not-to-use or sibling routing (e.g., versus decode_gs1 or decode_udi), so it stops short of a 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses the output content (detected profile from a named list, violations with exact rule IDs, extracted invoice JSON) and flags a capability boundary (PDF/A-3 only on the HTTP API). It omits error/limit behavior, but for a validation tool the safety profile is largely self-evident.

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?

A single dense sentence, but it is front-loaded with purpose and then enumerates return values in order of usefulness. No filler, though the sentence is long enough that a reader must parse several clauses.

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?

No output schema exists, so the description's enumeration of return values (profile, violations, invoice JSON) is doing necessary work, and the two-input surface is simple. Missing only the shape of error responses and any input size constraints.

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 both xml and operation are already documented, including the default of 'validate'. The description reinforces the operation semantics and accepted XML dialects but adds no syntax or format detail beyond the schema, making the baseline 3 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?

States a specific verb (validate/parse) plus the exact resource (Factur-X/ZUGFeRD 2.x/XRechnung CII e-invoice) and the standard applied (EN 16931 BR-01..BR-65). This clearly separates it from siblings like validate_peppol and parse_iso20022, which target different formats.

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 distinguishes the two operations (validate vs parse) and discloses that PDF/A-3 extraction is only available via the HTTP API, which is actionable context. It does not, however, state when to reach for this tool over validate_peppol or how the two e-invoicing validators differ.

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 no annotations, the description carries full behavioral burden. It usefully discloses the validation algorithm (modulo-7 check digit per IATA Resolution 600a) and format expectations, but says nothing about return values, whether validation is offline/local, or failure modes.

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?

A single front-loaded sentence with no filler; the standard reference is the only slightly expendable clause. Appropriate size for a one-parameter 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 simple one-param validator the description is nearly adequate, but with no annotations and no output schema it leaves the return shape (boolean vs. structured result) and any error behavior undefined.

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 the single parameter is well documented in the schema, so baseline is 3. The description adds genuine meaning by spelling out the internal structure (3-digit airline prefix + 8-digit serial + modulo-7 check digit) that the schema only shows by example.

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 (validate) and resource (IATA air waybill number), then decomposes the expected format into prefix, serial, and check digit. This clearly separates it from siblings like validate_iban or validate_lei, though it never names an alternative 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?

No when-to-use statement, no prerequisites, and no mention of alternatives among the many sibling validators. The phrase 'for air cargo freight documentation' faintly implies context but does not tell an agent when this tool should be chosen over another.

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?

No annotations are provided, so the description carries the full behavioral burden. It helpfully lists the validation layers applied (checksum, structure, BBAN, SEPA, formatting), but never states that the operation is non-mutating, whether it performs network/lookup calls for SEPA reachability, or what the result looks like. It adds real value over a bare name but leaves gaps for a no-annotation 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?

Two tight sentences: the core IBAN validation with its checks leads, the optional BIC path follows. No filler or repetition; 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?

For a read-only validator with no output schema and no annotations, the description covers what is checked but not what is returned (e.g., validity flag, parsed components, error reasons) or whether SEPA reachability requires external lookups. Adequate for invocation, but incomplete for interpreting results.

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%, with both parameters fully documented (including the 8-11 char BIC range and space tolerance on IBAN). The description reinforces the optional BIC behavior but adds no format or syntax detail 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?

States a specific verb (validate) and a precise resource (IBAN, ISO 13616), and enumerates the exact checks performed (MOD-97-10, country structure, BBAN parsing, SEPA reachability, formatting). The resource is unambiguous relative to disjoint siblings like validate_lei, validate_vat, and validate_iso6346_container.

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 this tool is relevant (any time an IBAN/BIC must be checked) but never states when to prefer it over alternatives or any exclusions. Because siblings operate on entirely different identifiers, routing ambiguity is low, so 3 ('implied usage') is appropriate rather than a penalty.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It enumerates the validation components and mentions the modulo-11 check digit, but says nothing about what the tool returns, how failures are reported, or whether output is a boolean or structured result.

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?

A single, front-loaded sentence that packs the essential validation details without any filler. Every clause contributes to understanding the tool's scope.

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?

No output schema exists, and the description does not explain return values, error behavior, or success/failure signaling. While parameter semantics are fully covered by the schema, the absence of any return information leaves the definition incomplete for a validation tool.

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 both parameters are already documented in the input schema. The description largely restates the same concepts and adds only the modulo-11 detail for the check digit, which is marginal added meaning over 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?

States a specific verb (validate), resource (ISO 6346 intermodal shipping container number), and breaks down the components (BIC owner prefix, equipment category identifier, serial number, modulo-11 check digit). The resource is unique among siblings, so an agent can immediately tell it apart from other validators like validate_iata_awb or validate_iban.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The description does not name alternatives or conditions that would select this tool over sibling validators, leaving usage entirely implied by the tool name.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses two modes (offline checksum/format validation and optional live GLEIF registry lookup), but omits auth requirements, rate limits, error behavior, and response characteristics.

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?

A single, front-loaded sentence with no filler. It efficiently covers the purpose, validation scope, and optional live mode.

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 no output schema and no annotations, the description should do more to explain return values and error behavior (e.g., boolean result, validation failure details, live registry response). It covers call semantics adequately but leaves meaningful gaps about outcomes.

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 baseline is 3. The description mirrors the schema's explanations for 'lei' and 'live' without adding syntax, format, or semantic detail beyond what the input 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?

States a specific verb (Validate) and resource (LEI, ISO 17442), then details the validation scope: checksum, 20-character format, LOU prefix/entity code, and optional live GLEIF verification. This is clearly distinguishable from sibling validators for other identifier standards.

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: use this tool when validating an LEI. The optional live mode is described, but there is no explicit when-to-use/when-not guidance or routing against alternative identifiers, which is especially relevant given the many sibling validate_* tools.

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?

No annotations are provided, so the description carries the full burden; it does disclose what the call returns (rule violations, billing profile, totals, extracted invoice JSON) and the accepted input dialects. It omits any mention of failure behavior, e.g. malformed XML handling or whether errors surface as violations versus exceptions, which is the remaining gap.

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?

A single dense sentence front-loads the action and resource, then layers formats, ruleset and return payload. No filler or repetition.

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 two-parameter, no-annotation tool, the description covers input dialects, the standard applied, and the outputs returned, which is close to complete. Without an output schema, some structure of the returned violations/totals remains unstated, but the essentials an agent needs are present.

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 both 'xml' and 'operation' including the validate/parse meanings, which the description merely echoes. Baseline 3 is appropriate since the description adds no syntax or format detail beyond structured fields.

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 specific verbs (validate/parse), the exact resource (Peppol BIS Billing 3.0 e-invoice), the accepted syntaxes (UBL 2.1 Invoice/CreditNote, UN/CEFACT CII) and the ruleset (CEN TC 434). This clearly distinguishes it from siblings like validate_facturx without opening the other 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?

The description implies the two modes of use and the schema marks 'validate' as the default, but there is no explicit when-to-use versus when-not guidance or a named alternative among the many sibling validators. Usage is inferable but not spelled out.

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 no annotations, the description carries the full behavioral burden. It does disclose useful behavior: two validation modes (offline syntax/checksum vs live registration check) and that rates are returned. However, it omits failure semantics (does an invalid number error or return a flag?), the fact that live checks depend on an external service subject to availability/rate limits, and any permission requirements.

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?

One front-loaded sentence that leads with the core action and appends the optional live mode as a trailing clause. No filler, no restatement of the title.

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 is simple (1 required param, no nesting) and the description does partially compensate for the absent output schema by naming what is returned (standard and reduced VAT rates). Still, with no output schema and no annotations, an agent lacks detail on the response shape, invalid-number behavior, and live-mode failure modes.

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 only two parameters exist, so the schema already documents both vatNumber (format, prefix example) and live (VIES/HMRC verification). The description restates the live semantics but adds no format, casing, or country-prefix detail beyond the schema. 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?

States a specific verb (validate) and resource (EU/UK VAT number) plus the mechanism (VIES/HMRC syntax and checksum rules) and the payload (standard and reduced VAT rates). This is clearly distinct from the sibling validators (validate_iban, validate_lei, validate_iata_awb, etc.) without needing to name them.

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 signals the base use case and explains the conditional path: 'optionally verify live registration status against VIES or HMRC,' which tells the agent when the live flag matters. It stops short of explicit exclusions or fallback guidance (e.g., what to do when VIES is unavailable), so no 5.

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