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

Beyond the annotations it discloses that totals are computed, the official XSD is checked, invalid data is refused before charging, and the XML is returned unsigned and UTF-8. The credit-charge implication sits somewhat uneasily with readOnlyHint=true, but it is disclosure rather than contradiction, and the description adds real behavioral 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 first sentence front-loads purpose and outputs, and the long field listing is justified by the bare schema. The block is dense and compressed into a single unformatted slab, which costs some scannability, but no sentence is wasted.

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 nested builder the coverage is strong: field inventory, amount formatting ('1.234,56' or '1234.56'), tax/recargo enumerations, public-administration DIR3 codes, and the signing prerequisite. With an output schema present, return values are covered and the description still names xml, xml_base64, totals, and the validation report.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the single parameter is an open object, so the description carries the full burden and does so with a detailed field map: required/optional fields, defaults (EUR, ESP), person-vs-company name shapes, DIR3/FACe face structure, line-level tax types and recargo rates, withholding, and payment blocks.

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+resource+standard: build a Facturae 3.2.2 invoice as XML, with totals computed and XSD validation. It also implicitly separates itself from the sibling validate_facturae (build vs. validate) and from the verifactu_* tools by naming the FACe/Facturae domain.

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 context is clear: it is for turning plain data into a signed-ready XML for FACe, and the closing sentence sets a downstream prerequisite ('Sign the XML (XAdES) before sending to FACe'). What is missing is explicit routing, e.g. when to prefer validate_facturae or whether this can replace a build+validate sequence.

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, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds real value by listing the four validation dimensions (host, path, parameters, formats) and stating there is no cost, but it does not say what happens when the URL fails a check or whether validation is against a live AEAT service.

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 covering domain, validation scope and cost, with no filler. The trailing 'Free.' is terse but earns its place as a cost signal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the tool is simple with one parameter. Still missing is any failure-mode hint or sibling routing, which matters given a near-identical QR sibling in the toolset.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single 'url' parameter has 0% schema description coverage, so the description must compensate. Specifying 'a tax QR URL read from an invoice' narrows the expected input domain, which helps, but it gives no format or shape hints for the string itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Check') and a precise resource ('a tax QR URL read from an invoice'), and enumerates what is validated: official AEAT host, path, parameters and formats. It does not name the obvious sibling generate_verifactu_qr, so the check-vs-generate distinction is left to inference.

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?

'read from an invoice' implies the input context, and 'Free' signals no credit cost, but there is no explicit when-to-use framing, no exclusions, and no pointer to generate_verifactu_qr when the agent needs to produce a QR rather than inspect one.

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 openWorldHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — that the call is free — but says nothing about whether the value is live or cached, or about any rate limiting on repeated polling.

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 short fragments, front-loaded with the resource and followed by the cost note. Nothing is wasted, though the extreme terseness leaves room for a clarifying clause at no real length cost.

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 parameters, an existing output schema, and annotations covering safety, the definition is functionally sufficient to call the tool. It stops short of explaining what a credit represents or when the balance matters, leaving an agent without context for interpreting or acting on the result.

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 tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema already conveys. Baseline 4 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 resource and what it reports: the remaining credit balance on the KeyFlint license. An agent can identify it as a balance-lookup tool immediately. It does not differentiate itself from the adjacent 'pricing' sibling, which is the one tool an agent might plausibly confuse it with.

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 only implied — the 'Remaining credits' framing suggests calling it to check a balance, and 'Free' hints it can be called without consuming credits. There is no explicit when-to-use statement, no prerequisite, and no comparison to alternatives such as 'pricing'.

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, and closed-world behavior, so the bar is lower, and the description still adds real context: 'environment' selects the AEAT production versus test portal, the verifactu flag selects between ValidarQR and ValidarQRNoVerifactu endpoints, and the image uses error correction level M. It does not mention failure modes such as invalid NIF or malformed numserie, keeping it from a 5.

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 one-line purpose statement is front-loaded and the Args block is dense with zero filler; every line adds information an agent needs. The docstring-style 'Args:' formatting is slightly machine-unfriendly, but nothing is redundant.

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, the description does not need to enumerate return fields, and it still names URL and image plus the print_rules guidance. For an 8-parameter tool with rich format requirements, this is close to complete; only error behavior and the relationship to sibling validation tools are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry all parameter meaning, and it does: date format conversions (AAAA-MM-DD and DD/MM/AAAA accepted), importe requiring a decimal point with an example, size_px bounds 100-2000, image_format png/svg, and the semantic distinction behind the verifactu boolean. This is meaningfully more than the bare schema titles.

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: 'Generate the AEAT tax QR (QR tributario) of an invoice: URL and image.' This tells the agent exactly what comes back. It does not explicitly contrast itself with the sibling 'check_qr_url', so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the agent can infer this is for producing the QR that must appear on an invoice, and the 'verifactu' flag hints at which system configuration applies. There is no explicit statement of when to use this versus check_qr_url or verifactu_hash, and no exclusion or prerequisite is named.

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 openWorldHint=false, so the safety profile is covered. The description adds one behavioral fact — 'Free' — suggesting calling this tool costs no credits, which is genuinely useful context, but it is ambiguous (free tool vs. free credits) and says nothing about rate limits or how prices are kept current.

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 short front-loaded fragments with no wasted words. The terseness does cost some precision — 'Free.' is a bare fragment whose referent is unclear — but structure is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and a parameterless informational tool has little else to specify. The remaining gap is the ambiguity of the pricing units and of 'Free', which a slightly fuller sentence could resolve.

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 tool takes zero parameters, so the baseline is 4; with nothing to document, the schema and description together are sufficient. No meaningful parameter context is missing.

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 names a specific resource (credit price of each tool) and a secondary output (where to buy credits), which is distinguishable from the sibling credits_balance that reports a balance rather than prices. It is telegraphic but an agent can tell what it returns without reading 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?

