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

Beyond the read-only/idempotent/non-destructive annotations, the description reveals behavior such as returning `count: 0` with an empty list when no records exist, partial-name matching, and the exact result fields for each `tipo`. It also notes the 'legislatura atual' scope for auxilio-moradia, which is not visible from annotations or schema alone.

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 dense but every clause carries necessary information: output schemas per type, filter applicability, empty-result behavior, the CEAPS caveat, and examples. Code-formatted enums and output fields keep it scannable despite being long.

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 three-mode tool with one required enum parameter, the description is fully complete: it covers all modes, all optional filters and their limitations, empty-result behavior, the relevant sibling tool, and example inputs. Nothing needed for correct invocation 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?

Although the input schema already documents all three parameters, the description adds substantial meaning by mapping each `tipo` enum value to a distinct output shape and explaining which filters apply to which variant. It also clarifies `nome` as partial search and provides concrete examples, going well beyond the schema's baseline 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 resource ('Dados administrativos dos senadores') and a controlling `tipo` parameter, then enumerates each of the three modes with concrete return shapes. It explicitly distinguishes itself from `senado_ceaps`, so an agent can tell which administrative data this tool provides versus expense data.

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 states exactly when each `tipo` value applies and which optional filters (`uf`, `nome`) work with which subtypes. It also gives an explicit alternative condition: 'Para gastos de cota parlamentar use `senado_ceaps`.' Examples are included, showing realistic call shapes.

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