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

Annotations already declare readOnly, idempotent and closed-world, so safety is covered; the description goes well beyond that by enumerating the response payload (estado, estado HTTP, msgError, cuando ocurre, que hacer, si se reintenta) despite there being no output schema. It also discloses the semantic decoding rule for the first digit (1 recibido … 6 cancelado), which tells the agent how to interpret results, not just fetch them.

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 accepted input format, then the return shape, then the disambiguation and taxonomy — no filler. The closing digit-decoding list is genuinely useful but is reference-style detail that crowds an otherwise tight definition; it could sit in a table rather than inline prose.

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

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

With no output schema and three optional synonymous parameters, the description carries the full burden and does: it covers accepted input forms, return contents, retry semantics, and the boundary against HTTP status. Nothing an agent needs in order to call this correctly and interpret the result 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 baseline would be 3; the description adds real meaning by explaining that the accepted value is either the 4-digit code or its symbolic name, and that the first digit encodes the state family. The synonym parameters (codigo, codError) are left to the schema, which already documents them adequately.

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 (explicar) and resource (codEstado del catalogo de la API), and immediately pins the input domain: a 4-digit number such as 3002, 4004 or 5005, or a name like comprobante_invalido. It also explicitly excludes the most likely confusion (el estado HTTP), so an agent can distinguish this from a generic docs/reference lookup.

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 triggering context: use it when you hold a codEstado from an error body, an operation, an emitidos row, or a webhook. The 'no el estado HTTP' clause is a real exclusion. It stops short of naming a sibling to use instead (e.g. consultar_referencia / buscar_documentacion) when the agent has an HTTP status rather than a codEstado, so routing for the negative case is left implicit.

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