Usage is only implied: an agent would consult this to learn per-tool credit costs or where to top up. There is no explicit when-to-use statement, no mention of credits_balance as the alternative for checking remaining credits, and no stated prerequisites.

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

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

Adds real behavior beyond the annotations: the specific check families performed (XSD, arithmetic FACe checks, NIF, DIR3 codes, signature presence) and the billing caveat that non-Facturae files are not charged. Annotations already cover read-only/idempotent/closed-world safety, and the output schema covers results, so this is solid but stops short of describing failure modes or severity reporting.

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 in the first sentence, then a compact enumeration of checks. The single long sentence listing checks is dense but every clause conveys a distinct validation category, so little is wasted.

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 existence of an output schema relieves the description of explaining return values, and the check list is thorough. However, with zero required parameters and two empty-defaulted content fields, the description gives no guidance on which field to populate or what happens when both are empty, which is a genuine gap for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and both parameters (content, content_base64) are undocumented, yet the description never clarifies which one accepts raw XML versus base64-encoded data, nor how a signed .xsig should be supplied. The only hint is the file-format mention, which does not map to a 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?

States a specific verb (validate), a specific resource (Facturae 3.2.2 .xml/.xsig), and the target destination (FACe or a client). This clearly separates it from siblings like build_facturae or validate_verifactu_xml without the agent needing to open a 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 clear timing context ('before sending it to FACe or a client') and enumerates the check categories, so the agent knows when this tool is applicable. It does not explicitly exclude or route against sibling validators (validate_verifactu_xml, validate_invoice_chain), which keeps it 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?

Goes well beyond the readOnly/idempotent annotations by enumerating exactly what is checked and reported: fingerprint recomputation and comparison, previous-record link verification, PrimerRegistro misuse, duplicate invoices, cancellations of unknown invoices, backwards timestamps, and invalid NIF/dates/amounts/TipoFactura. It also discloses a concrete capacity limit (20,000 records) and explains continuation semantics, which is precisely the kind of behavioral context annotations cannot carry.

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?

Purpose and input shape are front-loaded, and nearly every sentence carries load. The long comma-separated list of detected error classes is dense and reads as a run-on, and the trailing `continues_from` / `last_huella` sentences mix input-parameter and return-value concerns, slightly muddling the structure.

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, read-only audit tool with an output schema present, this covers what's needed: input record shape, ordering requirement, batch continuation, and a hard size limit. Return values needn't be re-explained given the output schema, so nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the records item schema is a bare object with additionalProperties:true, so the description must carry the load — and it largely does, spelling out `Huella`, optional `HuellaAnterior`, the `RegistroAnterior` sub-fields, and `PrimerRegistro` ("S"), plus the meaning of `continues_from`. It loses a point because the referenced `verifactu_hash` fields are not enumerated here, forcing the agent to consult a sibling, and `last_huella` is described as an output-style field in ambiguous proximity to the input parameters.

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?

Opens with a specific verb+resource+scope: "Audit a VERI*FACTU chain of records (in generation order) given as JSON objects." That distinguishes it clearly from siblings like verifactu_hash (single fingerprint) and validate_verifactu_xml (XML validation), so an agent can route correctly without opening a 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?

Tells the agent the prerequisite shape of the input (records in generation order, JSON objects) and gives an explicit batching workflow via continues_from for auditing "a chain in pieces." It also states the operational ceiling of 20,000 records. It stops short of explicitly naming which sibling to use for single-record hashing or XML input, so it earns a 4 rather than 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety and determinism are covered without prose. The description adds one genuinely new behavioral fact — 'Free', i.e. no credit consumption — but says nothing about how format problems (dashes, lowercase, wrong length) are handled versus checksum failures. A 3 fits because annotations carry most of the burden and the text adds only marginal 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?

