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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds material context beyond them: an uncached HTTPS call taking seconds with a 90s limit, offers that shift with the market, euro amounts excluding tax breakdown, and a concrete failure contract (`{"ok": false, "error": "ArgumentoInvalido", ...}` with the distinction between missing-argument and network failures).

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

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

Purpose is front-loaded in the first clause, followed by parameter routing and then behavioral/error notes. It is dense and semicolon-heavy rather than bloated, but the packed clauses make it slightly harder to scan than a cleanly separated structure would be.

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 12-parameter, zero-required tool with an output schema, the description covers the selection matrix, defaults, precedence, cost model (euros, no tax breakdown), latency, and the failure format. An agent can call it correctly and interpret failures without opening anything else.

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 cross-parameter interaction logic the schema cannot express: explicit `cp`, `consumo` or `potencia` override the `qr`, and without a `qr` the defaults are 3.45 kW and a 2.0TD split. That precedence rule is genuinely additive, though per-parameter meaning largely lives in 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 (consulta/compara) and resource (ofertas de luz y gas del comparador oficial de la CNMC), plus the ordering (de la más barata a la más cara) and the multi-year analysis scope. It also explicitly distinguishes itself from the sibling `leer_factura_qr` by noting the QR text is unnecessary here.

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 rules: luz needs `qr` or `cp`+`consumo`; gas needs `suministro`=gas plus `cp`+`consumo_gas`; ambas combines them. It names the alternative tool (`leer_factura_qr`) and the condition under which it is not needed, which is exactly the when/when-not guidance an agent needs.

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 read-only/idempotent/non-destructive/closed-world, yet the description adds substantial context beyond them: pdftoppm rasterization with page traversal and first-QR-wins, no network use, per-PDF latency (worse with bad scans), a missing-extra dependency, and the exact JSON error shapes for FileNotFoundError, RuntimeError and SinQR.

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

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

Purpose and the key file-type branching are front-loaded, and nearly every clause carries information. It is dense and slightly run-on in the middle, but no sentence is 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?

With an output schema present, return values need no explanation, and the description still covers prerequisites, error taxonomy, performance expectations and parameter interpretation. Nothing needed to invoke the tool 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 genuinely adds meaning: the `.ruta` value is interpreted by extension (`.pdf` case-insensitive rasterized; anything else opened as an image). This extension-branching behavior is not present in 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 verb and resource (extract the comparator QR from a utility-bill file on the server disk) and explicitly scopes the output as identical to `leer_factura_qr`. The extension-based handling makes it immediately distinguishable from its sibling.

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 an explicit selection condition: 'Úsala cuando tengas el archivo y no el texto del QR', which routes the agent away from `leer_factura_qr` (QR text) toward this tool (file). It also states the prerequisite extra `facturas`.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds genuine behavioral context beyond them: execution is local and instantaneous with no network or disk, and failures return an in-band JSON envelope with concrete codes (ArgumentoInvalido, SinQR) including the case of gas/payment QRs lacking cp. It does not describe the shape of the success payload, but an 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?

Front-loaded with purpose, then parameter semantics, alternatives, and error behavior in a tight sequence with zero filler. The single long paragraph with run-on clauses is dense in places, which slightly hurts scannability, but every sentence carries 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?

The output schema carries return values, so the description need not explain them. It covers the input contract, the required cp prerequisite, the sibling routing, and the exact error envelope and codes an agent must handle — complete for a single-parameter, offline parser.

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

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

Schema coverage is 100% and the schema example already shows the query string, so baseline is 3. The description adds real meaning beyond it: the field-by-field mapping of the CNMC query (cp obligatorio, pP1/pP2 in kW, caP1-caP3 annual kWh, cfP1-cfP3 billed-period consumption, imp in euros) and the rule that an absent or unreadable numeric field is treated as 0.

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 (interpreta) and resource (texto ya decodificado del QR de una factura de luz) plus the returned outcome, and explicitly names both siblings (comparar_ofertas for comparison, leer_factura_archivo for files). An agent can route 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?

Gives explicit when-to-use ('Úsala para ver los datos') and names the alternative plus the selecting condition for each sibling: pass the QR to comparar_ofertas to compare, use leer_factura_archivo when you have the file. 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.