Calcular totales de un documento

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds substantive behavior beyond them: identical rules to Sifende validation, the official SET rounding rule (guaraníes, lower multiple of 50), IVA-inclusive prices, and the fact that it performs a purely local computation. It does not describe the shape of the returned result beyond montoPago, which is the only 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?

Four short sentences, front-loaded with the core purpose, then when-to-use, then a pricing caveat, then scope. Each sentence carries information, though 'Los precios incluyen IVA' is partly redundant with the schema and could be trimmed.

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 calculation tool with a rich, fully-documented input schema and no output schema, the description covers purpose, timing, rounding rules and side-effect scope adequately. It only names one return field (montoPago), so an agent lacks the full result shape, but the essential calling context 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%, so every parameter (items, comision, tipoCambio, monedaOperacion, descuentoGlobalPorcentaje) is already documented in the schema. The description adds only the general note that prices include IVA, which duplicates the schema's precioUnitario wording and adds no parameter-level meaning. 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?

States a specific verb+resource ('Calcula el total de un documento') and enriches it with the exact rule set used (Sifende validation rules, SET rounding to the lower multiple of 50). It also distinguishes itself from the issuing sibling by noting 'no emite nada ni llama a la API', so an agent can tell it apart from emitir_documento 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 an explicit when-to-use: 'Usala para obtener el montoPago exacto de una venta al contado antes de emitir'. It scopes the tool (local calculation, no API call) but does not name an alternative tool or state when NOT to use it (e.g., non-cash sales), leaving that to inference.

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