contix

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing that existing files are preserved, that an expense holds at most 5 files, that contix stores but does not read the file, accepted formats and the 10 MB cap. It also pre-announces the return payload (expense id, stored file name, file count), which no structured field provides.

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 core action, then layers constraints, prerequisites and return values in a tight paragraph with zero filler. The parenthetical examples (two-page ticket as two photos) clarify the file-count rule rather than padding.

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 mutation tool with no output schema, the description covers the prerequisite ordering, format/size limits, file-count ceiling, retention behavior and the return shape. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for file_base64/mime_type by enumerating accepted formats (JPG, PNG, WEBP, HEIC, PDF) and the 10 MB limit, which the schema does not express. It adds nothing further for expense_id or filename 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?

States a specific verb and resource ('attach the original receipt ... to an existing expense') and immediately scopes it against siblings by telling the agent to set amounts with create_expense / update_expense first. An agent can distinguish this from create_expense, update_expense and list_expenses without opening any schema.

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

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

Explicitly sequences usage ('enter the amounts with create_expense / update_expense first') and frames the operation as equivalent to the web app upload. It gives clear context but does not state an explicit when-not-to-use case or name a competing alternative for file storage.

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 known; the description reinforces this by framing the tool as a pure summation ('It only sums what it is given') that performs no interpretation. It does not describe the shape of the returned object beyond naming the computed boxes, which is a minor gap for a calculation 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?

Three front-loaded sentences: what it sums, what the input is with an example, what it does not do, then the sibling alternative. No filler, and the scope limitation is placed before the routing hint where it matters most.

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 calculation tool with no output schema, the description covers purpose, input format, limitations, and the alternative path. The only missing piece is what the response envelope looks like, though the enumerated formula boxes substantially telegraph the output.

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 baseline is 3, but the description adds real meaning: the values are tax amounts ('cuotas') per box rather than rates, and it supplies a concrete example object ({"09": 17430, "29": 9870}) clarifying the key format. That goes beyond the schema's accepted-box enumeration.

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

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

The description states a specific verb and resource — 'Add up the boxes (casillas) of the Spanish quarterly VAT return Modelo 303' — and enumerates the exact formula boxes (27, 45, 46, 64, 66, 87, 69, 71). It also explicitly distinguishes itself from the sibling get_modelo, so an agent can route between the two 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?

It gives both sides of the routing decision: use this tool when you have tax amounts per box already, and use get_modelo with model 303 when computing from an account's own invoices and gastos. It also sets explicit exclusions — 'it does not decide which rate or deduction applies and it is not a tax return.'

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, and the description adds useful behavioral context: reverse VAT calculation, rate-application boundary, and the returned total_factura after IRPF withholding. It does not discuss rounding or error behavior, so not 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?

Front-loaded with the purpose, then proceeds through default behavior, reverse calculation, rate boundary, and return values. Every sentence earns its place with no repetition 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?

Although there is no output schema, the description lists all returned fields and explains total_factura versus total_con_iva. Combined with the read-only annotations and complete parameter schema, it gives the agent everything needed to call 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?

Schema description coverage is 100%, so parameter meanings are already fully documented. The description restates the importe/incluye_iva relationship and adds return-field context, but adds little parameter semantics beyond the schema itself, 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 (compute) and the exact resources it calculates: taxable base, VAT, recargo de equivalencia, and IRPF withholding. The boundary that it only applies supplied rates and does not decide which rate applies distinguishes it from rate-decision or tax-form 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?

Clearly explains the default mode (importe as taxable base) and the reverse-VAT mode when incluye_iva=true. It also states a key exclusion (it does not decide applicable rates), though it does not explicitly name a sibling alternative such as calculate_modelo_303.

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 only flag destructiveHint/readOnlyHint; the description goes well beyond by explaining what actually happens downstream (RegistroAnulacion sent to AEAT, or recorded only in the local hash chain if never submitted) and the irreversible semantic effect that the invoice counts as never issued. It also discloses the return value and the mandatory confirmation gate.

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 front-loaded sentences plus a routing clause carry the irreversibility warning, the AEAT/local-chain branch, the confirmation protocol, the sibling alternative, and the return value with no 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 destructive, irreversible tool with no output schema, the description covers consequences, the AEAT branch, the confirmation prerequisite, the alternative tool, and what is returned. Nothing an agent needs before invoking it 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 67%, with confirm and reason already documented; the description still adds the procedural meaning of confirm (only after explicit user confirmation) and frames reason as the 'this was a mistake' rationale. invoice_id remains undocumented in both places, which is the only real gap.

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?

"Annul (anular) a finalized invoice" gives a precise verb plus resource and adds the governing model (Veri*factu chain, invoice counts as never issued). It is unmistakably distinct from siblings like delete_invoice and rectify_invoice, which the description names 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?

States the selection rule between this and rectify_invoice (anulación = 'this was a mistake'; rectify = later discount or correction), plus the prerequisite workflow of obtaining explicit user confirmation before calling with confirm=true. Both the when and the when-not are 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?

The readOnlyHint already establishes safety, and the description adds substantial context beyond annotations: it lists the exact categories of findings, gives the Modelo 347 threshold, clarifies that findings are questions for the user, and explicitly excludes tax-advice judgment. This is rich behavioral disclosure for a read-only check.

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 purpose and handover context are front-loaded, followed by concrete examples of what is checked and a crisp scope exclusion. The description is dense but every clause helps an agent understand what the check covers and what it does not.

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 check with no output schema, the description is nearly complete: it explains the checks and frames findings as user questions. It could say more about the shape or ordering of results, but the core behavior an agent needs to invoke it correctly is 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%, and the schema already documents year and quarter, including that omitting quarter checks the whole year. The description reinforces the quarter-or-year scope but adds no parameter syntax or format details beyond the schema, so 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 uses a specific verb and resource: check a quarter or year for missing documents and blockers before gestoría handover. It names concrete checks (recurring invoices, expenses without supplier/invoice number, drafts, Modelo 347 threshold cases) and explicitly distinguishes the tool from tax advice, making it clearly identifiable among the many invoice, expense, and gestoría siblings.

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

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

It clearly states when to use the tool: before handing a period to the gestoría. It also states an important when-not: this is not tax advice and does not judge deductibility or rates. It does not explicitly name alternative sibling tools to use for tax calculations, so it falls short of full sibling routing.

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 readOnlyHint annotation, the description explains return semantics: whether the number exists and, where published, the name behind it. It also discloses a critical failure mode: VIES downtime is reported as disponible=false, which is not the same as an invalid number.

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 front-loaded with the primary lookup action, then adds only the high-value caveats about tax conclusions and VIES availability. Every sentence earns its place and there is no 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 read-only lookup with no output schema, the description supplies the missing return semantics and the important distinction between unavailable and invalid. Together with the annotations and fully documented schema, an agent has enough information to call and interpret this 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?

Schema description coverage is 100%, so the schema already documents both the country code and number parameters, including that the country can be omitted when the number carries its prefix. The description does not add parameter-level syntax or format guidance 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?

The description states a specific verb and resource: looking up an EU VAT number in the European Commission's VIES registry. It distinguishes the scope from Spanish tax ID or VAT calculation tools by naming VIES and EU VAT 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?

It gives clear context and an important limitation: the result does not determine whether an invoice may be issued without IVA, which is the user's decision with their gestoría. It does not explicitly name sibling alternatives such as validate_spanish_tax_id or calculate_vat, so it falls short of full alternative routing.

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 only declare this is a non-read-only, non-destructive write; the description adds real context on top: the output is unfinalized, has no invoice number yet, is dated today, and the call returns the new draft's id. It stops short of stating source-invoice preconditions (e.g. whether finalized or paid invoices can be cloned).

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?

Four short, front-loaded fragments with no filler: the operation and result come first, then the usage cue, then the draft caveats, then the return value. Every sentence contributes new information.

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 one-parameter tool with no output schema, the description covers the essential outcome, the draft state, and the return value. Missing only edge-case behavior around which source invoices are eligible and how failures surface.

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 is one parameter (invoice_id) with 0% schema description coverage, so the description carries the burden. 'Clone any invoice' implies invoice_id identifies the source, but it adds nothing on validity constraints, such as whether the id must reference an existing, non-cancelled invoice.

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 (clone) and resource (invoice) plus the concrete outcome: a new DRAFT with today's dates. It implicitly separates cloning from create_invoice by saying it starts from an existing invoice, though it never names that sibling 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?

'Good for "invoice like last time"' gives a clear, concrete usage context that an agent can match against a user request. It offers no exclusions or named alternatives (e.g. create_invoice for a from-scratch invoice), which keeps it below the top score.

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 establish non-read-only and non-destructive. The description adds key behavior: output is a new draft (not finalized), source status precondition, and that id and total are returned. It does not cover duplicate conversion or whether the quote's status changes.

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?

Three compact sentences ordered as action, precondition, follow-up, and return value. Every sentence adds operational information.

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 one-parameter conversion tool with no output schema, the description covers preconditions, resulting state, next step, and key return fields. Minor gaps around duplicate prevention and source-quote mutation keep it from being 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?

