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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed world), and the description still adds real behavior: the 25-item page cap, per-state aggregation, and the DENUE grouping rule that silently excludes establishments registered under another razón social. That exclusion is exactly the kind of surprising behavior an agent needs to know before reporting a count as complete.

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 return shape before inputs and then the caveat. No filler. The middle sentence slightly restates what the schema already declares about id and razón social, which is the only wasted line.

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 describing returns and does so (per-state totals plus a paginated list capped at 25). For a 5-parameter, zero-required lookup tool the remaining gap is the no-argument case and pagination behavior across pages.

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%, with estado and razon_social already documented in-schema. The description reinforces the id-or-razón-social alternative and the 25-per-page ceiling, but says nothing that refines 'pagina' or the interaction between filtering by estado and the per-state totals. It adds some meaning but does not fully compensate for the uncovered parameters.

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

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

States a specific verb and resource: returns the establishments sharing a company's razón social across the four directories (plantas, sucursales, bodegas, oficinas), plus per-state totals and a paginated list. This is far more than the title restated. It does not name a sibling to contrast with (e.g. ver_empresa), so the differentiation is implied rather than explicit.

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: 'Recibe el id de una empresa o una razón social' tells the agent the two acceptable entry points, and the closing sentence gives an important upstream caveat (a branch registered under a different razón social in DENUE will not appear). There is no explicit when-to-use vs. when-to-prefer-ver_empresa guidance, and nothing about what happens if neither id nor razón_social is supplied despite required=0.

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