Dados Abertos Senado BR MCP

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

The annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful extras: it performs a live GET against the public source, unknown ids return an error, and returns canonical citation URLs plus Markdown content. No contradiction with annotations.

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 well structured, front-loads the core behavior in the first sentence, and every sentence adds value: output shape, sourcing rule, valid-id constraint, sibling role, and live GET behavior. There is no filler.

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 single-parameter fetch tool with annotations, an output schema, and a sibling list, the description is complete. It covers return contents, id provenance, error conditions, citation use, and the relationship to the broader tool suite.

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?

The schema already fully documents the `id` parameter as the identifier returned by `search`. The description reinforces this and adds the unknown-id error behavior, but it does not materially extend the parameter meaning beyond what the schema already states.

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 states a specific verb and resource: 'Returns the full document for an id obtained from `search`' and defines the exact output shape. It also differentiates itself from siblings by naming itself as the companion of `search` and explicitly excluding the `senado_*` tools for data queries.

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 clearly says this tool is the companion of `search`, that only ids returned by `search` are valid, and that `senado_*` tools remain the tools for data queries. This gives the agent explicit routing guidance and an exclusion condition.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds meaningful context beyond those: the catalog is cached in memory, the result is limited to 10 documents, an empty list means no match, and results are relevance-ordered. There is no contradiction with annotations.

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 front-loaded with the core purpose and output contract, then adds routing guidance, query semantics, and behavioral notes. Every sentence carries distinct information, and there is no filler or redundant restatement of the tool title.

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 single-parameter search tool with a huge sibling set, the description is complete: it defines the search domain, output shape, max results, empty-list behavior, language/accent handling, read-only/idempotent behavior, and how to continue with `fetch` or switch to `senado_*` tools. The presence of an output schema also means return values do not need to be re-explained, yet the description still gives useful semantics.

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 already documents natural-language/keyword search with accent/case insensitivity. The description adds value by explicitly stating that queries can be in Portuguese or English and by framing query construction more usefully for an agent, which goes beyond the baseline of simply repeating 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?

The description opens with a specific verb and resource: 'Searches the Brazilian Federal Senate open data ... catalog' and states the exact output shape, result limit, and ordering. It also explicitly distinguishes itself from the senado_* data tools by identifying itself as a catalog index rather than a data query, so an agent can tell it apart from its many siblings.

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?

The description gives explicit routing guidance: use this tool for Deep Research catalog lookups and pass returned ids to `fetch`, while preferring `senado_*` tools for direct questions and actual data. This is concrete when-to-use and when-not-to-use guidance, directly addressing the large sibling list.

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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the default-date behavior ('padrão: hoje'), which is genuine added context, but says nothing about auth, rate limits, or result volume beyond the (schema-backed) return shape.

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 parameters/defaults, then routing alternatives in a single tight paragraph. The full enumeration of return fields is somewhat redundant given an output schema exists, but it is organized and readable.

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?

Covers purpose, both parameters with defaults, return shape, and sibling routing. For a read-only list tool with an output schema and complete annotations, nothing an agent needs to call it 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 baseline is 3, but the description adds meaning the schema omits: that `data` defaults to today when absent and that `siglaComissao` is an optional filter. That default-value disclosure is a real increment over the parameter definitions.

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+scope: 'Obtém a agenda de reuniões de todas as comissões numa data'. It explicitly names the two sibling tools it is not and the conditions that select them, so an agent can distinguish it without opening other schemas.

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 gives explicit routing rules: use `senado_reunioes_comissao` for a single committee's history over a period, and `senado_reuniao_comissao` with the `codigo` for a meeting's details. When-to-use and alternatives are fully spelled out.

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/openWorld/non-destructive, so the safety profile is covered. The description contributes useful behavior beyond that: the default assumption of today's date and the default escopo. It does add a return-shape enumeration that is largely redundant with the existing output schema, so it stops short of 5.

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 defaults, then alternatives — a logical order with no filler. It is slightly heavy because the return-shape enumeration duplicates the output schema, which keeps it from being maximally tight.

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 no-required-param read tool, the description covers purpose, defaults, scope enum, and sibling routing, and an output schema already documents the return. An agent has everything needed to call it correctly.

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 the baseline is 3. The description reinforces the escopo choices and the no-data default, but adds little syntactic meaning beyond what the schema already provides (including the cn-only constraint on dataFim).

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 (obtém) and resource (agenda de sessões de plenário), scoping it to Senado or Congresso Nacional, and explicitly distinguishes itself from senado_resultado_plenario (already-appreciated results) and senado_encontro_plenario (session details). An agent can identify the tool and its boundaries 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 explicit when-to-use conditions (escopo dia/mes/cn; no data → today) and names two alternatives with the exact condition that selects each. Nothing about routing between the three plenary tools 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.

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

Annotations already declare readOnly/idempotent/non-destructive, so the baseline is met there; the description adds genuinely non-obvious behavioral context: the counter-intuitive reading of 'atual' (em tramitação, not mandato vigente), the mixed population of the list, and possible duplicate rows for the same person under different `tratamento`. It does not cover pagination/truncation behavior beyond `limite`, which keeps it short of 5.

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 the semantic caveat, then return shape, then parameters — a sensible priority order with no filler. Dense, though the single long paragraph asks a fair amount of the reader at once.

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?

Even though an output schema exists, the description goes further by naming the payload keys (`count`, `total`, `autores`) and per-author fields, and it resolves the biggest ambiguity an agent would face (the meaning of 'atual'). Nothing needed to call it 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 adds real semantics beyond the schema: `nome` is accent-insensitive partial matching and `limite` defaults to 50 with a 1000 ceiling. The `uf` filter adds little over the schema's example.

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 precise verb+resource ('Lista parlamentares autores de processos em tramitação'), plus the ordering rule (by produção). It explicitly disambiguates itself from the sibling `senado_listar_senadores`, so an agent can pick the right tool without opening either 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, an explicit when-NOT-to-use ('não use como lista de senadores em exercício'), names the alternative for that case, and explains downstream usage of the returned `codigo` in `senado_obter_senador` and `senado_search_processos`.

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 readOnly/openWorld/idempotent/destructive, but the description adds real behavioral context beyond them: the live query against the official open-data base whose results may vary between calls, and the deterministic error (not an empty list) when no filter is supplied. The return-shape narration is largely redundant with the output schema, which keeps this from a 5.

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 the core purpose and the AND/at-least-one constraint before alternatives and return details. It is a dense but coherent single block; the sentence spelling out every returned field overlaps with the output schema and is the one piece of avoidable length.

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 4-param read-only search with an output schema already present, the description supplies everything else an agent needs: the at-least-one-filter rule, AND combination, live-data variability, sibling routing, and the follow-up tool for full text. Nothing required to invoke it 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 adds semantics the schema does not state: the four filters combine in AND mode, and at least one must be provided or the call fails deterministically. It also points to senado_tabelas_referencia for the tipo catalog, which the schema only mentions in passing.

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 (busca normas jurídicas federais já promulgadas) and enumerates the covered species (leis, decretos, LCP, EMC). It explicitly carves out the sibling boundary by naming senado_buscar_materias for proposições em tramitação, so the agent can distinguish it without opening either 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 usage constraint ('informe ao menos um' filtro, com erro determinístico se omitido) and an explicit alternative with the selecting condition (proposições em tramitação → senado_buscar_materias). It also routes the follow-up step to senado_obter_legislacao via the returned codigo.

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 mark this readOnly/idempotent/openWorld/non-destructive, so the bar is lower; the description still adds operational behavior: default limite of 100 with a 500 cap and an 'aviso' field emitted when results are truncated. It doesn't cover error modes or deeper pagination beyond the limit, so it stops short of a 5.

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?