With schema coverage at 0%, the description partially compensates by requiring the referenced quote to be in accepted status. However, it never names quote_id or clarifies the integer identifier format/behavior, leaving a gap.

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 (convert), source (accepted quote), and target (new draft invoice) with retained customer/items/rates. It also names the follow-up sibling finalize_invoice, making the boundary 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?

Explicitly requires the quote to be in accepted status and tells the agent to review the resulting draft before calling finalize_invoice. It does not state what to do for a non-accepted quote or when to use create_invoice instead, so it stops short of full alternative routing.

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 this is a non-destructive write, so the safety profile is covered. The description adds the return payload (id, name, NIF, email), which matters because there is no output schema, but it omits duplicate-handling behavior and any account/permission constraints for a 20-parameter mutation.

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?

Three compact sentences, front-loaded with the action and the required-field constraint, with no filler. The return-value sentence earns its place given the absent output schema.

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 20-parameter tool in a regulated Spanish invoicing domain, the description covers the basic call shape and return values but not the conditional clusters (DIR3 trio requires is_public_admin, email_cc vs no_email_cc interaction) that an agent could get wrong. Adequate, not 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?

Schema coverage is only 50% across 20 parameters, so the description should compensate more than it does. It usefully explains that nif/email/address are optional and why, but says nothing about recipient_type, dir3_*, no_email_cc, or default_product_group, which are the highest-consequence fields left to 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 and resource ('Create a new customer') and scopes it to the user's contix account, which cleanly separates it from update_customer and get_customer. It does not explicitly name a sibling or state what it does not do, so it falls short of the top band.

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

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

It clarifies the minimal viable call ('Only contact_name is required') and gives one concrete business rule (private individuals without NIF are fine), which is real usage guidance. However, it never says when to prefer this over update_customer, when to look up an existing customer first, or what happens on duplicates.

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, it discloses the critical behavioral rule that a supplier must be supplied or the expense cannot appear in Modelo 347/349. It also explains that OCR is out of scope, defines the return fields, and points to the follow-up tool for receipt attachment.

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 front-loaded with the core action and required fields, then adds supplier compliance, OCR scope, return values, and the follow-up tool. Every sentence contributes useful information without waste.

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 16 parameters, minimal annotations, and no output schema, it covers the critical requirements, supplier compliance, return values, and receipt-attachment workflow well. Some optional parameter semantics remain reliant on the schema, but the description is largely complete 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?

The description adds important meaning for the supplier fields by making them effectively mandatory and explaining why. However, with only 56% schema description coverage, it leaves several parameters such as notes, category, tax_rate, tax_amount, and invoice_number without added semantic guidance.

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

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

The description states a specific verb and resource: register an expense (gasto) from data. It clearly distinguishes creation from OCR ticket scanning and from attaching a receipt afterward, so an agent can identify the correct operation.

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

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

It explicitly says OCR ticket scanning stays in the web app and directs receipt attachment to attach_expense_receipt. It does not explicitly mention update_expense or list_expenses, but the create-vs-attach boundary 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 only declare readOnlyHint=false and destructiveHint=false, so the description carries the real behavioral burden: it states that the result is a draft, that finalization is a separate call, that duplicate external_id values are refused with a 409 rather than double-billing, and what the return values are. That is substantial context beyond the 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 front-loaded with the purpose, then moves efficiently through workflow, tax rules, idempotency, and return values. Every sentence earns its place; there is no repetition 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?

There is no output schema, but the description explains the return payload (new draft id and total, or the existing invoice id and number on a repeated external_id). It covers the critical workflow, tax, and idempotency behavior for a mutation tool. Minor gaps remain around permissions or draft editability, but they are not essential 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 coverage is 56%, and the description adds important semantics the schema does not fully supply: the supported VAT values (21, 10, 4, 0) and IRPF retention values (0, 7, 15, 19), plus line-level tax-rate override behavior. It does not explain customer_id, items, notes, referencia, numero_pedido, or product_group, though those are covered in the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Create a new draft invoice'. It immediately distinguishes the draft-creation step from the follow-up emission step by naming finalize_invoice, so an agent can tell exactly where this tool sits in the workflow.

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

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

It explicitly says to review the draft with the user and then emit it with finalize_invoice (or from the dashboard), naming the alternative and the condition that selects it. It also gives explicit retry guidance via external_id, covering the when-to-use case for that parameter.

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 only declare readOnlyHint=false and destructiveHint=false; the description adds real value beyond that by clarifying the document is non-fiscal and outside the Veri*factu chain, that acceptance happens in the dashboard rather than via this tool, and that the call returns id, number and total. It stays silent on quote numbering/series, which matters given the get_quote_series and set_quote_series siblings.

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?