Two terse fragments with the core action and resource front-loaded and the cost note appended. Nothing is redundant and the whole definition is scannable in one pass.

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, deterministic validator with an output schema and full annotation coverage, the description supplies what an agent needs to select and call it: the identifier family and the fact that it is free. The main residual gap is input-format expectations, though the output schema relieves the need to describe return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single required parameter, which the schema only labels as a bare string titled 'Nif'. The description partially compensates by enumerating the accepted identifier types (NIF, NIE, CIF), which is real meaning beyond the schema. It still omits expected format details such as separators, case, or length, so compensation is incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb ('Check') and a precisely scoped resource ('Spanish NIF / NIE / CIF control character'), so an agent knows it validates tax-identifier checksums rather than performing a generic string check. It is clearly distinct by resource from sibling validators such as validate_facturae or validate_verifactu_xml, though it does not name those siblings 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?

Usage is implied by the resource name: call it when a Spanish tax ID needs verification. There is no explicit statement of when not to use it, no mention of alternatives for non-Spanish identifiers, and no prerequisites, so guidance stays at the implied level. The 'Free' note does hint at a cost consideration versus paid siblings, which is a small added signal.

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 and idempotent, so the bar is lower. The description still adds real value: schema validation against SuministroLR.xsd happens 'when present' (i.e., conditionally), all chain and fingerprint checks are re-run, and empty-record XML is not billed — a billing behavior not visible in 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?

Two short sentences plus a note, front-loaded with the verb and resource and then the validation steps in execution order. Minor line-wrapping aside, no filler sentences.

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 output schema covers return values and annotations cover safety, so the remaining burden is input semantics and they are unaddressed. For a three-parameter tool with two mutually exclusive content fields, the definition leaves a material gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across three parameters, so the description must carry parameter meaning and does not. It never explains whether to populate content versus content_base64, or what continues_from does (presumably resuming a chain across documents); an agent must guess.

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 (Audit) and resource (VERI*FACTU XML) and enumerates the accepted document shapes (RegFactuSistemaFacturacion, SOAP envelope, raw RegistroAlta/RegistroAnulacion). It also positions itself relative to validate_invoice_chain by running that tool's checks on top of schema validation, though the wrapper relationship could be stated more directly.

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 accepted-format list and the note that empty XML is not charged, so an agent can infer this is for auditing exported invoice files. There is no explicit when-not guidance or statement of when to call validate_invoice_chain directly instead of this wrapper.

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 openWorldHint=false, so the safety profile is covered and the description's 'Free' note usefully adds cost/paywall context. It also discloses that results come with sources and indicate what is still pending publication, which tells the agent the data may be incomplete — but it says nothing about refresh cadence or how current the deadlines are, which matters for a time-sensitive legal calendar.

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 short sentences with the resource and its coverage front-loaded, followed by the caveat about pending publication. The one-word 'Free.' fragment is slightly abrupt but carries real value about pricing, so nothing is wasted.

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 parameters and an output schema present, the description does not need to explain return values, and it is complete enough for an agent to call and correctly interpret the result. The only meaningful omission is the data's currency or last-updated status for a deadline-oriented 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?

There are zero parameters, so baseline is 4; the description appropriately spends no space on arguments. The only semantic risk — whether the calendar can be scoped by date, region, or business type — is not addressed, but with an empty schema there is nothing to clarify.

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 names the specific resource (legal deadlines for VERI*FACTU and mandatory B2B e-invoicing in Spain) and its scope, which is clearly distinct from the sibling tools that all validate, hash, or generate verification artifacts. It is not phrased as a verb, but the resource and its domain are unambiguous, so an agent can tell this is the informational lookup among the validation 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?

Usage is only implied: an agent can infer this is the tool to call when it needs compliance dates rather than validation results. There is no explicit statement of when to use it, no exclusion of cases, and no reference to a sibling alternative or prerequisite, though in practice no sibling covers this information.

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 cover the safety profile (readOnly, idempotent, closed-world), and the description adds real value on top: it discloses that the return includes the fingerprint, the exact hashed string, and field problems, and that any error implies AEAT would reject the record. Missing only operational details such as auth or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose, then uses a compact nested listing keyed by record type rather than prose. The density is justified by the format requirements, though the indented field enumeration is slightly harder to scan than a tighter layout.

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?

Complete for a two-parameter hashing tool with a nested free-form object: both record variants, the chain-link input, and error semantics are covered, and an output schema exists so return structure needs no further explanation. Nothing an agent needs to call 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 coverage is 0% and the record object is free-form (additionalProperties: true), so the description carries the entire burden and does so thoroughly — enumerating AEAT field names, date/time formats (DD-MM-AAAA, AAAA-MM-DDThh:mm:ss+hh:mm), allowed TipoFactura codes, decimal-point convention, and the empty-string meaning of previous_huella.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Compute the VERI*FACTU fingerprint (huella, SHA-256) of one invoicing record.' The scoping to a single record, plus the chain-link parameter, distinguishes it from sibling validate_invoice_chain and from generate_verifactu_qr 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?

Gives concrete usage context: which AEAT fields to supply for an 'alta' vs an 'anulación' record, and that previous_huella is empty for the first record of the chain. It does not explicitly state when to prefer this over validate_invoice_chain or validate_verifactu_xml, so alternatives are left implicit.

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