It is long but front-loaded: purpose first, then usability guidance, then return shape, then routing, then defaults and examples. Nearly every clause carries actionable information, though the density is high enough that it slightly exceeds what an agent needs in one pass.

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 11 optional params and an output schema present, the description still supplies the essential context: at least one criterion required, result envelope and key field names, truncation signaling, and worked examples. An agent has everything needed to call and interpret it correctly.

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 is 3; the description goes beyond by showing how parameters combine (palavraChave + ano + ordenarPor:'dataApresentacao' + ordem:'desc' + low limite) and by clarifying date formats (YYYYMMDD or ISO). It reinforces rather than introduces, keeping it at 4 rather than 5.

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?

It names a specific verb (Busca) and resource (matérias legislativas) and enumerates the searchable facets (tipo, número, ano, palavras-chave, autor, período, situação). It also distinguishes itself from the sibling senado_obter_materia by stating details/tramitação/textos should be fetched there instead.

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 gives an explicit precondition ('informe ao menos um critério'), concrete parameter recipes for the common 'matérias recentes sobre X' request, and a clear when-not rule ('não é necessário chamar detalhes para listar resultados'). The routing to senado_obter_materia is conditioned on the user asking for detail.

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/openWorld, so the safe-read profile is covered. The description adds real behavioral context beyond that: limite is capped at 100 with an aviso on truncation, groups are ranked by descending sum with grupos[0] as the top spender, and topN defaults to 10. It stops short of noting pagination or performance limits on full-year scans.

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 estatisticas routing are front-loaded, which is good, but the single dense paragraph then restates output field lists (mes, data, senador, tipoDespesa, fornecedor, cnpjCpf, valor) and enum semantics that already live in the schema and output schema. It is longer than needed, and some clauses duplicate structured data rather than adding value.

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 an 11-parameter tool with two enums and an output schema, the description covers everything an agent must decide before calling: which mode, when statistics apply, how grouping changes results, how filtering interacts, truncation behavior, and where to get the senator code. Nothing essential to 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?