Three short sentences, front-loaded with the purpose and then the lifecycle and return value. No filler, and each sentence carries distinct information (what it is, what it isn't, what comes next, what comes back).

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 mutation tool with no output schema, it does state the returned fields and the downstream path, which covers the most important unknowns. But with six parameters and near-zero schema documentation, the definition is not complete enough for an agent to populate items, tax_rate or retention_rate confidently.

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 only 17% (only valid_until is documented), so the description carries the burden of explaining five other parameters, yet it adds no parameter information at all. Nothing explains items structure, tax_rate/retention_rate defaults, notes, or customer_id expectations, leaving the agent to infer semantics from bare property names.

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 ('Create a new quote (presupuesto) for a customer') and immediately qualifies the document type as non-fiscal with no Veri*factu chain, which separates it from create_invoice and the rest of the invoicing siblings. An agent can tell what it produces and what it does not produce 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?

Gives a clear lifecycle context: create the quote here, mark it accepted in the dashboard, then call convert_quote_to_invoice to produce a DRAFT invoice, naming the sibling explicitly. What it does not state is the inverse routing rule (use create_invoice when the document must be fiscal), which is only implied by the 'non-fiscal' qualifier.

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 declare a non-read-only, non-destructive creation. The description goes well beyond that: it discloses that nothing is issued or sent at creation time, that activation triggers automatic Veri*factu finalization and emailing to the customer, and what the return payload contains. This is exactly the lifecycle context the annotations cannot convey.

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

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

Front-loaded with the core action and draft state, then the activation path, then the return value. Three sentences with no filler, though the bilingual parentheticals (factura recurrente / suscripción, borrador) add slight density without much decision value.

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 15-parameter creation tool with no output schema, the description supplies the lifecycle and activation context an agent most needs, plus the return shape (id, name, frequency, next invoice date). It stops short of explaining default behaviors for tax_rate, payment_days, and items, which an agent might otherwise assume.

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 only 47% across 15 parameters, but the schema itself describes the highest-risk ones (is_active, auto_send, auto_finalize, start_date, end_date, description, product_group). The description reinforces the draft/activation semantics of is_active and the automatic emailing implied by auto_send, but it adds little on the remaining bare parameters such as items, tax_rate, payment_days, and retention_rate.

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 (create a recurring invoice profile) and immediately disambiguates it from siblings by describing it as a saved template that generates invoices on a schedule, distinct from generate_recurring and update_recurring which are named. An agent can select this tool without opening any schema.

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

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

Explicitly says the profile is created as a draft and that to start the series the agent should confirm date/frequency with the user and then call update_recurring with is_active=true. The when-to-use and the alternative (update_recurring) are both named along with the precondition for switching.

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 destructiveHint=true annotation: it discloses that deletion is a recoverable soft delete with a 30-day window, that linked movements are never deleted and come back labeled 'protegidos', and exactly what each mode returns (preview counts vs. actual moved count plus lote id).

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?

Three dense sentences, front-loaded with the outcome and recoverability before the selection modes, then the confirmation workflow. Every clause carries operational information; only the final return-value sentence comfortably overlaps the earlier confirm explanation, costing a little tightness.

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 destructive 5-parameter tool with no output schema, the description supplies everything an agent needs: selection combinatorics, the mandatory user-confirmation loop, the protection rule, and the shape of both return variants including the lote id for restoration.

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 60% (desde/hasta/importado_el already documented), and the description adds real value on the two undocumented params: how ids works as a selection mode and the full dry-run/commit contract for confirm. The 5000-item cap on ids is left to the schema, which is acceptable.

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 precise verb+resource+outcome: 'Move imported bank movements to the trash'. It distinguishes itself from sibling deletion tools (delete_invoice, delete_expense) and from restore_bank_trash by naming the soft-delete/restore pairing.

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

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

Explicitly enumerates the three combinable selection modes (ids, desde/hasta, importado_el), then prescribes the two-step workflow: call WITHOUT confirm first, report the count to the user, and only re-call with confirm=true after agreement. It also names the recovery path (restore_bank_trash) and the exclusion rule for invoice/expense/payment-linked movements.

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 destructiveHint=true and readOnlyHint=false, so the description needn't restate that it's destructive. It adds genuine value beyond annotations: it reassures that deletion is safe because gastos are outside the invoice chain, and it discloses the return value (deleted expense's id). Missing only an explicit reversibility/no-undo note.

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?

Three short sentences, front-loaded with the action, then the key safety distinction, then the id-lookup hint. No padding; each sentence carries distinct information.

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 destructive tool with full schema coverage and annotations covering the safety profile, the description supplies everything needed: how to find the id, why deletion is safe, and what is returned. Nothing an agent needs to call it correctly is 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 coverage is 100% and the single parameter's description already says 'expense id from list_expenses', so the description's 'by id' plus the list_expenses pointer largely echoes the schema. Adequate but no added syntactic or format detail beyond what's structured.

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 ('Delete an expense by id') and then distinguishes it from the invoice-related siblings by clarifying that gastos are plain expense records not in the Verifactu invoice chain. An agent can separate this from delete_invoice/delete_bank_transactions without opening any schema.

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

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

Explicitly routes the agent to list_expenses to obtain the id, and clarifies the domain context (gastos are not invoices) that governs when this deletion is appropriate. It stops short of spelling out exclusions such as irreversibility warnings, so it's clear but not fully exhaustive.

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 destructiveHint=true, so the description's added value is the eligibility rule and the regulatory reason (the facturado chain) plus a return value. It doesn't cover error behavior (e.g. what happens if the id is a finalized invoice or does not exist), which is the remaining gap for a destructive operation.

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?

Three sentences, front-loaded with the action and scope, then the constraint and alternative, then the return value. Every sentence carries distinct information with no 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 one-parameter destructive tool, the description covers eligibility, the safe alternative, id provenance, and the return value; with no output schema, stating the return is a plus. Only failure modes for an invalid or finalized id are unaddressed.

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 already documents 'invoice id from list_invoices'. The description's 'by id' and 'use list_invoices to find the id' restate the schema rather than adding format, type, or validation detail, so 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 and resource plus a hard scope qualifier: 'Delete a DRAFT invoice by id.' The DRAFT restriction immediately separates it from cancel_invoice and rectify_invoice in the sibling set.

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?

Explicit when-to-use (drafts only) and when-not-to-use (finalized invoices in the Veri*factu chain), naming the correct alternative rectify_invoice. It also routes the agent to list_invoices for id discovery, leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true, and the description goes well beyond that by explaining the consequence in human terms: the invoice can never be edited or deleted, and corrections require a rectificative document. It also discloses the conditional AEAT submission (account-mode dependent) and what the tool returns, which annotations cannot express.

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 critical warning is front-loaded and every clause carries information, but the sentence is overstuffed and contains a stray untranslated fragment ('se envía a la cadena Veri*factu') spliced mid-thought, and it partially repeats the title's 'irreversible' warning.

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, high-stakes mutation with no output schema, the description covers everything an agent needs: preconditions, irreversibility, confirmation protocol, return values (invoice number, Veri*factu hash, AEAT status), and the remediation path.

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 only 50%, with invoice_id carrying no schema description, but the description compensates by framing the target as a DRAFT invoice, making the id's meaning inferable. For confirm it reinforces the schema constraint ('only after explicit user confirmation'), though it does not restate that confirm must be true beyond 'call with confirm=true'.

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+resource (finalize a DRAFT invoice) and then spells out the concrete effects: assigns the sequential number, computes the hash, appends to the Veri*factu chain, and optionally submits to AEAT. It also names its siblings explicitly ('use update_invoice before finalizing', mistakes require a rectificative invoice), so an agent can place it precisely among update_invoice, rectify_invoice and cancel_invoice.

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 both a when-to-use and a when-NOT-to-use: if the draft still needs changes, call update_invoice first; if a mistake was already made, use a rectificative invoice. It additionally prescribes the interaction protocol ('ask the user for explicit confirmation first, then call with confirm=true'), removing ambiguity about sequencing.

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 a non-read-only, non-destructive write, and the description adds value beyond them by disclosing the return payload (id, status, total) and the side effect on the profile's next scheduled date. It does not clarify whether this advances/skips the schedule or creates a duplicate invoice, which is the main behavioral ambiguity left.

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?

Three short sentences, front-loaded with the action, then the related sibling, then the return value. No filler or 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?

With no output schema, the description usefully documents the return shape and the scheduled-date side effect, and annotations cover the safety profile. The one gap is guidance on sourcing the profile_id, which matters for a single-required-param tool with 0% schema coverage.

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 profile_id parameter has no description, so the description carries the burden; it implies the parameter identifies an existing recurring profile but never states the expected type, nor how to obtain a valid ID (e.g. via list_recurring). Partial compensation only.

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 precise verb+resource ('Generate an invoice now from an existing recurring profile') and explicitly distinguishes it from the sibling that creates profiles ('Create profiles with create_recurring'). An agent can tell this apart from create_recurring, update_recurring and list_recurring 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?

Explains the precondition (an existing recurring profile) and points to create_recurring as the alternative for profile creation, plus 'now' signals immediate generation rather than scheduled. It never says what to do if no profile exists or how this differs from calling create_invoice directly, so no explicit when-not 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?

Annotations already indicate this is not read-only and not destructive; the description adds useful context that this is an RGPD accountability record and that it returns tenant_id. It does not cover edge cases such as idempotency or failure behavior, but it adds meaningful behavioral context beyond the 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 concise sentences with no wasted text. The core action is front-loaded, followed by the sequencing instruction for subsequent calls.

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 one-parameter tool with full schema coverage and no output schema, the description supplies the key missing context: the RGPD purpose, returned tenant_id, and header usage on later calls. Nothing essential for correct invocation appears 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 100%, and the schema already explains that link_id comes from gestoria_listar_mandantes and is not the tenant_id. The description reinforces the return of tenant_id but does not add further parameter syntax or constraints 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 states a specific action and resource: recording that a gestoría opens an accepted client and returning its tenant_id. It distinguishes the operation from listing clients by pointing to gestoria_listar_mandantes as the source of link_id and clarifying that link_id is not tenant_id.

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

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

It explicitly says when to call it: before reading a client's data, with X-Contix-Tenant used on subsequent calls. The prerequisite source for the required ID, gestoria_listar_mandantes, is also named in the schema.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so the description focuses on what annotations cannot say: the response is text plus a PDF URL, the PDF must be fetched with the same credentials (an auth note), and output is deliberately limited to technical facts with no tax assessment. That last scope caveat is genuinely useful. It does not mention failure modes for an unaccepted client or a broken chain.

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 certificate name and regulatory reference lead, followed by the enumerated payload and the return shape in a single dense sentence plus one clarifying clause. Every element earns its place; it is only slightly run-on and could be broken into two sentences for scanability.

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 compensates by describing the return: facts as text plus a PDF URL with a credential hint. For a single-parameter read tool with safety annotations already in place, this covers nearly everything an agent needs; only the behavior for a missing/unaccepted link_id is unaddressed.

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?

With 100% schema coverage, the schema already documents link_id as the id from gestoria_listar_mandantes rather than tenant_id. The description reinforces the 'one accepted client' scoping but adds no format, range, or lookup 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 artifact (Certificado de cumplimiento, RD 1007/2023) scoped to one accepted client, and enumerates exactly what it reports: producer/Declaración Responsable, NumeroInstalacion, hash chain counts, last hash, re-verification result, and AEAT submission status. That enumeration makes it distinguishable from generic siblings like gestoria_resumen_mandante, though no sibling is named 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 only implied: the reader infers this is the certificate-generation call within the gestoría flow. There is no statement of when to prefer it over gestoria_resumen_mandante or gestoria_revision_mandante, nor any prerequisite such as requiring an accepted mandate.

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 establish readOnlyHint=true and destructiveHint=false, and the description adds substantive behavior beyond that: reminders are off by default, lead-day defaults, and the specific missing-account conditions that trigger reminders. It does not cover auth requirements or response shape, but those are less critical here.

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?

Three sentences, front-loaded with the account scope and the settings returned. The content is dense but mostly earns its place; 'Read-only' overlaps the annotation slightly, keeping it just short of ideal.

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 zero-parameter, read-only getter with no output schema, the description is complete enough: it enumerates the settings, defaults, and the conditions under which reminders fire. An agent can call it without needing more structured output detail.

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 input parameters and the schema is empty, so parameter semantics are not a burden; the baseline is 4. The description's mention of defaults and template placeholders describes returned settings, not inputs.

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 exact resource: quarter-close reminder settings for a gestoría account, including who sends, lead days, and template. It is clearly a read of current settings, but it never explicitly contrasts with gestoria_cierre_configurar, so sibling differentiation is only implied by the title and 'Read-only'.

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

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

It gives context ('For a gestoría account') and marks the tool read-only, implying it is for inspecting current settings. It does not state when to use this instead of gestoria_cierre_configurar or gestoria_cierre_vista_previa, nor any 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?

Beyond the destructiveHint=true annotation, the description discloses three things annotations cannot: updates are partial (unchanged fields are preserved), saving the body constitutes the gestoría's approval of wording, and the call returns the saved settings. It does not explain why the tool is flagged destructive, which is the one open question an agent might have.

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 with an inline placeholder list, front-loaded with the account scope and the three actions. The placeholder parenthetical is long but earns its place; nothing is redundant boilerplate.

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 4-param, non-required, partial-update mutation with no output schema, the description covers scope, per-field behavior, template syntax, approval semantics and the return payload. The main omission is any note on whether prior settings are recoverable after a change.

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 only 25% (only 'dias' is documented), so the description carries real weight. It enumerates the eight supported template placeholders for asunto/cuerpo and clarifies the semantics of passing a subset of fields, adding meaning well beyond the bare 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?

Names a specific verb set (switch on/off, set days, change subject/body) on a specific resource (quarter-close reminders for a gestoría account). It is reasonably distinct from gestoria_cierre_vista_previa and gestoria_cierre_config, though it never names those siblings to draw the line 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?

"Only the fields you pass change" and "For a gestoría account" establish scope and partial-update semantics, which is real usage guidance. However, it never states when to use this instead of reading via gestoria_cierre_config or previewing via gestoria_cierre_vista_previa, so the routing decision is left implied.

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 destructiveHint=false, and the description adds meaningful confirmation: 'Sends nothing.' It also discloses what the preview contains (subject, text, what is missing, whether it would be sent at all), which is substantive behavioral context beyond the 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 compact sentences, front-loaded with the purpose and output content, then closing with the key non-sending guarantee. No wasted wording.

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?

There is no output schema, but the description explains the returned preview contents: subject, text, missing data, and send status. Combined with annotations covering safety, an agent has enough information to call it correctly for a one-client preview.

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

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

Schema coverage is 100%, so the link_id mapping to gestoria_listar_mandantes is already documented. The description adds the important qualifier that the target is 'one accepted client', giving extra meaning about which client is valid beyond the schema text.

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 preview operation for one client: the exact reminder that would be sent today, including subject, text, missing items, and send eligibility. The phrase 'Sends nothing' clearly distinguishes it from send_reminder and other mutation 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?

It establishes the context ('For a gestoría account', 'one accepted client today') and signals this is a dry-run preview. It does not explicitly name send_reminder as the alternative or state when not to use this tool, so it stops short of full routing 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description agrees with a terse 'Read-only.' Beyond that, it discloses the substance an agent actually needs: the 30% commission rule, that it accrues for as long as the client pays, and the four reporting lenses (month, year, pending, paid out) plus per-client granularity. It does not state whether it requires an authenticated gestoría role or what the currency/format of the figures is, so it falls short of full 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?

One sentence, front-loaded with the audience ('For a gestoría account') and the subject ('what it earns from contix'), with the commission model in a parenthetical. It is dense but every clause carries meaning; the trailing 'Read-only.' is small redundancy against annotations but harmless.

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, no output schema, and safety covered by annotations, the description carries the return-value burden well by enumerating the periods and per-client breakdown. It is nearly complete for a zero-argument read report; only the units/format of the amounts and any gestoría-role prerequisite are unstated.

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 schema imposes no semantic burden and the baseline is 4. The description correctly implies no input is needed, keeping the call shape unambiguous.

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 (a gestoría's earnings from contix) and specifies the exact commission model (30% of each linked client's net monthly fee) plus the breakdown windows. An agent can immediately tell this is a commission/earnings report. It stops short of naming or contrasting any sibling such as gestoria_resumen_mandante, which is the closest alternative.

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

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

Usage is only implied by the qualifier 'For a gestoría account', which signals the prerequisite context but not when to pick this over related gestoría reporting tools. There is no explicit when/when-not, no mention of prerequisites like an active mandante mandate, and no alternative 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 cover the read-only profile, and the description adds genuine context beyond that: the result is a URL rather than the file itself, the archive is one ZIP with per-client folders, and the download requires the same credentials. It does not mention expiry, size limits, or latency, which would matter for a bulk export.

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 sentences, no filler, with the core return value front-loaded and the credential note placed last where it belongs. Every clause carries information an agent would otherwise have to guess.

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 correctly explains what comes back (a URL to a single ZIP with a folder per client). The 'accepted client' qualifier is unexplained, but for a 2-parameter read-only tool the remaining gaps are minor.

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 50%: quarter is documented in the schema, year is not. The phrase 'for a year or year+quarter' clarifies the relationship between the two parameters (quarter narrows the range, omission means full year), which is modest added value over the schema. Baseline 3 is appropriate given partial coverage.

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 (return the download URL) and resource (a single ZIP containing every accepted client's export), and enumerates contents (invoices, expenses, libros, modelos). This clearly separates it from per-client siblings like gestoria_facturas_mandante or get_libros_registro, though it never names them 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 through the year / year+quarter framing and the note to download with the same credentials, which is useful auth context. It does not say when to prefer this bulk export over the per-mandante or per-documento tools, nor any prerequisites (e.g. what 'accepted' requires).

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 destructiveHint=false, so 'Read-only' repeats structured data. However, the description adds real value beyond annotations: the 'newest first' ordering and the exact return-field list (number, date, customer, base, IVA, total, status, Veri*factu flag), which is important since no output schema exists.

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 audience/scope front-loaded before the colon-delimited field list. The enumeration is slightly long, but it is warranted because no output schema exists to describe return values.

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 list tool with no output schema, the description covers scope, ordering and returned fields adequately. Remaining gaps are minor: the meaning of 'accepted' client status and the default/max limit behavior (the latter is in the schema).

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

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

Schema coverage is 75% and already documents link_id, quarter and limit. The description adds meaning the schema does not: 'accepted' status qualifies which link_id is valid, and 'one client in a year or quarter' clarifies the mutually exclusive period filtering. The undocumented 'year' parameter is only implicitly covered by the phrase 'in a year'.

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 (invoices) with tight scope: 'ONE accepted client in a year or quarter', plus the exact fields returned. An agent can distinguish it from the general list_invoices by the 'gestoría account' framing and the single-client constraint, though no sibling is named 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?

The 'For a gestoría account' opener implies the applicable context, and 'ONE accepted client' implies usage after gestoria_listar_mandantes. But there is no explicit when-to-use/when-not guidance versus list_invoices or gestoria_gastos_mandante, leaving the choice to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Read-only' is consistent with them. Beyond that it adds real context: sort order (newest first), the exact fields returned including supplier NIF, IVA and the receipt-attached flag, and the single-client scoping. It omits pagination/row-cap behavior, which lives only in the 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?

One front-loaded sentence: audience/account type first, then scope, then ordering, then returned fields. The field enumeration is long but earns its place because there is no output schema.

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 compensates by enumerating returned fields, which is exactly what an agent needs to decide to call it. The remaining gap is row-limit/pagination behavior and whether quarter requires year, both left entirely to the schema.

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

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

Schema coverage is 75% and already documents link_id provenance and the quarter range, so the baseline is met. The description adds the period semantics ('in a year or quarter') and stresses 'ONE accepted client', reinforcing that link_id is a per-client identifier rather than a tenant scope.

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 the resource (expenses/gastos) and immediately narrows the scope: a gestoría account, ONE accepted client, a year or quarter, newest first. The 'For a gestoría account' and 'ONE accepted client' framing cleanly separates it from list_expenses (own account) and gestoria_facturas_mandante (invoices) without 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?

'For a gestoría account' and 'ONE accepted client' tell the agent the precondition and the scope constraint that rules out the general list_expenses tool. It does not explicitly name an alternative tool or say when-not to call it, but the account-type gating is a clear, usable condition.

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 only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context: the client must accept before the gestoría can read anything, and the response is deliberately generic regardless of account existence (anti-enumeration). It does not mention rate limits or error behavior, but it substantially exceeds what the 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?

Three short sentences, front-loaded with the action, then the branch behavior, then the consent requirement and return semantics. No sentence is 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?

No output schema, and the description covers the return value (generic confirmation text) plus the key consent gate, which is enough to call it correctly. Edge cases like duplicate pending invitations or error responses are unaddressed.

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%, but the single parameter is fully implied by 'Invite a client (by email)' — the description confirms the parameter is an email address. No format, validation, or normalization detail (e.g. case handling) is added, so it is adequate but minimal for a one-param tool.

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?

Specific verb (Invite) plus resource (a client / gestoría mandante) and the mechanism (by email, to link their contix account to this gestoría). The direction of the invitation is explicit, which distinguishes it from the reverse-direction sibling invite_gestoria.

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 lays out the two branches (existing account → confirmation link, new email → registration link) and the precondition that the client must accept. It does not explicitly name alternatives such as gestoria_abrir_mandante or invite_gestoria, leaving some sibling routing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the non-obvious failure mode for non-gestoría accounts and discloses that the result is composite (clients + quarterly invoices + pending balance + last invoice date), which goes beyond the structured fields.

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 dense sentence plus a short failure clause, with the gestoría precondition front-loaded. Each clause carries distinct information: scope, statuses, returned metrics, and error condition.

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 must describe returns, and it does: client statuses and per-accepted-client quarterly invoices, pending balance and last invoice date. Combined with the declared failure mode, an agent has enough to call it 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 tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly implies the account context comes from the session rather than arguments.

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 (list) and resource (linked clients of a gestoría account) plus the statuses returned. It implicitly differs from gestoria_resumen_mandante by covering all linked clients rather than one, though it doesn't name that sibling 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?

"For an account in gestoría mode (is_gestoria)" gives a clear precondition for use, and "Fails if this account is not a gestoría" states the when-not case. No alternative tool is named, so an agent must infer that this is the multi-client overview rather than the per-mandante 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?

Annotations already cover readOnly/non-destructive, and the description adds real context beyond them: output is aggregates only, scoped to a single accepted client, and returns only blocking points/warnings rather than advice. It does not mention what happens if the client is not accepted or if the period has no data, but the behavioural profile is well disclosed.

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 account type and subject ('For a gestoría account: the figures of ONE accepted client'), then lists the returned figures, then the scope caveat. Dense but every clause carries signal; slightly long as a single run-on enumeration.

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?

There is no output schema, so the description shoulders the return-value burden and does it well by naming the invoice, expense and revision aggregates in order. Remaining gaps (behaviour for a non-accepted client, empty periods) are minor for a read-only aggregation 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% and both year and quarter already carry descriptions, so baseline 3 applies. The description reinforces the period semantics ('a year or a quarter') and implies link_id identifies the client rather than the tenant, but adds no new format or default information.

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-resource pair ('the figures of ONE accepted client for a year or a quarter') and enumerates exactly which figures: invoice counts, net base, IVA repercutido, IRPF, totals, drafts, expenses with IVA soportado, blocking points and warnings. This cleanly separates it from siblings like gestoria_facturas_mandante (line-level invoices) or gestoria_revision_mandante (the revision itself) — it is the aggregate roll-up.

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?

Implies usage through context ('For a gestoría account', 'ONE accepted client') and the scope fence 'Sums and counts only, never an opinion on what to declare or deduct'. It never explicitly says when to prefer this over gestoria_revision_mandante or gestoria_gastos_mandante for the same client/period, so routing still needs inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the important behavioral framing that output items are questions to put to the client rather than tax assessments or instructions, which directly governs how the agent should relay results. It does not mention result size, whether an empty set is normal, or cost/latency 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?

Scope and purpose lead; the enumeration, though long, earns its place by defining exactly which gaps qualify; the closing sentence is a compact presentation rule. No filler or repetition of annotation fields.

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 only three parameters and no output schema, the description does the heavier lifting well by characterizing the result as per-point client questions and by pinning down period/client scope. It could still be clearer about result shape (grouping, counts, empty-result meaning) for an agent composing a response.

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 67%: link_id and quarter are documented in the schema (including the omit-for-whole-year rule), and the description reinforces cardinality by saying 'ONE accepted client'. The undescribed `year` parameter gets no help from the description, and no format or default guidance is added 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?

States a concrete analytical task ('what is missing or does not add up formally') scoped to 'ONE accepted client's period' and then enumerates the exact finding types (expenses without receipt, draft invoices, suppliers without NIF above the 347 threshold, missing Veri*factu records, absent recurring receipts). An agent can tell this apart from gestoria_resumen_mandante or gestoria_export 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?

Sets clear preconditions — a gestoría account, one accepted client, a period — and ties itself to the same source as REVISION.txt and quarter-close reminders, which tells the agent when this fits (pre-close review). It stops short of explicitly naming a sibling to use instead for a multi-client or summary view.

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?

readOnlyHint=true is consistent with a pure read tool. Beyond the annotation, the description discloses the return shape in useful detail — aggregated totals plus per-invoice paid and outstanding amounts — which matters because there is no output schema. It does not state whether cancelled/draft invoices are included in the totals, which for a financial statement is the one thing left uncovered.

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

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

Front-loaded with the payload (totals + invoice list), then the optional period constraint, then two short clarifiers. Four sentences, no filler; "Pure facts, no advice" is slightly meta but cheaply prevents the agent from expecting advisory 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?

For a read-only, 3-parameter tool with no output schema, the return contents are described adequately. However, key inclusion rules that determine whether the numbers can be trusted (draft/cancelled/rectified invoices, currency, date basis for 'collected') are absent, which is a meaningful gap for a statement tool used near reconciliation tasks.

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 documents desde/hasta format (YYYY-MM-DD, inclusive, omit for whole history) at 67% coverage. The description adds meaning beyond that by clarifying the period filters on issue date specifically rather than payment date — a real semantic distinction — and that leaving it out yields the full history. customer_id remains undocumented in both places.

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 resource (customer account statement) and enumerates exactly what it returns: total invoiced, collected, outstanding balance plus the invoice list, with per-line paid/outstanding. This separates it functionally from plain get_invoice/list_invoices (aggregate roll-up per customer), though it never names a sibling to route against.

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?

"Optionally limited to a period by issue date" and "Pure facts, no advice" imply the usage context (period-scoped reconciliation view, no recommendations), but there is no explicit when-to-use-this-vs list_invoices/get_customer guidance and no stated prerequisites such as whether the customer must exist or have finalized invoices.

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, so the safety profile is covered. The description adds some useful context by naming returned data (NIF, contact, address), but it does not describe not-found behavior or other operational details, leaving it only moderately transparent.

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 states the action, scope, and returned fields efficiently.

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 and annotations cover its read-only nature, but there is no output schema. The description only partially describes the return payload (NIF, contact, address) and omits error/not-found behavior, so it is adequate but not 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?

Schema description coverage is 0%, so the description must clarify the single customer_id parameter. It only says "by id" and does not specify whether this is an internal integer ID, whether NIF can be used, or any format expectations beyond the schema's integer type.

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 ("Get") and resource ("customer") and scopes it to one record by id. The phrase "one customer ... by id" naturally distinguishes it from the sibling list_customers tool.

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: retrieve a single customer when an id is known. However, it does not explicitly say when to use this instead of list_customers or other customer-related siblings, nor does it mention prerequisites or exclusions.

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 destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: by default it returns a stored (potentially stale) status, and refresh=true performs a live round-trip to FACe. What it does not mention is failure behavior when FACe is unreachable or the invoice has no FACe record.

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 first front-loads the resource and its value set, the second carries the one behavioral switch. Nothing is repeated from the schema or 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?

With no output schema, the description compensates well by enumerating the returned status values and noting that cancellation-request state is included. The remaining gap is the identity/format of invoice_id and what happens on FACe lookup failure.

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 50%: refresh is documented in the schema, invoice_id is not. The description fully explains refresh's live-vs-stored semantics and default, which is useful, but invoice_id — whether it is the internal invoice ID or a FACe registry number — is left undocumented in both places.

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 scope: the FACe processing status of an invoice, and enumerates the six possible states. The FACe/B2G framing separates it from generic invoice readers like get_invoice, though no sibling is named 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 purpose (check FACe submission/cancellation state), and the description does explain when to set refresh=true versus leaving it false. It never says when to prefer this over get_invoice or what to do if the invoice was never submitted to FACe.

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, so safety is covered; the description adds genuine value by disclosing that the payload includes line items and a Veri*factu hash, which tells the agent what data it gets back. It does not cover behavior for a missing/invalid invoice_id or any auth constraints, which keeps it below 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?

One front-loaded sentence that identifies the resource and enumerates the notable returned fields with no filler. It is appropriately sized, though it spends its space on return contents rather than the parameter that an agent must supply.

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 usefully names the key return contents, and readOnlyHint covers safety. But for a lookup tool whose only parameter is undocumented, the description should at minimum explain what invoice_id is expected to be and possibly the error behavior for unknown IDs.

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 invoice_id, an untyped-meaning integer with no explanation. The description mentions no parameter at all, so it fails to clarify whether this is an internal ID or the visible invoice number — a real ambiguity given the presence of get_invoice_display and series tools.

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 ('Get full details of a single invoice') with the scope made concrete by naming the returned content (line items, Veri*factu hash). It implicitly separates itself from list_invoices by saying 'single invoice', but never distinguishes itself from the other invoice-detail siblings such as get_invoice_display or get_invoice_facturae.

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 single-invoice read versus list_invoices, but there is no explicit when-to-use, no mention of alternatives like get_invoice_display/get_invoice_facturae, and no stated prerequisites (e.g. whether the invoice must exist or be finalized).

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 readOnlyHint=true already covering the safety profile, the description adds real value by declaring precedence: 'A customer's own saved values override these on their invoices.' That prevents misreading the result as the effective values for a specific customer. It does not mention tenant/auth scoping beyond 'tenant', but that is minor.

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 sentences, front-loaded with the returned content. The parenthetical Spanish synonyms (plazo de pago / días de vencimiento, tipo de IVA por defecto) add domain vocabulary useful for Spanish-invoicing users but slightly clutter the 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?

There is no output schema, so the description carries the burden of describing return values, and it names three concrete fields plus the override rule. It may still be missing other defaults the endpoint returns (e.g. series or footer defaults), which keeps it short of a 5.

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. The description correctly implies a single-tenant read with no filtering options, matching the empty 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 and resource ('Get the tenant defaults a new invoice starts with') and enumerates the exact contents: payment term in days, IVA rate, and retención visibility. This scope ('tenant defaults for a new invoice') cleanly separates it from get_invoice, get_invoice_display and get_invoice_footer.

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 it should call this before create_invoice to learn tenant defaults. There is no explicit 'use set_invoice_defaults to change these' pointer and no statement of when this is unnecessary, so the routing guidance is left to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the severity bar is lower. The description adds useful substance by listing which settings exist and the allowed iva_display values (ninguno | auto | porcentaje | porcentaje_cuota | porcentaje_total), but it never explicitly says it returns the currently configured values or whether unset values have defaults.

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?

It is a single sentence with no filler, but it opens with a descriptive clause and a colon instead of leading with the action, and the parenthetical list of field names makes it dense and hard to scan. Front-loading 'Returns current invoice PDF display settings:' would improve it materially.

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 carries the return-shape burden; it does enumerate the fields (iva_display, show_contix_badge, header_phone, header_whatsapp), which largely covers the response. What is missing is the retrieval framing — that these are the current stored values — and any hint about default behavior when options have not been set.

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?

With zero parameters, the baseline is 4. The description goes beyond that by documenting the enum domain of iva_display, which is a setting value the agent will encounter in the response rather than 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?

The description names the resource (invoice display options) and enumerates the exact settings involved, but it is phrased as a definition of what display options are ('How invoice PDFs are printed: ...') rather than as an action the tool performs. An agent can infer it retrieves settings, especially alongside sibling set_invoice_display, but the verb is never stated.

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?

There is no guidance on when to call this versus related tools. The clear counterpart set_invoice_display and related readers like get_invoice_defaults and get_invoice_footer are never referenced, so the agent must infer that this is the read side of the pair.

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 readOnlyHint=false mutation semantics by disclosing that the XML is UNSIGNED and therefore not submittable on its own, that FACe requires a XAdES-signed .xsig even via web form, and how the tool behaves when DIR3 data is missing ('the tool explains exactly what to add'). That is exactly the 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?

Four tight sentences, front-loaded with what is returned, then the signature caveat, then the alternative tool, then the precondition. No repetition of the name or title, no 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?

With one parameter and no output schema, the description covers what is returned, its validity limits, the applicable alternative, and failure behavior — enough to call correctly. A minor gap is that it does not say whether the invoice must first be finalized via finalize_invoice, only that it is 'a finalized invoice'.

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 invoice_id has no type description in the schema. The description implies the id must refer to a finalized invoice, which adds useful meaning, but it does not clarify whether non-finalized or non-B2G invoices error out or return partial data.

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 with version precision: 'Return the Facturae 3.2.1 XML of a finalized invoice'. It distinguishes itself from nearby siblings like get_invoice and get_invoice_display by naming the exact artifact returned and the B2G/FACe scope.

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

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

Explicitly scopes use to previewing and validating, and names the alternative: 'to actually file the invoice use submit_invoice_to_face, which signs it first'. It also states the prerequisite (customer marked as public administration with three DIR3 codes) that determines whether the call can succeed.

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?

readOnlyHint=true already covers the safety profile, and the description adds genuine context beyond it: the footer is page-level, what kinds of data it contains, and the exact return shape (a column layout summary followed by raw footer text). It does not say what is returned when no footer has been configured, which keeps it short of 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?

Two compact sentences with zero filler; the what-it-is statement is front-loaded and the return format follows. The Spanish aliases add lookup value at negligible 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, no output schema, and a readOnly annotation, the description carries the right information — what the footer is and roughly what comes back. Only the empty/unconfigured case and whether the footer is tenant-wide or per-invoice is unaddressed.

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 no parameters, so there is no parameter semantics to explain; the baseline for a zero-param tool applies. The description correctly implies no scoping input is needed.

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 ('Get the footer text printed at the bottom of every invoice page') and enumerates the content returned (bank details, contact, registry data), which unambiguously separates it from the sibling set_invoice_footer. An agent knows exactly what this returns without opening anything else.

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 read/write pairing with set_invoice_footer, but the description never says when to call this versus sibling getters like get_invoice_defaults or get_invoice_display. No exclusions or prerequisites are stated, so the agent must infer the context.

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, so the safety profile is covered. The description adds genuinely useful context beyond annotations: it discloses the four returned signals including whether the start number remains editable this year, which touches on a mutation boundary the agent otherwise wouldn't know about. Return format/shape is not detailed, 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?

A single, front-loaded sentence with zero filler. The parentheticals earn their place by mapping the Spanish billing terminology an agent may encounter in this domain.

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 carries the burden of explaining returns and does so by naming the relevant fields and the changeability flag. It is complete enough to call, though it doesn't state the exact response structure or what happens if no series exists yet.

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?

Zero parameters, so the baseline is 4. The description correctly focuses on return semantics rather than inventing parameters, and the Spanish synonyms ('serie de facturación / numeración', 'prefijo') clarify domain vocabulary.

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 ('Get') and resource ('invoice numbering series') and enumerates what the caller receives: prefix, year, next invoice number, and mutability of the start number. It is clearly distinguishable from get_quote_series and set_invoice_series by the 'invoice'/'current' framing, though it never names 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?

The intent to read the current series before creating or configuring invoices is implied but never stated, and no alternatives are named (get_invoice_defaults, set_invoice_series). An agent can infer usage but receives no explicit when/when-not 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?

Read-only safety is already covered by readOnlyHint, but the description adds meaningful behavior: only finalized issued invoices are included, received invoices are broken out by VAT rate, and output rows include base, VAT, IRPF/deductible quota, total, and period sums. It does not discuss pagination or auth, but for a simple report it discloses the important semantics.

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 front-loaded and dense with useful information, with no filler. It moves from what the report is to what each row contains to how it relates to the gestoría export and its non-advice nature.

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 does a good job explaining the return shape and line granularity. It is nearly complete for a two-parameter read-only report, though it could be more explicit about the year parameter and whether all received invoices are included.

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 50%: quarter is documented in the schema, while year is not. The description reinforces that the report covers a quarter or year, but it does not add year format/range details or explain requiredness beyond what the schema already shows.

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 resource and scope: libro registro of issued and received invoices for a quarter or year, with one line per invoice and VAT rate. It also distinguishes this listing from export/advice behavior by saying it contains the same rows as the gestoría export and is a pure listing with no advice.

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 scope ('for a quarter or year') and by 'Pure listing, no advice,' but the description does not explicitly say when to use this instead of siblings such as list_invoices or gestoria_export. It gives context without clear alternatives or exclusions.

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 the description adds substantive context beyond that: the calculation is derived from existing invoices and gastos, and modelo 202 assumes pagos_anteriores=0, so the figure is a raw base not a final payable amount. That caveat is exactly the kind of behavioral disclosure 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?

Front-loaded with purpose and the supported modelos, then caveat, return format, and the sibling alternative. Dense but every clause carries information; the modelo 202 warning is slightly long but genuinely necessary for correct interpretation of the 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?

No output schema exists, but the description explains the return shape (full AEAT breakdown of casillas as JSON). Period semantics are covered, though it doesn't state what happens if the period is omitted for a modelo that requires one.

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 compensate, and it does for the tricky parameters: it maps quarter to 303/130/349 and periodo to 202, and the model enum values are all named in prose. Only 'year' is left unstated, though its meaning is self-evident.

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+resource ('Get an AEAT tax model summary') and enumerates exactly which modelos are supported (303, 390, 130, 347, 349, 202). It also distinguishes itself from the sibling calculate_modelo_303 by naming it 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?

Gives explicit routing: use this tool for the full AEAT breakdown, and use calculate_modelo_303 instead if you only need to sum casillas by hand without querying the account. It also specifies which period parameter applies to which modelo (quarter for 303/130/349, periodo for 202).

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

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

Annotations already declare readOnlyHint and openWorldHint=false, so the description focuses on what the annotations cannot say: which legal sources are used, that the e-invoicing dates are provisional while the ministerial order is a draft, and that a null date is a possible outcome. That provisionality/uncertainty disclosure is genuinely useful context a caller could not derive from structured fields.

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 compact paragraph that front-loads the subject (deadlines from published Spanish rules), then sources, then the return shape. It is dense with legal citations but every clause (regulation IDs, provisional status, null return, obligation keys) carries information an agent needs.

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 correctly compensates by describing the return: a date or null plus explanatory text, keyed by obligation name (verifactu, factura_electronica, estados_facturas). The one gap is that it never says which inputs trigger estados_facturas ('where it applies' is left ambiguous), though the schema hints at it via mas_8_millones.

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%, including an explanation of the forma enum and the mas_8_millones turnover threshold, so the schema carries parameter meaning fully. The description adds nothing about how forma / mas_8_millones / factura_a_empresas change which obligations are returned — baseline 3 is the right level.

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 (returns deadlines) and a specific, narrowly-scoped resource (Spanish Veri*factu and B2B e-invoicing obligations), citing the governing regulations. No sibling tool overlaps with this lookup, and the description makes that uniqueness obvious.

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 answers 'when do I have to comply with Veri*factu / e-invoicing'. There is no explicit statement of when to call it versus e.g. get_modelo or calculate_modelo_303, and no prerequisites mentioned beyond the schema. The scope caveat 'Information about the rules, not advice' is the only boundary drawn.

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, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the data is non-fiscal ('contix does not derive anything fiscal from it') and the return shape is a comma-separated list of names, which tells the agent not to expect structured objects or ids.

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?

Three short sentences, front-loaded with the verb and resource, then the domain definition, then the return format. The Spanish parenthetical earns its place given the tool's locale, though the 'Pure data / no fiscal derivation' clause is slightly defensive verbosity.

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 zero-parameter read tool with no output schema, the description supplies the one thing missing from structured data: what the returned names look like (comma separated) and what the concept means. Only the absence of guidance on the write-side sibling keeps it from a 5.

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; baseline 4 applies. The description correctly implies no filtering or pagination options exist.

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 ('List the account's product groups') and then defines the domain concept (an optional axis 'what was sold' that an invoice can carry) plus the Spanish term, which is the actual field name in the product. An agent knows exactly what this returns and how it differs from the mutating sibling set_product_groups.

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 verb — read the current catalogue of product groups — but there is no explicit routing such as 'to change them, use set_product_groups' or a note on when an agent should consult this list before creating an invoice. Adequate, not instructive.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful context by disclosing the returned quote-number format and the configured start number, but it does not describe side effects, permissions, or whether it reflects unsaved settings.

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 that states the return content without filler. Every element earns its place and 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 no parameters, no output schema, and a readOnly annotation, the description provides the key return values an agent needs. It could be slightly more complete by clarifying whether the result is purely a preview or tied to the current series configuration, but it is adequate for a simple getter.

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 parameter semantics are inherently simple and the baseline is 4. The description appropriately avoids spending words on non-existent inputs.

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 resource and result: the next quote number in P-YYYY-NNNN format plus the configured start number. It is specific about what is returned, though it does not explicitly differentiate itself from siblings such as set_quote_series or get_invoice_series.

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?

There is no guidance on when to use this tool versus alternatives like set_quote_series or get_invoice_series. The read-only preview nature is implied only by the output described, not by explicit usage conditions or exclusions.

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 only declare readOnlyHint=true, so the description adds real value by disclosing the return contents (link, signup count, converted-customer count) and the reward mechanics the agent may need to explain. It does not mention auth or rate limits, but for a read-only account lookup those are minor.

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?

Three sentences, front-loaded with the core action and followed by reward details and the usage cue. The 60-days/12 € specifics are slightly promotional but plausibly useful for answering the user's referral question, 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?

With no parameters and no output schema, the description carries the burden of describing the return value, and it does so concretely (link plus two counts). An agent has everything needed to call and interpret 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?

Zero parameters, so the baseline is 4. The description correctly implies the tool is scoped to the caller's own account ('the account's personal referral link'), which is the only semantic question a parameterless tool raises.

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 ('Get the account's personal referral link for contix') and immediately clarifies the payload includes signup and conversion counts. No sibling tool covers referrals, so there is no ambiguity to resolve.

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

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

Explicitly names the trigger: 'Use it when the user asks how to recommend contix or about the referral programme.' No when-not guidance is given, but there is no plausible competing tool among the siblings, so the context is sufficient.

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, so safety is covered; the description adds the actual payload semantics (trial days remaining, next billing date) and a self-throttling rule for proactive calls. It stops short of mentioning auth requirements or caching/staleness of billing data, which keeps 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?

Two sentences, both load-bearing: the first defines the output, the second defines the trigger. The bilingual gloss ('período de prueba') plausibly aids matching Spanish-language user phrasing rather than padding.

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?

A zero-parameter read tool with no output schema, fully covered: the description explains what comes back (status values, days remaining, billing date) and when to call it. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the schema is trivially complete. Baseline 4 applies; no additional parameter guidance is owed.

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?

A specific verb and resource ('Get the account's subscription status') followed by an explicit enumeration of the returned states (trial, active, past_due, canceled). No sibling tool covers subscription/billing status, and the description makes that scope unmistakable.

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?

States two concrete triggers: when the user asks about their plan, trial or billing, and proactively once per session if unsure about payment proximity. The 'once during a session' qualifier is an explicit usage constraint that prevents over-calling.

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 substantial behavior beyond the annotations: access is read-only until the account grants more in Ajustes, the recipient's flow differs depending on whether it already has a contix account, and the same generic reply is returned in all cases by design for privacy. This privacy-preserving return contract is exactly the kind of thing an agent cannot infer from the 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?

Front-loads purpose and access level, then explains the two recipient paths and the generic reply. Dense and nearly waste-free, though the final sentence partly restates the 'same generic reply' point already made.

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 one-parameter mutation with no output schema, the description covers the access granted, the recipient-side flow, the privacy-motivated return value, and the account scope. Nothing an agent needs to invoke it correctly is missing.

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

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

Only one parameter (email) with 0% schema description coverage. The description confirms the invite is sent 'by email' and discusses what happens based on account existence, but adds no format, validation, or constraint details for the email value 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 and resource ('Invite the accounting firm (gestoría) ... by email') and what the invite grants (read-only visibility and export of invoices/expenses). It scopes itself with 'Only for the own account', which helps distinguish it from the gestoria_*_mandante siblings, though it never names 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?

Gives clear context: invite the firm that keeps this account's books, and explicitly restricts to the own account, implying the mandante sibling is for other cases. It doesn't explicitly name the alternative tool or state when not to use it beyond that scoping sentence.

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 only declare readOnlyHint=true; the description adds the meaningful behavioral detail that results are aggregated to one row per import day with a movement count and date range, which is not in the annotations and there is no output schema to carry it. It omits ordering/pagination and how far back imports are retained.

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: the data shape is front-loaded, then the intended use case. Every clause earns its place and nothing is repeated from the annotations or schema.

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 zero-parameter read tool with no output schema, the description covers what the rows represent and how to apply them, which is close to sufficient. Missing only minor operational context such as ordering or the scope of history returned.

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; baseline 4 applies. The description correctly adds no parameter chatter.

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 (bank statement imports of this account) and the exact result granularity (one row per import day, with movement count and date range), which lets an agent distinguish it from sibling bank tools like list_bank_trash or delete_bank_transactions. It never names a sibling to contrast with, 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?

"Use it to offer the user 'delete what I imported on <day>'" gives a concrete workflow context, implicitly routing to the delete counterpart. It does not state exclusions or name the alternative tools (e.g. list_bank_trash for already-deleted items), so routing is implied 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?

readOnlyHint=true already tells the agent this is a safe read, and the description adds real value beyond that: it discloses result granularity (one row per deletion lote, not per movement) and that each row carries a count and a purge date. That return-shape information is meaningful since there is no output schema. It omits whether anything is filtered or capped.

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 no filler, front-loading the resource ('Deleted bank movements still recoverable') before the row-shape detail. Every clause carries information the schema and annotations do not.

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 zero-parameter read tool with no output schema, the description covers what is listed, the level of aggregation, and one key field (purge date) — enough to call it correctly. It stops short of describing whether results are grouped, paginated, or bounded, which would complete the picture.

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 of 4 applies. The description makes no parameter claims and needs none, and the empty schema is self-evident.

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 precisely what the resource is: deleted bank movements that are still recoverable, with one row per deletion batch (lote). Combined with the tool name, an agent knows this is a trash-listing read. It does not explicitly contrast itself with restore_bank_trash or delete_bank_transactions, so sibling differentiation is only implicit.

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 phrase 'still recoverable' implies this is the discovery step before calling restore_bank_trash, but no explicit when/when-not guidance or named alternative is given. Usage is inferable rather than stated.

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, so the safety profile is covered; the description adds genuinely new behavior: the matching fields for `query` and the fact that `nif` narrows the result to a single customer. It does not mention pagination beyond the `limit` default or result ordering, which keeps 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?

Three short sentences, each carrying distinct information (scope, filters, return shape), with the account scope front-loaded. No filler or 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?

With no output schema, the description usefully states the return shape ('one line per customer: id, name and NIF'). For a read-only list tool that is close to sufficient; only pagination/limit behavior and the total-vs-truncated result question remain unaddressed.

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 67% and the description fills the largest gap: the schema only says 'Search term (optional)', while the description specifies that `query` matches company_name, contact_name, or NIF. `nif` semantics are largely redundant with the schema, and `limit` (default 20, max 100) is never mentioned in the description.

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 ('List customers in the user's contix account') and clarifies the two filtering modes. It never names `get_customer` as the alternative for single-record lookup, so sibling differentiation is only partial.

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 the two optional filters (`query` for fuzzy matching, `nif` for an exact single match), which implicitly tells the agent when to use which. It gives no explicit guidance on when to prefer `get_customer` or `create_customer`, and never states that a bare call returns all customers up to `limit`.

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 readOnlyHint=true already declared, the description adds useful behavioral context by listing the exact fields returned, including the receipt-attached flag and the meaning of 'SIN JUSTIFICANTE = no file'. It does not describe pagination or ordering, but the schema's limit bounds partially cover that and the tool has no output schema, making the field disclosure especially valuable.

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?

Three dense but well-structured sentences: first the resource and returned fields, then query semantics with an example use case, then the alternative tool for attachment. Every sentence adds information without repetition, and the key scope is front-loaded.

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 covers what the tool returns, which is critical because there is no output schema, and it fully explains the only under-documented parameter (query). It also names the relevant sibling for the adjacent attach action, leaving no major gaps for an agent to call it 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 query parameter's schema description is minimal ('free text, e.g. supplier invoice number or supplier name'), while the tool description significantly expands its meaning to search across description, invoice number, notes, supplier name/NIF, and amount. The limit parameter is fully specified in the schema with default and min/max, so no additional description is needed.

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

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

The description states a specific verb and resource (list expenses/gastos) and immediately enumerates the returned fields (date, description, supplier, total, category, receipt attached), which clearly distinguishes it from mutation siblings such as create_expense or update_expense. It also explicitly routes receipt attachment to attach_expense_receipt, making the scope unambiguous.

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

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

It gives a concrete use case ('e.g. to check whether a supplier invoice is already booked') and names the alternative tool for a related but different action ('To attach the receipt file to an expense use attach_expense_receipt'). It does not explicitly say when not to use it (e.g., for invoices use list_invoices), but the main boundary 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?

With readOnlyHint already declared, the description adds real context: result ordering ("Recent first") and the exact per-invoice projection (id, number or "Borrador" for a draft, date, total, status). It does not say whether results are capped by the limit parameter or truncated, which is the one behavioral gap that matters for a list 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?

Dense but front-loaded: purpose, then filters, then ordering, then return shape, then the sibling redirect. No filler sentences and every clause carries information an agent needs.

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?

There is no output schema, yet the description fully specifies the return shape at line granularity, so the agent knows what it will receive. Combined with ordering and filter semantics, nothing essential for a correct call 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 only 25%, so the description must compensate, and it largely does: it enumerates status filters, explains that query searches not just number/reference/notes/customer but also line descriptions (a real behavior the schema does not convey), and implies year filtering. It omits the limit parameter entirely (default 20, max 100), leaving one of four params undocumented.

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 ("List invoices") plus the scoping domain ("for the user's contix account"), and explicitly contrasts with the sibling get_invoice. An agent can distinguish this list/search tool from the single-invoice fetch without opening either schema.

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

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

Explicitly routes the agent to get_invoice when full line items or the Veri*factu hash are needed, which is the main ambiguity for a invoices listing. However there is no guidance on when to prefer list_invoices vs. other listing tools (list_quotes, list_expenses) and no mention of limits/pagination strategy.

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, so the safety profile is covered. The description adds substantive context beyond that: ordering (oldest first), the relationship to amount_paid, the imported-invoice empty case, and the return field set. It doesn't cover error behavior for an unknown invoice_id, keeping it at 4.

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

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

Front-loaded with the core definition, then the disambiguating note about amount_paid, then the empty case and return shape. Every sentence carries information; the amount_paid sentence is slightly convoluted but earns its place as a disambiguator.

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 does the right work by enumerating the returned fields and ordering, plus the imported-invoice edge case. It lacks any statement on error handling or volume/limits, which is a modest gap for a single-param read.

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% with one required integer invoice_id, so the description must carry the load. It only implies the parameter ("one invoice") and never says where the id comes from (e.g. list_invoices or get_invoice) or what happens with an invalid id, so it adds minimal meaning over the bare 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 resource — the individual payments recorded against one invoice — and its scope/ordering, which implicitly separates it from get_invoice (which gives the aggregate) and record_payment (which writes one). An agent can tell exactly what it gets back 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?

Gives a clear context for use (you want the breakdown behind amount_paid) and a valuable exclusion: imported invoices have no payment history. It does not name a sibling alternative such as get_invoice, so it falls short of explicit when/when-not routing.

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 only declare readOnlyHint=true, so the description carries the rest: it discloses that quotes are non-fiscal pre-invoice offers and spells out the exact per-row return shape (id, quote number, issue date, total, status), which is genuinely useful with no output schema. It omits pagination/limit behavior and whether results are ordered, keeping it below 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?

Three short sentences, front-loaded with the identity of the resource, then the filter, then the return shape. No filler and no repetition 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?

For a two-parameter read-only list tool with no output schema, the description supplies both the domain meaning and the returned fields. The one real gap is that 'limit' and result ordering/pagination are never addressed, which an agent needs to page results reliably.

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 compensate. It covers the 'status' filter conceptually ('Filter by status') but never lists the enum values or explains their meaning, and it says nothing at all about 'limit' (default 20, max 100). Partial compensation only.

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 ('List quotes') and defines the domain term with a clarifying gloss ('presupuestos: non-fiscal offers sent to a customer before invoicing'), which implicitly separates it from list_invoices. It does not name a sibling tool explicitly, 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?

'Filter by status' implies the intended use case (browse quotes by lifecycle state), but there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as get_quote_series, get_invoice, or list_invoices. Usage must be inferred.

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?

readOnlyHint=true already tells the agent this is a safe read with no side effects. The description adds the concrete field set (name, frequency, next date, active), which is useful behavioral detail, but says nothing about ordering, pagination, or whether inactive profiles are included — notable given 'active' appears as a field.

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 with the resource first and the field list appended; no filler. The Spanish/English synonym parenthetical earns its place for a Spanish-domain tool but is the only slight 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?

With no input parameters, no output schema, and readOnlyHint already covering safety, the description supplies the one thing the structured data omits — the shape of each returned record. Only pagination/result-volume behavior is absent, a minor gap for a simple list endpoint.

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 and there is nothing for the description to compensate for. No parameter semantics are needed or 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?

States a specific verb+resource ('List recurring invoice profiles') and enumerates the returned fields, so an agent knows exactly what this returns. It is naturally distinguished from create_recurring/generate_recurring by the verb, but 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 only implied by the verb 'List': an agent can infer this is the read path for recurring profiles. There is no explicit guidance on when to call this versus create_recurring or generate_recurring, nor on prerequisites or exclusions.

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, so the safety profile is covered; the description adds genuinely new behavior — ordering (newest first) and the per-invoice return granularity (count, last date, total). It does not disclose scope or limits (all time? all customers? pagination?), 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?

Two sentences, no filler: the first defines the set and its ordering, the second defines the return shape. Front-loaded with the scoping condition rather than burying it.

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 carries the burden of explaining returns and does so explicitly (one line per invoice: count, last date, total). It is nearly complete; only the temporal/customer scope of the listing is left unstated.

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?

Zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. It correctly makes no claims about filtering inputs.

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 a precisely scoped resource: invoices where a payment reminder was already sent, including the Spanish synonyms (recordatorio / aviso de pago). That qualifier is what separates it from the broad list_invoices sibling, so an agent can choose correctly 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?

The use case is strongly implied by 'where contix already sent a payment reminder', but the description never states when to prefer this over list_invoices or how it relates to send_reminder. There is no explicit exclusion or alternative routing.

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 declare readOnlyHint=true, so safety is covered. The description adds useful behavioral context by specifying what data comes back (id, NIF, country, expense count), which helps the agent interpret results. It doesn't mention pagination behavior for the limit param.

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 sentences, front-loaded with the returned fields, then the use cases. No wasted text; 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?

No output schema exists, but the description compensates by listing returned fields. For a simple read-only listing tool with annotations, this is nearly complete; only the limit pagination behavior is left implicit.

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?

At 50% schema coverage, only 'search' is documented in the schema; 'limit' has just defaults/bounds with no description. The description mentions neither parameter, so it does not compensate for the gap. Baseline 3 for the documented half only.

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 (list) and resource (suppliers/proveedores) and enumerates the returned fields (id, NIF, country, expense count). The agent can distinguish it from siblings like list_customers or list_expenses 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?

Explicitly names two concrete use cases: finding supplier_id for create_expense, and checking existence before creating a supplier. This routes the agent clearly, though it doesn't state exclusions or mention alternative discovery paths.

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, destructiveHint=false), it discloses the key behavioral fact that no email is sent, the precondition that the invoice must already be finalized, and the return payload (invoice id and marked-sent date). It does not say what happens if the invoice is not finalized (error vs silent accept) or whether repeated calls are idempotent, which keeps it short of 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?

Four sentences, front-loaded with the primary use case before the exclusion, the parameter note, and the return values. No filler and no repetition of the title or annotations.

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 mutation with no output schema, it covers the trigger, the no-op side effect, the prerequisite state, and the return shape. Only the failure mode for a non-finalized invoice is unstated.

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 only 50%, so the description has to carry weight; it explains the optional date's purpose (when it was actually sent on an earlier day) and its YYYY-MM-DD format, duplicating and extending the schema hint. invoice_id is undocumented in both places, though the name is self-explanatory.

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 (record) and resource (a finalized invoice as sent) plus the scope qualifier 'by another channel', and explicitly distances itself from send_invoice. An agent can distinguish it from send_invoice or finalize_invoice without opening either schema.

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

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

Gives the exact triggering condition (customer was reached via your own email thread, WhatsApp, paper), an explicit exclusion (finalizing does NOT count as sent), and names the alternative that handles the other case (send_invoice records it automatically). Nothing is left to inference.

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