Schema coverage is 100%, so the baseline is 3, but the description goes beyond per-field docs by explaining cross-parameter behavior: estatisticas overrides modo, agruparPor switches the ranking output, and filters combine on the filtered set. The pointer to obtain codSenador via senado_listar_senadores also adds operational meaning the schema does not carry.

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 states a concrete verb+resource: CEAPS parliamentary-quota expenses for senators in a given year, and it enumerates the aggregation/statistics modes it returns. It is clearly distinguishable from generic budget siblings such as senado_orcamento_parlamentar and senado_execucao_orcamentaria by the CEAPS domain, though it never names an alternative tool to contrast against.

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 gives explicit question-to-parameter routing: for max/min/mean/median/distribution/ranking questions use estatisticas=true, otherwise pick an aggregate mode or modo='detalhe'. It explains precisely why the statistics path is needed ('the aggregate modes only sum by group and don't reveal distribution or the individual extreme') and how agruparPor changes the output, 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 the safety profile (readOnly/openWorld/idempotent/non-destructive), yet the description adds substantial behavioral context beyond them: truncation signaled by `count < total`, empty-section behavior, error on invalid combinations, and the critical caveat that the source publishes no contract value in any section (only `aditivos.valor`, sometimes null).

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, followed by parameter semantics, return-shape/truncation behavior, data caveats, and routing. Despite its length, every sentence carries actionable information — no filler.

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?

Given four parameters, two enums, an output schema, and read-only annotations, the description covers everything an agent needs: valid combos, defaults, truncation, error cases, a non-obvious data limitation, and how to obtain the `id`.

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 integrative meaning by spelling out which `secao` values are valid for which `tipo` and the default `limite`/truncation semantics. It mostly reinforces rather than extends the per-parameter schema text, so it exceeds baseline only modestly.

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 (detalha) and resource (uma seção de uma contratação identificada por `id`), and explicitly distinguishes itself from the sibling locating tools `senado_contratos`/`senado_contratacoes_lista`. An agent can tell it apart 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 (detalhar a seção de uma contratação já identificada) and when-not (para localizar a contratação, use as ferramentas de lista). Also states the valid `secao`×`tipo` combinations and that invalid combos error out.

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, and non-destructive behavior, but the description adds substantial context: return shape, per-tipo normalization differences, ordering semantics, truncation warning, empty-list behavior, and routing to detail. No contradiction with annotations.

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 and return shape, then covers ordering, pagination, limits, and routing in a single dense paragraph. Every clause appears to earn its place, with no filler.

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 5-parameter read-only list tool with an output schema and rich annotations, the description covers return shape, per-tipo quirks, ordering, pagination, truncation, empty results, and escalation to detail. Nothing material 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?

Schema description coverage is 100%, so the schema already documents each parameter, making 3 the baseline. The description adds meaning beyond the schema by explaining that the textual filter is applied in the Worker over all fields, that tipo changes the record format, that offset paginates the tail after ordering, and that limite truncation triggers an aviso.

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 ('Lista') and resource (atas de registro de preço, notas de empenho, menores aprendizes) and distinguishes itself from the detail sibling by directing deeper lookups to senado_contratacao_detalhe. An agent can identify the tool's scope immediately.

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?

Routes the agent to senado_contratacao_detalhe for deepening an ata/empenho and explains ordering, filtering, and pagination context. However, it does not explicitly compare this tool with other list-oriented siblings such as senado_contratos or senado_licitacoes.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial non-obvious behavior: the full base is downloaded and filtered in the Worker, search is accent-insensitive partial on objeto/fornecedor/numero, results are truncated at `limite` with an `aviso`, and the source publishes no monetary value (only `aditivos` in the detail tool does). These are real gotchas an agent could not infer from structured fields.

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?

It is dense and front-loads the search capability before the detail-routing and the 'valor' caveat. Most sentences earn their place, though the description is long and the return-shape enumeration is partly redundant with the existing output schema.

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 7-parameter, read-only search tool with an output schema, the definition is more than sufficient: it covers filters, matching semantics, pagination limit, subespécie ambiguity, the missing-value trap, and the follow-up tool. An agent has everything needed to call it correctly without additional context.

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 meaning beyond it: partial and accent-insensitive matching for objeto/fornecedor/numero versus the exact-match cnpj, and the default/max behavior of `limite` with truncation warning. This clarifies matching semantics the schema alone does not convey.

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 states a specific verb and resource ('busca contratos administrativos do Senado') and enumerates the filters (fornecedor, CNPJ, ano, número, objeto, mão de obra). It also differentiates from siblings by naming senado_contratacao_detalhe as the drill-down target and warning that the list mixes subespécies. An agent can tell what this returns and how it differs from the licitações/contratações tools.

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 gives clear operational guidance: use the returned `id` in `senado_contratacao_detalhe` for items, payments, guarantees or aditivos, and explicitly says not to spend calls hunting for the contract 'valor'. However it does not explicitly contrast with close siblings like senado_contratacoes_lista, senado_licitacoes or senado_empresas_contratadas, so the when-to-use routing is strong but incomplete.

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/openWorld, so the safety profile is covered. The description adds the mandatory date-range constraint with format and sketches the returned payload shape, which is genuine extra context; it stops short of pagination or result-size behavior.

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 tight sentences: scope first, then output shape, then sibling routing. No filler, and the most decision-relevant information is front-loaded.

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?

An output schema exists, so return values need not be explained in depth, yet the description still names the top-level keys. Combined with full parameter documentation and explicit sibling routing, nothing needed to call this 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% and both parameters already carry type, pattern and format descriptions. The description's mention of dataInicio/dataFim as required in YYYYMMDD restates what the schema already says, adding no new semantics, so the baseline 3 applies.

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 ('Lista todos os discursos realizados em plenário') plus the scoping dimension (date range). It explicitly distinguishes itself from the two closest siblings, senado_discursos_senador and senado_discurso_texto, so an agent can route without opening schemas.

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 alternatives and the condition that selects each: use senado_discursos_senador for a specific parliamentarian, senado_discurso_texto for the full text. This is exactly the when/when-not routing 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 only cover readOnly/idempotent/openWorld safety, which says nothing about the operational behavior disclosed here: tipo swaps the upstream source, results are unpaginated, empty periods yield count 0 with an empty list, and the return omits the integral text. The 30-day default window for tipo=discursos is a critical non-obvious gotcha that no annotation or schema field conveys on its own.

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 the core summary, then the return shape, then the period caveat and routing hints — a sensible order. It is a dense single block and the 30-day warning is partially duplicated between prose and schema, but nearly every sentence carries distinct operational 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?

Given 5 params, an enum, an output schema, and a crowded sibling namespace, the description supplies everything an agent needs: data source, return shape, non-pagination behavior, the period pitfall, prerequisite tool for the senator code, and follow-up tool for the full text.

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, and individual param docs are largely mirrored here. Above baseline because the description explains the cross-parameter interaction (tipo silently changes what dataInicio/dataFim mean and which upstream source is queried), which per-field schema descriptions do not capture.

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?

Specific verb+resource (lista pronunciamentos de um senador) with explicit scope modifiers (período, casa). It also names the exact siblings it is not: senado_discursos_plenario for all senators and senado_discurso_texto for full text, so an agent can route without opening schemas.

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?

Explicit when-to-use chain: get codigoSenador via senado_listar_senadores, get full text via senado_discurso_texto, use senado_discursos_plenario for all senators in a period. It also states the when-not condition (this tool is only for one senator's own pronunciamentos).

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 the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely useful behavioral context beyond them: the returned text is not truncated nor paginated and may reach tens of KB, and invalid codes or text-less speeches return an error. The return-shape sentence partly duplicates the output schema, keeping this from a full 5.

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 scope are front-loaded, followed by return shape, error behavior, and routing guidance. Every sentence earns its place, though the density of several packed clauses in one paragraph slightly reduces readability.

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?

An output schema exists, so the description need not re-explain return values, and it still supplements them with size and error expectations. Combined with clear usage routing and a fully documented parameter, an agent has everything needed to call it correctly.

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 already documents the single integer parameter, so baseline is 3. The description adds real value by explaining the parameter's provenance — it is the `codigo` field obtained from the two listing tools — which helps the agent source a valid value.

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 (obtém) and resource (texto integral de um único pronunciamento) keyed by `codigoPronunciamento`. It explicitly distinguishes itself from `senado_discursos_senador`/`senado_discursos_plenario`, telling the agent this tool returns text of an already-identified speech while those list/filter.

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?

Explicit when-to-use (fetch the body of one identified speech) and when-not (use the listing tools for summary/date/author). It also gives the prerequisite workflow: obtain `codigoPronunciamento` first from the two sibling tools using the `codigo` field.

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 readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds real behavioral context beyond that: no pagination, output ordered by quantidade descending, and count of 0 when the committee has no records. It also flags the non-obvious silent-ignore behavior of codigoParlamentar under relatoria.

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?

A single dense but well-ordered paragraph: purpose first, then parameter semantics, then return shape, then discovery and alternative routing. Every sentence carries information, though the return-shape enumeration is somewhat heavy given an output schema already exists.

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?

Given three parameters, an output schema, and full schema coverage, the description supplies everything an agent needs: purpose, the tipo/codigoParlamentar interaction, the empty-result case, and the sibling tools for discovery and for the alternate list-based task.

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 goes further by explaining that tipo selects which workload axis is measured and by explicitly warning that codigoParlamentar is ignored in relatoria — a semantic caveat that prevents a plausible misinvocation.

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 ('Ranqueia parlamentares pela quantidade de matérias numa comissão') and immediately scopes it by the tipo axis (autoria vs relatoria), so an agent can distinguish it from list-oriented siblings. It explicitly names senado_buscar_materias as the tool for the underlying list rather than the count.

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?

Explicitly routes the agent: discover the sigla via senado_listar_comissoes, get the parlamentar codigo from senado_obter_senador, and use senado_buscar_materias when the raw list of matérias is wanted instead of a ranking. It also states the condition under which codigoParlamentar is useful (tipo=autoria) and when it is not (relatoria).

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds critical data-availability context: 'encerrada' only covers consultations closed since ingestion (grows over time), and those closed before the first load are not captured. This is valuable beyond annotations, though no rate limits or cache behavior are mentioned.

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 front-loaded, covering modes, defaults, status semantics, return shape, and sibling routing in a single paragraph. It is slightly long but every sentence adds value; no filler.

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?

Given 6 parameters, output schema, and full schema coverage, the description covers the tool's purpose, modes, status behavior, defaults, and return fields (modo, criterio, count, consultas). It lacks edge cases like pagination for limite>50 or error handling, but is otherwise complete.

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 the schema already documents each parameter. The description adds quantitative defaults (percentualMinimo 85%, margemPolarizacao 15 points, minimoVotos 1000, limite 10) and clarifies the sorting logic for each mode, going beyond the schema. It does not explain the parameters' interaction fully, so not a 5.

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 states a specific verb (analisa) and a precise resource (conjunto completo de consultas públicas abertas) and explains the two analysis modes. It explicitly differentiates from siblings senado_ecidadania_consultas_votos (historical archive with UF breakdown) and senado_ecidadania_obter_consulta (single consultation detail).

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 conditions for each mode (consenso=high agreement, polarizada=~50/50) and names the alternative tools for other tasks. The final sentence directly instructs when to use this tool for 'most voted consultations, ranking, or current panorama'.

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/openWorld, so the safety profile is covered. The description adds genuinely useful operational context beyond them: the data source (CSV Arquimedes), volume (~15k matérias), refresh cadence (weekly), and the important caveat that `status` reads as `Descontinuado` in the source archive. It stops short of describing pagination or ranking tie-breaking behavior.

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 and routing before any detail, and every sentence carries information. It is dense and long, with slight repetition of the 'acervo vs. opinião atual' contrast, but nothing is filler.

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?

Despite an output schema existing, the description enumerates the return shape (`count`, `referencePeriod`, `consultas` and per-item fields including `votosPorUf`), covers all five optional parameters, and explains the data's provenance and freshness. Nothing an agent needs to call it 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 baseline is 3, but the description adds real meaning beyond the schema: `uf` not only filters but re-ranks by that state and injects a `recorteUf` field on each item, and `materia` matches either a numeric code or a substring of the name/ementa. Defaults and enum semantics for `ordenarPor`/`ordem` are also restated in context.

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+scope: historical archive of e-Cidadania public consultation votes, broken down by UF. It explicitly names and contrasts the two nearest siblings (`senado_ecidadania_consultas_analise` and `senado_ecidadania_listar_consultas`), so an agent can route 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 (requests about the historical archive or votes by state) and when-not-to-use (current opinion, rankings of most-voted consultations in progress), naming the alternative tool for each case. The distinction is reinforced by explaining that archived records carry `status: Descontinuado`.

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 readOnly/idempotent/destructive/openWorld, so the bar is lower. The description still adds genuinely useful provenance context — that all consultas enter as 'aberta', transition to 'encerrada' over time, and that consultas closed before the first ingestion are never captured — which an agent cannot infer from annotations or schema.

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-loads the core purpose and scope, then routing instructions, in a dense but readable block. The enumerated return fields are somewhat redundant given an output schema exists, which is the only wasted material.

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, the description need not detail return values, and it doesn't overload on them. It covers scope, defaults, status semantics, ingestion limits, and sibling routing — everything needed to call the tool correctly.

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 the baseline is 3. The description restates `limite` (padrão 20) and the status lifecycle, but adds little beyond the schema's own enum description, which already explains the encerrada growth caveat.

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 (Lista) and resource (consultas públicas do e-Cidadania), scopes the default set as the complete 'abertas' collection (~7.7k) and identifies the underlying data (sim/não votes). It is clearly distinguishable from senado_ecidadania_obter_consulta and senado_ecidadania_consultas_analise, which it names explicitly.

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?

Explicitly routes the agent: use senado_ecidadania_obter_consulta for per-consulta detail with an id, and senado_ecidadania_consultas_analise for analytical cuts. The status filter's purpose (aberta/encerrada/todas) is explained, giving clear when-to-use conditions.

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, openWorld. The description adds valuable non-annotation context: the data source (D1, weekly refresh), the rough size (thousands, including closed events), and the return shape. It does not cover rate limits, but this is solid extra context beyond the safety profile.

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 the core purpose, then return shape, then filters and the ranking tip, then the sibling routing. Dense but every sentence earns its place; slightly long with a couple of parenthetical asides, yet no filler.

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?

An output schema exists, and the description still summarizes the returned fields and status enum values, plus the data source and freshness. It tells the agent what it gets, how to filter, how to rank, and where to go for details. Complete for its role.

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 parameters are already documented; baseline is 3. The description does mention filters by status, comissao, and limite and describes the comentarios ranking via ordenarPor/ordem, which maps to what the schema already carries, adding little beyond it.

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: lists interactive e-Cidadania events (public hearings, sabatinas, lives) with the scope explicitly called out as the complete corpus. It also names the sibling senado_ecidadania_obter_evento for detail and scopes itself as the list counterpart.

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?

Explicitly routes the agent: use this for the full list and for a ranking of most-commented events; use senado_ecidadania_obter_evento for full detail of a single event. No explicit when-not beyond that, but clear context and a named alternative.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the corpus is persisted in D1, updated weekly, includes closed/converted ideas, has a fixed size (~114 mil), and clarifies that `autor`/`dataPublicacao` are null in list results. This is beyond what annotations alone provide.

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 purpose and scope, then data shape, then usage guidance — every sentence earns its place with no waste.

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?

Complete for a filtered list tool: annotations cover safety, an output schema exists (so return format needn't be explained), schema covers parameters, and the description adds corpus/persistence context and sibling routing. Nothing an agent needs to call it 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 schema already documents all five parameters including enums and defaults. The description adds a note about filtering by status/limite and how to use ordernarPor/ordem for ranking, which corroborates but doesn't materially extend the schema. 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 ('Lista') and resource ('ideias legislativas') with precise scope ('conjunto completo', ~114 mil ideias incluindo encerradas e convertidas). Explicitly routes to sibling senado_ecidadania_obter_ideia for detail, distinguishing what this tool returns vs the detail tool.

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?

Explicit guidance: use this for the complete list, use obter_ideia for full detail of one idea, and use ordenarPor:'apoios' with ordem:'desc' for a ranking. Names the alternative and the condition that selects it.

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?

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing output-level gotchas: dataAbertura/dataEncerramento/comissao/linkMateria are always null because the portal does not publish the period, and `comentarios` is always null because the page lacks a comments feature. It also explains the semantic substitute for the missing dates (status transitions when the matéria enters/leaves tramitação), which prevents an agent from misinterpreting nulls as errors.

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-loads the purpose, then layers return fields, then null-field caveats, then the id-prerequisite tip. The middle sentences are dense but each carries non-obvious information; the field enumeration is slightly list-like, keeping it just short of maximal efficiency.

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 one required parameter, full schema coverage, and an output schema present, the description still adds the missing behavioral context an agent needs (which returned fields are permanently null and why, plus how to source the id). Nothing required to call it correctly is left unstated.

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% for the single `id` parameter, so the baseline is 3; the description adds provenance value by specifying that the id must come from senado_ecidadania_listar_consultas or senado_ecidadania_consultas_analise. It does not add format or validation detail beyond the schema, so it stays just above baseline.

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 ('Obtém o detalhe de uma consulta pública específica do e-Cidadania') and scopes it to a single record, which cleanly separates it from the sibling listing tools (senado_ecidadania_listar_consultas, senado_ecidadania_consultas_analise). An agent can tell what this returns 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?

Explicitly names the sibling tools to call first to obtain the required `id` ('Obtenha o `id` antes via senado_ecidadania_listar_consultas ou senado_ecidadania_consultas_analise'), giving a concrete alternative-and-prerequisite path rather than leaving lookup order to inference.

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, openWorld and non-destructive, so the safety profile is covered. The description still adds real behavioral context: unfilled fields return `null`, a non-existent `id` returns an error, `pauta` is capped at 15 items, and `videoUrl` is null when no YouTube embed exists. It does not state rate limits or auth needs, but on top of rich annotations this is substantial added value.

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 the core action, then the return shape, then the routing advice. Information-dense but every clause earns its place; the single long sentence is slightly heavy but not padded.

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 single-param, well-annotated read tool with an output schema, the description covers purpose, prerequisite, return shape, error behavior and sibling routing. Nothing an agent needs to call it 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% and there is only one parameter, so the schema already documents `id` fully (constraint > 0, and where to source it). The description reinforces the id-sourcing rule but adds no syntax or format detail beyond the schema, so 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 (obter/detalhar) and resource (evento interativo do e-Cidadania), enumerating the event subtypes (audiência, sabatina, live). It explicitly distinguishes itself from the sibling senado_ecidadania_listar_eventos, so an agent can disambiguate without opening either 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?

Provides an explicit prerequisite (obtain the `id` first via senado_ecidadania_listar_eventos) and an explicit when-not clause (to only list/rank events without descrição/pauta/convidados, use listar_eventos instead). Both the condition and the alternative are named.

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 the safe read-only, idempotent, non-destructive profile, so the description rightly focuses on data behavior. It adds useful quirks beyond annotations: the `descricao` is truncated at ~2000 characters, `comentarios` is always null because idea pages lack comments, and `plConvertido` indicates conversion into a bill. That is solid behavioral context, though some listed fields overlap with the output schema.

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 front-loaded with the core purpose, then adds output details and the prerequisite in a compact three-sentence block. It is slightly longer than strictly necessary because it enumerates return fields despite an existing output schema, but no sentence is wasted.

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?

Given the simple one-parameter schema, existing output schema, and rich annotations, the description supplies everything an agent needs: purpose, prerequisite acquisition of the id, output field overview, and notable data caveats (truncation, null comments). No important operational detail appears to be 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?

The input schema has 100% description coverage and already documents the sole `id` parameter as the legislative idea ID. The description reinforces where to obtain that id, but it adds no format, constraints, or validation semantics beyond the schema, so the baseline of 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?

The description states a specific verb and resource ('Obtém o detalhe de uma ideia legislativa do e-Cidadania') and immediately distinguishes its role from the sibling listing tool by telling the agent to obtain the id via `senado_ecidadania_listar_ideias`. An agent can identify this as the detail-fetching counterpart to the list endpoint without opening either 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?

It explicitly names the prerequisite and the path to satisfy it: get the id first via `senado_ecidadania_listar_ideias`. There is no explicit when-not-to-use clause, but the routing context is clear enough that the agent knows this tool is for detail lookup rather than discovery.

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 the safe read-only/idempotent profile, so the bar is met here by extra behavior: it discloses that it analyzes the full set of open consultas plus ideias, caps output at 10, filters by polarization/consensus thresholds and minimum participation, and orders results by participation. What it does not add is any note on cost, rate, or performance of the full-set analysis.

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?

It is dense but front-loaded: the purpose and scope lead, followed by the return shape, criteria defaults, and routing. Most sentences earn their place, though the detailed return-shape paraphrase is somewhat redundant given an output schema exists.

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 nested, single-object, zero-required-parameter tool, the description covers purpose, criteria defaults, output cardinality, ordering, and the handoff to detail tools. An agent has everything needed to call it correctly even before consulting the schema.

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 real meaning beyond the enum stubs: it explains that `apenasEmTramitacao` (padrão true) considers only open consultas based on real status, and that `evitarPolarizacao`/`evitarConsenso` are on by default, clarifying the behavioral effect of each flag.

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?

It states a specific verb and resource ("Sugere temas para uma enquete pública mensal") plus the exact method (analisa o conjunto completo de consultas abertas e ideias, elege as de maior engajamento, filtrando por polarização/consenso e participação mínima), so an agent can distinguish it from listing/analysis siblings 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?

The description gives clear context for use and explicitly routes follow-up investigation to `senado_ecidadania_obter_consulta` or `senado_ecidadania_obter_ideia` by `tipo`. It does not, however, state when to prefer this selector over `senado_ecidadania_consultas_analise` or `senado_ecidadania_listar_consultas`, so the exclusion side is left implicit.

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 the safety profile (readOnly, idempotent, openWorld), so the bar is lower. The description still adds operational context beyond them: the one-of-nome/cnpj requirement despite zero required params, the 30-contract cap per item, and the default 20 / max 100 limit — all useful for calling it correctly.

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-loads purpose, then return shape/fields, then input constraints, then routing to siblings — a logical order. Every sentence carries distinct information with no 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?

An output schema exists so return values need not be re-described, yet the description usefully summarizes the envelope and per-item fields and caps. Combined with the constraint and routing notes, it is complete for a 3-param, read-only lookup tool.

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 per-field meanings (nome minimum length, partial search, limite default) are already documented and the baseline is 3. The description adds genuine meaning the schema does not encode: that at least one of nome or cnpj must be supplied, preventing a param-less call the schema would otherwise permit.

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 ("Busca") and resource ("empresas que contratam com o Senado") and narrows the search keys (nome mín. 3 caracteres ou CNPJ/CPF). It also names the siblings that own the detail view (senado_contratos, senado_contratacao_detalhe), so an agent can distinguish this list/lookup tool from them without opening schemas.

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?

Explicitly states the selection condition ("Exige nome ou cnpj") and routes the agent to senado_contratos / senado_contratacao_detalhe for contract-level detail. It explains why the input is required ("a base completa é grande"), giving the agent a clear when-to-use and when-to-go-elsewhere rule.

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/openWorld/non-destructive. Beyond that, the description discloses that encontro may be empty when a section has no data, that the call errors when the codigo does not exist, and that encontro's shape varies by section (object vs array). These are meaningful behavioral traits the annotations do not cover.

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-loads the core purpose and return shape, then details sections, failure modes, and sourcing. It is dense and somewhat run-on within the long middle sentence, but every clause carries actionable information with no filler.

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 two-parameter read tool with an output schema, the description covers purpose, section semantics, return shape, empty-result behavior, error condition, and upstream sourcing. Nothing an agent needs to call it 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% and both parameters are documented there, so a baseline of 3 applies. The description adds real meaning above the schema by spelling out what each enum value returns (detalhes general data, pauta planned items, resultado appreciated items, resumo synthesis) and where codigo comes from.

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 the specific resource (a legislative meeting / plenary session) and its scope, and explicitly contrasts the different data slices (detalhes/pauta/resultado/resumo). The named upstream siblings for obtaining the codigo make it clearly distinguishable from senado_agenda_plenario and senado_resultado_plenario.

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: obtain the codigo via senado_agenda_plenario or senado_resultado_plenario, and explains which section to pick depending on the desired data. There is no when-not, but the preconditions and alternatives are concrete enough for correct invocation.

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 the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the provenance caveat: the open-data API does not publish the full tree, so this comes from the institutional portal. That is a genuinely useful disclosure about data trustworthiness and completeness. It stops short of mentioning pagination or how the limite cap interacts with totalSubordinadas, so it is not a 5.

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 purpose, the accepted input forms, and the return-shape breakdown are all front-loaded before the routing advice, and the source caveat closes it. It is dense with backticked field names but every clause carries information; only the return-shape enumeration is partly redundant with the output schema.

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 two-parameter read tool with annotations and an output schema, the description supplies everything the structured fields do not: the semantic meaning of caminho (superiors from the top down to the immediate superior) and of subordinadas (the entire subtree, including nuclei), plus the data-source caveat. Nothing needed to call it 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 description coverage is 100%, so both parameters are already documented, and the description's note that unidade accepts a sigla or a full name only restates the schema. The limite parameter and its interaction with totalSubordinadas is never mentioned. Baseline 3 is correct when the schema does the heavy lifting.

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 resource (the Senate's organizational chart down to service level) and the exact operation (given a unidade, return its superior path and full subordinate subtree). It explicitly names the sibling it is not — senado_servidores — and the different question that tool answers, so an agent can route without opening either 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 concrete question shapes this tool answers ('o que está sob a DGER', 'quais secretarias/serviços pertencem a X') plus an explicit exclusion: to count or list servants under a unit, use senado_servidores with subordinadasA. When-to-use and when-to-use-something-else are both stated.

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 the safe, idempotent read profile, but the description goes well beyond them: it discloses the auto-selected value column surfaced as `campoAnalisado`, the returned envelope (`tipo, modo, ano, totalLinhas`, `agregado[]` ordered by value, `despesas[]`/`receitas[]`), and the truncation behaviour (`limite` default 100 with an `aviso` when truncated). These are real runtime behaviours an agent needs and none are in the annotations.

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?

One dense paragraph, but it is front-loaded with the resource definition and the statistics decision rule, and every clause carries operational information. Some content (return envelope fields, type/modo pairing) restates the schema, which is mild redundancy in an otherwise efficient block.

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 an 8-parameter, 4-enum tool with an output schema, the description covers what is missing elsewhere: when to prefer statistics vs detail mode, that filtering by `ano` is the volume-control lever, sibling disambiguation, and truncation signalling. Nothing an agent needs to call this correctly is absent.

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 interaction semantics the schema entries only hint at: `modo` is ignored when `estatisticas=true`, `estatisticas` + `agruparPor` produces ranked groups with groups[0] as largest, and `campo` may be overridden and silently falls back to the type default. It stops short of explaining the type-to-modo validity matrix in full, which the schema leaves to the reader.

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 opening sentence states a specific resource (Senado budget execution) with the exact measures covered (dotação, empenhado, liquidado, pago / previstas, arrecadadas) and their temporal scope (desde 2013 / 2012). It explicitly positions itself against the closest sibling, `senado_orcamento_parlamentar`, removing ambiguity about which budget tool to pick.

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 gives concrete routing conditions: use `estatisticas=true` for maior/menor/média/mediana/distribuição/ranking, no `agruparPor` = line distribution, with `agruparPor` = ranked groups, and filter by `ano` to shrink volume before requesting `detalhe`. It also names the alternative tool it must not be confused with, which is the rare 'when-not-to-use' clause.

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, so the safety profile is covered. The description adds substantial behavioral context the annotations cannot: the two distinct response shapes, that valorTotal sums the month's spend, and that estimated ranking semantics apply via agruparPor. It does not mention rate limits or failure modes, keeping it just short of a 5.

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 before branching into the estatisticas behavior, and every clause carries information. It is dense and somewhat run-on, but nothing is wasted; a minor trim would improve readability without losing content.

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 7-parameter tool with an output schema, this covers purpose, mode selection, filtering, pagination, and cross-tool routing. The two distinct return shapes are explained even though the output schema exists, leaving no ambiguity for correct invocation.

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 goes beyond restating fields: it clarifies that limite is ignored under estatisticas=true, that topN governs top/bottom when estatisticas=true without agruparPor, and elaborates the agruparPor ranking result. This adds interaction meaning the schema fields alone leave implicit.

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 resource (overtime pay to Senate servants) with scope (ano/mes de referência, a partir de 2013) and explicitly distinguishes itself from senado_remuneracoes_servidores, which covers full remuneration. An agent can tell exactly what this returns 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 explicit routing: for max/min/mean/median/distribution/ranking questions use estatisticas=true, with concrete example phrasings ('quem recebeu mais horas extras'). It also names the alternative tool for full remuneration, so when-to-use and when-not-to-use are both covered.

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, so the safety profile is covered; the description adds genuinely new behavior: the mandatory-filter error condition, the default and max page size, and the fact that raw unfiltered API records are returned. It does not describe pagination beyond 'limite' or ordering, keeping it short of a 5.

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 tightly packed sentences: purpose, return shape, limits, precondition, and alternative. No filler, and the search modes plus the error precondition are front-loaded.

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?

Covers purpose, required input constraint, result cap, and the sibling hand-off; the return payload is restated briefly and an output schema exists anyway, so nothing an agent needs to invoke this 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 contributes an extra constraint the schema cannot express with required:[] — that at least one of 'numero'/'objeto' must be supplied. It also restates default/max for 'limite' and clarifies 'numero' is an exact match.

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 ('Busca licitações do Senado') and enumerates the two supported lookup modes (exact 'numero' or 'objeto' text), which lets an agent distinguish it from the many other senado_* list/search tools. It also explicitly routes to the related sibling senado_contratos.

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 a hard precondition ('Exige ao menos numero ou objeto (sem filtro retorna erro)') and an explicit alternative with its selecting condition ('Para o contrato resultante de uma licitação, use senado_contratos'). Both when-to-use and when-not-to-use are covered.

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, and the description goes well beyond by disclosing a real data caveat: the source never publishes the parliamentarian's UF (always null) and the agent must resolve it via senado_obter_senador. It also explains conditional field population (bloco filled only for bloc leaderships, partido only for party leaderships).

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 the purpose, then return shape, then filters, then alternatives — a logical order. It is dense and somewhat long, enumerating many fields that an output schema already carries, but each clause carries actionable information (field semantics, the UF null caveat, routing hints).

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 read-only listing tool with an output schema, the description supplies everything an agent needs: return structure, conditional field meaning, filtering semantics, a known data-quality trap with its workaround, and sibling routing. Nothing material 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 adds value the schema lacks: it defines the default when no filters are supplied (all houses) and clarifies the casa abbreviations in context of filtering. It does not add syntax beyond the schema for codigoParlamentar or siglaTipoLideranca.

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 ("Lista") and resource ("lideranças") and scopes it precisely to Senate, Chamber and National Congress, with examples (líderes, vice-líderes). An agent immediately knows what entity is returned and can distinguish it from sibling list tools.

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?

Explicitly enumerates the four filter options (casa, codigoParlamentar, vigente, siglaTipoLideranca), states the default behavior (no filters returns all houses), and routes the agent to alternatives: senado_listar_blocos for bloc composition, senado_obter_bloco/senado_obter_senador for follow-up lookups.

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, but the description adds real behavioral context beyond them: the list is HISTORICAL, a filled 'dataDesligamento' means the party left, current composition is entries with null 'dataDesligamento', and the same party may appear repeatedly across distinct adhesion periods. It even warns that without this filter a party looks like it belongs to two blocos at once — a genuine misinterpretation trap.

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 return shape, then the caveat, then routing — a sensible order. Slightly redundant to enumerate '{ count, blocos }' and all block fields when an output schema already exists, which is the only thing keeping this from a 5.

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 no-parameter, read-only listing tool with full annotation coverage and an output schema, the description supplies everything left over: the historical-composition gotcha and the follow-up tools. Nothing needed to invoke or correctly interpret it 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?

The tool takes zero parameters (empty object schema, additionalProperties false), so the baseline is 4. There is no parameter meaning to add; the description instead spends its budget on response semantics, which is the right trade-off.

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?

Names a specific verb+resource ('Lista todos os blocos parlamentares do Senado e seus partidos membros') and immediately distinguishes itself from senado_obter_bloco (single-block detail) and senado_liderancas (leadership). The response envelope '{ count, blocos }' with the field list makes the scope unambiguous.

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?

Explicit routing: use this to discover a bloco's 'codigo' and then call senado_obter_bloco for detail, and use senado_liderancas for leadership data. This is exactly the when-to-use/when-to-use-something-else 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 the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely useful non-obvious behavior: the endpoint only returns active commissions, so ativa=false yields an empty list. That quirk is not derivable from annotations and prevents a wasted call.

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 tight sentences, front-loaded with purpose then caveat then routing. No filler; each sentence carries distinct 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?

Complete for a two-param list tool: purpose, filter semantics, the empty-list edge case, and sibling routing are all present. The return-shape sentence partially duplicates the existing output schema, a minor redundancy.

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 is 3, but the description earns extra credit by explaining the enum values and the counterintuitive ativa=false behavior. It adds meaning beyond the terse schema 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?

States a specific verb (Lista) and resource (comissões/colegiados ativas do Senado) with explicit scope, and distinguishes itself from the sibling senado_obter_comissao. An agent can tell exactly what this returns 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?

Explicitly routes the agent: "Use para descobrir a `sigla` exigida por `senado_obter_comissao` e `senado_reunioes_comissao`." It names the downstream alternatives and the condition that selects this tool, leaving nothing to inference.

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/openWorld, so the safety profile is covered; the description adds real behavioral context beyond that: default `emExercicio=true`, that `uf`/`partido` are filtered locally rather than server-side, that `nome` matching is partial and accent/case-insensitive, and the official provenance endpoint. It does not discuss pagination or result limits, so not a full 5.

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 trigger phrases and filter guidance in dense sentences; nearly every clause adds information. Slightly long and run-on, and restating the return shape is partly redundant given the output schema, which keeps it off 5.

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 zero required params, a fully documented schema, an output schema, and rich annotations, the description supplies everything else an agent needs: trigger contexts, filter semantics, default behavior, and sibling routing. Nothing material is missing for correct invocation.

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 already 100%, so the baseline is 3; the description earns above baseline by explaining the match semantics of `nome` (partial, accent-stripped) and the local-filtering behavior of `uf`/`partido`, plus the `emExercicio` vs `legislatura` tradeoff for choosing the result set.

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 (list senators in office or a given legislature) and explicitly names the sibling it is not for ('Para senadores fora de exercício veja senado_senadores_afastados'). An agent can distinguish it from senado_obter_senador and senado_senadores_afastados without inspecting schemas.

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?

Opens with concrete user phrasings that should trigger it, then prescribes when each optional filter matters ('use `nome` quando você só tem o nome e precisa do `codigo`') and routes onward to `senado_obter_senador`/`senado_votacoes_senador` for follow-up. Both when-to-use and alternatives are stated.

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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds a return-shape summary, but that information is also available in the output schema, and no additional behavioral context such as auth needs, rate limits, or pagination is provided.

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 four efficient sentences with no filler: purpose first, then parameter behavior, then return shape, then the sibling alternative. Every sentence contributes to selecting or invoking the tool correctly.

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 simple read-only tool with one optional parameter, 100% schema coverage, rich annotations, and an output schema, the description covers purpose, parameter semantics, return shape, and the nearest sibling alternative. Nothing needed to call it 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 description coverage is 100%, so the single parameter is already documented in the schema, including its enum values and default. The description restates the same choices and expands 'SF'/'CN' to 'Senado Federal'/'Congresso Nacional', adding only marginal meaning beyond the structured field.

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 ('Lista os membros da Mesa Diretora') and clarifies the exact subset with parenthetical roles. It also names a sibling tool for a related but different need, letting an agent distinguish this from senado_liderancas without opening either 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?

Explains how the `casa` parameter selects between the Senate and Congress Mesa, and explicitly routes party-leadership queries to senado_liderancas. It does not give broader when-not-to-use guidance, but the alternative for the closest adjacent need is clear.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses the empty-result contract (unknown id or no transcript returns totalBlocos 0 with an `aviso`), the coverage/timing characteristics of each session type, truncation behavior (`aviso` signals a cut, 20-block cap in texto mode) and the cross-parameter rule that `sequenciaFim` only acts in modo=texto.

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?

Dense but front-loaded: identity, return shape, coverage caveats, then mode/pagination semantics, then sourcing and the sibling hand-off. It is long for one paragraph, and some coverage detail (e.g. the several session-type enumerations) could be trimmed, but every sentence carries operative 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?

For a 7-parameter tool with an output schema, annotations and a large sibling set, the description covers sourcing of the id, mode semantics, pagination, truncation signaling, empty results and the media alternative — nothing an agent needs to invoke it 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% and the schema already documents each parameter, but the description adds meaning the schema does not: how `modo` reshapes the whole payload, that pagination in resumo mode runs through `sequenciaInicio`, and that `orador` matches partial names in the block text. These cross-parameter interactions are genuinely additive rather than restated.

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: the official transcription (notas taquigráficas) of a plenary session or committee meeting, returned in sequential blocks. It explicitly distinguishes itself from the closest sibling, senado_videos_taquigrafia, which covers media rather than text transcripts.

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 prerequisites (obtain the `id` via senado_agenda_plenario/senado_resultado_plenario for sessions or senado_reuniao_comissao for meetings) and an explicit exclusion (for video/audio use senado_videos_taquigrafia, not this). It also states coverage limits — joint Congress sessions, cancelled/non-held sessions and some solemn sessions have no notes.

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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is free. The description still adds real behavioral context beyond them: the exact error condition for a nonexistent code and the semantic rule that `partidos` is a HISTORICAL composition where a non-null `dataDesligamento` means the party has left.

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?

A single dense paragraph, front-loaded with the purpose and ending with the prerequisite and error behavior. The enumeration of return fields partially duplicates the output schema, which is the only slightly wasteful element.

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, the description need not restate return fields, yet it still supplies the interpretive nuance the schema cannot (null dataExtincao = active block, historical vs current party composition) plus the prerequisite and error path. Nothing needed to call it 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?

Only one parameter with 100% schema coverage, so the baseline is 3. The description adds value above the schema by telling the agent how to source the value ('obtenha o parâmetro codigo primeiro via senado_listar_blocos'), which the schema cannot express.

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 ('Obtém detalhes') plus resource ('bloco parlamentar') and the lookup key ('pelo seu código'). It is immediately distinguishable from the sibling senado_listar_blocos, which enumerates rather than details.

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?

Explicitly routes the agent: obtain `codigo` first via `senado_listar_blocos`, and warns that an unknown code returns an error. It names the prerequisite sibling tool but does not spell out the inverse exclusion (e.g. 'do not use this to enumerate blocks'), so it falls just short of a full when/when-not statement.

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 the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavior: `finalidade` is only populated for temporary colegiados and comes back null with an `aviso` for permanent commissions, and sigla is internally resolved to a numeric code. That edge-case disclosure goes meaningfully beyond the annotations.

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 the verb and primary resource, then branches cleanly into the two sections. The field-by-field enumeration is dense and somewhat long, but each clause carries routing or edge-case information rather than filler.

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?

An output schema exists so return values need not be spelled out, yet the description still explains the shape and the null-`finalidade` caveat. Combined with the sigla-discovery pointer, an agent has enough to call the tool correctly, though it omits explicit pagination/error notes.

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 enriches both parameters: it enumerates the fields returned under `resumo` vs `membros` and annotates subfields (presidente/vice with nome/codigo/bancada, tipoVaga titular/suplente). This is well above a bare schema restatement.

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 ('Obtém dados de uma comissão pela `sigla`') and immediately scopes the two modes via `secao`. It is clearly distinguishable from `senado_listar_comissoes`, which it explicitly frames as the discovery counterpart.

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?

Explicitly routes the agent to `senado_listar_comissoes` when the sigla is unknown, and the `secao` values indicate which view to request. It stops short of stating when this detail tool is preferable to other committee-related siblings (e.g. agenda/voting tools), so it is clear context rather than full when/when-not guidance.

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, openWorld and non-destructive, so the 'somente leitura, sem efeitos colaterais' line is largely redundant. The description does add real value beyond annotations: a live query against the official open-data base, null semantics for absent fields, and an explicit error contract ('Norma não encontrada' rather than an empty object).

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 behavior/return contract, then sibling routing — a logical order where each sentence earns its place. It runs slightly long, with some overlap between the return-field enumeration and the output schema plus a repeated warning about codigo vs. numero.

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?

An output schema exists and annotations cover the safety profile, yet the description still supplies the error case, null handling, and upstream dependency on the search tool. Nothing an agent needs to invoke this 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 description coverage is 100% and the schema's own codigo description already explains the internal-ID vs. law-number distinction, which the description merely restates. It adds only that the value should be sourced from senado_buscar_legislacao, so the baseline of 3 applies.

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 ('Obtém o detalhe de uma norma federal já promulgada pelo seu codigo interno') and explicitly distinguishes itself from senado_buscar_legislacao, which it names as the lookup tool. An agent can tell the two apart without opening either 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?

Explicit routing: get the codigo first via senado_buscar_legislacao, and use that tool for locating norms by tipo/numero/ano, while 'esta serve só para o detalhe de uma norma já identificada.' The when-to-use and the alternative are both stated.

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/openWorld, yet the description adds substantive behavior: ordering (cronológico, most-recent-first), truncation semantics (`count`/`total`, keeps the most recent, emits an `aviso`) and per-section default limits. These are the operational traits an agent needs and they are not derivable from the annotations.

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?

One dense paragraph, front-loaded with the primary purpose and the source of the ID. Every clause maps to a distinct behavior or return shape, though the wall-of-backticks format is heavy to parse.

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?

Even though an output schema exists, the description fully characterizes each section's payload and the truncation contract, and routes the agent to the search tool for the required ID. Nothing needed to invoke it 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 adds per-section meaning for `secao` (what each mode returns) and the different default `limite` values per mode plus the truncation notice, going meaningfully beyond the schema strings.

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 (obter/detalhar) and resource (matéria legislativa) and immediately distinguishes itself from the search sibling by noting that `codigoMateria` comes from `senado_buscar_materias`. The three `secao` modes are enumerated, so an agent knows exactly what this retrieval tool returns.

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 a clear prerequisite/workflow: obtain `codigoMateria` via `senado_buscar_materias`, then call this to detail it. It explains which `secao` to pick for which need (situação/relator, histórico, documentos). It does not state explicit when-not-to-use cases, so it stops short of a 5.

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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description's added behavioral value is limited to enumerating returned fields, which overlaps the existing output schema rather than disclosing new traits like auth needs or rate limits. Adequate but not additive.

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 the purpose and followed by an efficient routing sentence. The long enumeration of ~15 return fields is somewhat redundant given an output schema exists, but it is structured and the final clause earns its place by preventing misuse of a sibling tool.

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 single-param read tool with full schema coverage and an output schema, the description covers the essential precondition and the sibling boundary, which is what an agent needs to invoke it correctly. The return-field list is redundant with the output schema but not harmful.

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% for the single param and the schema already documents 'ID do processo legislativo'. The description adds the precondition that idProcesso must be obtained from a search tool first, which is useful context, but no format or value semantics beyond the schema. 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?

Specific verb ('Obtém detalhes completos') plus resource ('processo legislativo específico pelo seu id') and it explicitly names the sibling it is NOT for emendas/relatorias/prazos. An agent can distinguish this from senado_processo_detalhe without opening either 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?

States the prerequisite workflow explicitly ('Obtenha o idProcesso antes via senado_search_processos ou senado_buscar_materias') and routes to the correct alternative with its discriminating parameter ('para emendas, relatorias ou prazos use senado_processo_detalhe (parâmetro secao)'). When-to-use, how-to-obtain-the-id, and the alternative are all covered.

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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses two important edge behaviors: emExercicio is derived and returns null—never affirmatively stated—when mandate data cannot be read, and a nonexistent code returns an explicit error rather than an empty record. These are exactly the behaviors an agent needs to interpret responses correctly.

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 purpose is front-loaded and each subsequent sentence adds nontrivial information, but the field-by-field return enumeration partly duplicates what an output schema would describe. Still, it is compact and uses code formatting effectively; nothing is wordy.

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 simple lookup with one required parameter, the description covers how to obtain the parameter, the returned object shape, tricky null behavior, error semantics, and the relevant alternative tool. An agent has everything it needs to select and invoke the tool correctly without opening the schema.

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?

The schema already documents codigoSenador at 100%, so the baseline is 3. The description adds value by telling the agent where to get the value (senado_listar_senadores with nome filter) and what happens for an unknown code. It does not add format or type details, but for a single parameter this is more than sufficient.

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 verb and resource ('Obtém o detalhe biográfico de um senador específico') and clarifies scope by naming the sibling tool senado_senador_historico for other biographical/historical dimensions. This makes the tool distinguishable from the large sibling set.

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 explicitly states how to obtain the required codigoSenador via senado_listar_senadores and when to use senado_senador_historico instead (for filiações, profissões, licenças, comissões, cargos). This is direct when/when-not guidance rather than implied.

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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it discloses the returned vote fields, the multi-votação response shape, and the critical namespace-collision warning. It does not discuss auth or rate limits, but with annotations present the bar is lower.

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?

It is front-loaded with the tool's purpose and then the critical constraints, so the important warning is not buried. However, it spends several clauses enumerating return fields even though an output schema exists, which slightly dilutes conciseness.

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?

Given an idempotent read endpoint with an output schema, the description supplies exactly the missing context: the prerequisite search tool, the accepted plenary code space, and the invalid committee numbering space. Return values are covered by the output schema, so the description is complete enough for correct invocation.

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 already documents the single parameter as the votação code and plenary session code. The description reinforces that alias and, more importantly, tells the agent where to obtain the value and which code space is invalid, adding operational meaning beyond 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 and resource ('Obtém detalhes de uma votação de plenário') and names the exact parameter. It also distinguishes itself from the sibling tool senado_votacao_comissao by explicitly limiting valid codes to the plenary space.

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?

Provides an explicit prerequisite ('Obtenha o codigoSessao via senado_search_votacoes antes de chamar') and a clear exclusion: comissão voting codes are not valid here. The alternative path for committee votes is named, so the agent can route correctly.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds non-obvious data behavior: the base spans multiple years so `ano` filtering is recommended, and that the ofício's date differs from the budget year of the emenda. It stops short of describing rate limits or pagination edge cases.

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-loads the resource and its two modes before descending into per-mode return shapes, filtering and pagination guidance. It is dense and long, but every clause conveys operational detail (field names, mode semantics, year caveat) rather than filler; the single unbroken paragraph is the main structural weakness.

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?

Even though an output schema exists (so return values need not be described), the description covers mode semantics, the ano caveat, pagination, drill-down behavior and sibling routing. For a two-mode, five-parameter tool this leaves nothing an agent needs in order to call it correctly.

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 the baseline is 3, but the description adds rationale the schema lacks: why `ano` should be set ('a base cobre vários anos') and what `incluirEmendas: true` actually surfaces (favorecido, CNPJ, órgão, nota de empenho). It also clarifies that `limite`/`pagina` only govern the oficios mode, going marginally beyond the schema text.

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 resource (emendas parlamentares ao orçamento da União) with two explicitly differentiated modes: emendas (proposição) and oficios (execução/indicação de destino). It names the sibling it is not ('Para a execução do orçamento interno do próprio Senado... use senado_execucao_orcamentaria'), so an agent can separate it from senado_execucao_orcamentaria without opening either 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?

Explains which mode to use (emendas = proposta, oficios = documento de execução posterior à proposição), recommends filtering by `ano` because 'a base cobre vários anos', and points to the correct alternative tool for internal Senate budget execution. When-to-use, mode selection and the alternative are all explicit.

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, so the safety bar is low. The description goes further by describing the return envelope and its fields, adding useful behavioral context beyond the annotations, though it omits pagination/rate-limit behavior.

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 and the sentences are dense with useful content. It is a bit long because it enumerates return fields, some of which the output schema already covers, but nothing is truly wasted.

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?

Given the output schema, explaining return values is optional, yet the description does so anyway, which is mildly redundant but harmless. Filter semantics and the sibling escape hatch are covered, leaving it complete for an agent to call correctly.

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. The description adds the relational semantic that the caller supplies either a single day OR a start/end period, a constraint not obvious from the schema's three independent optional fields.

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: how each party leadership oriented its vote in plenary votes, with tallies. It explicitly differentiates from the sibling `senado_resultado_plenario`, so an agent can distinguish it without opening either 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 clear operating context ('Informe `data` (um dia) ou o período `dataInicio`/`dataFim`') and routes to the alternative tool for session results. It does not state when-not to use it versus other vote-related siblings (e.g. `senado_obter_votacao`, `senado_search_votacoes`), so it stops short of a perfect 5.

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 cover safety (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), so the bar is lower. The description still adds real behavioral context beyond what annotations provide: it discloses the return envelope `{ tabela, count, total, aviso?, registros[] }`, the default and maximum limit (100/2000), empty-list behavior when a table has no records, and that aggregated vs. nominal records depend on the table. It does not detail pagination beyond `limite` or the meaning of `aviso`, minor gaps.

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 the core purpose, then efficiently organized into verb+resource, enum enumeration, return shape, and sibling routing. It is fairly dense with three clauses packed per sentence in places, but every sentence carries information an agent needs. Slight density costs a point versus a crisper version.

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?

Given 3 parameters, an enum, an output schema, and rich annotations, the description covers purpose, enum semantics, return shape, limit behavior, filter behavior, and sibling routing. It is essentially complete; the only omissions are the semantics of the `aviso` field and explicit pagination guidance, both minor against an existing output schema.

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 baseline is 3. The description adds value beyond the schema: it explains what each `tabela` enum actually returns (aggregated quantitative vs. nominal list, with per-value examples), which is far richer than the schema's one-line enum description. It also restates `limite` behavior (default 100, max 2000) and clarifies `filtro` matches any field of the record — a small but genuine addition to the schema's example list.

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 states exactly what the tool does — returns Senate personnel tables according to the `tabela` parameter — and explicitly enumerates all eight enum values with parenthetical explanations (e.g., `pessoal` = workforce by class/education). It also names the sibling `senado_servidores` for nominal staff records, clearly distinguishing this tool from that alternative.

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 explicitly routes the agent: use this tool for personnel tables driven by the `tabela` parameter, and use `senado_servidores` for the nominal register of permanent/commissioned servers. The enumerated `tabela` values tell the agent which value to pick for each data need, so both when-to-use and the alternative are given.

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