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 structurally. The description adds real value beyond that: it discloses that resolution may perform 'a live GET against the public source' and that failure mode is a hard error on unknown ids. It stops short of saying anything about document size or latency, which is the only remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the return shape and the id-provenance rule, then supporting context. Minor waste in the 'Companion of `search` in the OpenAI Deep Research contract' framing and a slightly redundant title echo, but every paragraph carries routing or behavioral 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?

With an output schema present and annotations covering the safety profile, the description need not restate return values, yet it usefully names the fields and flags `url` as the citable canonical page. It is complete for correct invocation; only document-length or truncation behavior is unaddressed, a small gap for a full-text fetch.

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 single `id` parameter is already documented in Portuguese, so the baseline is 3. The description earns the extra point by defining the *provenance contract* for that id — it must come from `search`, anything else errors — which is semantics 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?

States a specific verb and resource ('Returns the full document for an id') and immediately pins its scope to the Deep Research catalog. It also explicitly separates itself from the `search` sibling ('for an id obtained from `search`') and from the `senado_*` family, so the agent can place it without opening a 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 precondition ('Only ids returned by `search` are valid; an unknown id returns an error') and an explicit routing exclusion ('The `senado_*` tools remain the tools for data queries'). This is when-to-use plus when-not-to-use plus the alternative, exactly what an agent needs to pick correctly among ~60 siblings.

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, yet the description adds real operational context: a 10-result cap, relevance ordering, empty-list semantics for no matches, and that the catalog is cached in memory from the public source. The closing 'read-only and idempotent' sentence only restates annotations, which slightly dilutes the 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?

Well front-loaded: purpose and return shape come first, then routing guidance, then query semantics. The Deep Research contract paragraph is a bit long and the final sentence duplicates annotations, but nothing is confusing or out of order.

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 catalog search with an output schema present, the description covers everything an agent needs: what it returns, how many, ordering, empty-result meaning, when to prefer siblings, and the hand-off to `fetch`. No gap remains that would cause a mis-call.

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 and schema coverage is 100%, so the schema already documents it, including the accents/case note that the description repeats. The description adds one genuinely new fact — queries may be in Portuguese or English — which is useful but marginal, leaving it at 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 ('Searches the Brazilian Federal Senate open data ... catalog') and immediately bounds the output ('up to 10 matching documents as { id, title, url }'). It also differentiates itself from the large `senado_*` family by declaring 'this is a catalog index, not a data query', so an agent can route 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?

Explicitly names when to use it (the Deep Research contract requiring exactly `search` and `fetch`) and when not to ('For direct questions and for data (values, series, rankings) prefer the `senado_*` tools'). It also gives the follow-up step: 'Pass one of the returned ids to `fetch` to read the document.'

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 and openWorld, so the safety profile is covered. The description adds behavior beyond them: the default date is today and the response is a wrapper object with a count plus a reunioes array. It does not mention rate limits or pagination, which keeps it 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 operation and the date constraint, with the sibling routing at the end where it belongs. The enumeration of every returned field (codigo, comissao, descricao, hora, local, tipo, situacao) is somewhat redundant given an output schema exists and costs length, but it is still scannable and earns most of its space.

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?

A simple two-parameter read tool whose annotations cover safety; the description supplies the default date, both parameter meanings, the response envelope and explicit alternatives. Nothing an agent needs in order to call it correctly, or to decide not to, 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 both parameters are documented structurally (pattern ^\d{8}$, minLength on siglaComissao). The description still adds value by disclosing the default value ('padrão: hoje') for data and that siglaComissao is an optional filter — the default is absent from 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 ('Obtém a agenda de reuniões'), the exact resource scope (todas as comissões) and the key constraint (numa data), then names the two sibling tools it is not. An agent can distinguish it from senado_reunioes_comissao and senado_reuniao_comissao 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?

Explicitly routes to alternatives with the condition that selects each: histórico por período → senado_reunioes_comissao; detalhes de uma reunião → senado_reuniao_comissao com o codigo. That is a clear when-to-use-which statement, not merely implied context.

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 read-only, idempotent, non-destructive profile, so the bar is lower. The description adds real value with the default-to-today behavior and the exact response shape (`data, escopo, count, sessoes` plus per-session fields), but says nothing about pagination, volume of results, or edge cases such as empty agendas.

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 purpose, then return shape, then routing to alternatives. Every sentence — including the return-shape sentence — carries information an agent can act on.

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?

Although an output schema exists (making the return-value explanation optional), the description still gives enough to call the tool correctly with zero required parameters and three documented optional ones. Nothing an agent needs to invoke 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?

Schema description coverage is 100%, so all three parameters (data, escopo, dataFim) are already documented, including the enum and pattern. The description restates the escopo options and the today-default but adds no syntax or format detail beyond what the schema provides, so 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 ('Obtém a agenda de sessões de plenário'), the two possible scopes (Senado or Congresso Nacional), the granularity (por dia ou mês) and the payload (pauta de matérias a votar). It is clearly distinguishable from the named siblings, so an agent can select it 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 `senado_resultado_plenario` for already-deliberated results and `senado_encontro_plenario` for session details. It also states the default behavior ('sem data assume hoje') and which escopo values to use, 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 establish read-only/idempotent safety, and the description adds genuinely non-obvious behavior: 'atual' means still in tramitação rather than current mandate, the list mixes senadores/deputados/ex-parlamentares, and the same person can appear twice with different `tratamento`. Normalization caveats like these are exactly what an agent cannot 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?

Front-loaded with purpose, then the critical semantic caveat, then return shape and filters — a sensible priority order with no filler sentences. It is dense and long for a single tool, but the length is justified by the disambiguation content; a small trim of the return-field enumeration (already covered by the output schema) would tighten it.

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 output schema exists, the description still provides the caveats the schema cannot: duplicate entries, mixed entity types, and the meaning of 'atual'. Combined with filter semantics and downstream usage, an agent has everything needed to call and interpret results 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, but the description adds meaning beyond it: `nome` is accent-insensitive partial search and `limite` defaults to 50 with a 1000 cap (matching but reinforcing the schema). It also names the returned fields the filters map onto. Slightly redundant with the schema rather than fully additive, hence 4 not 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?

States a specific verb and resource ('Lista parlamentares autores de processos em tramitação'), adds the sort order ('ordenados por produção'), and explicitly differentiates from the sibling `senado_listar_senadores`. An agent can distinguish it from every other author/senator tool without opening a 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 warns what the tool is NOT ('não use como lista de senadores em exercício') and names the alternative `senado_listar_senadores` for that case. It also tells the agent how to continue downstream (pass `codigo` to `senado_obter_senador` or `senado_search_processos`) — both when-to-use and when-not 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 declare readOnly/openWorld/idempotent/non-destructive, and the description adds genuinely new behavior: live queries against the official open-data base whose results may vary between calls, no pagination, and `null` in absent fields with count=0 meaning a valid empty result. Minor tension: 'results podem variar entre chamadas' sits awkwardly beside idempotentHint=true, though idempotency concerns side effects rather than identical payloads — worth a note, not a contradiction.

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 the critical no-empty-filter constraint before the return shape and sibling routing. It is a dense single block and slightly long, but each sentence carries distinct information; a short bulleted split for the error rule and the return shape would improve scanability.

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, zero-required, open-world search this covers everything an agent needs: the mandatory-filter rule, AND combination, absence of pagination, exact return fields and null behavior, plus the follow-up chain to senado_obter_legislacao. Even though an output schema exists, the field-level summary of `count`/`normas` is a useful extra rather than 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 every parameter's type, bounds and format (AAAMMDD vs ISO) is already documented. The description's one real addition is the cross-parameter AND semantics plus the at-least-one-filter rule, which the schema cannot express; beyond that it largely restates field names.

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 names a specific verb+resource ('Busca normas jurídicas federais já promulgadas') and enumerates the covered species (leis, decretos, LCP, EMC). It draws a hard boundary against the closest sibling by excluding propositions in tramitação (PEC, PL, PLP, MPV) and pointing to senado_buscar_materias, so an agent can choose correctly 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 states the positive precondition ('informe ao menos um' of tipo/numero/ano/data) and the failure mode of violating it (deterministic error, not an empty list). It also routes two follow-ups explicitly: use senado_buscar_materias for pending propositions, and pass the returned `codigo` to senado_obter_legislacao for thematic indexing and the full-text URL.

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 safety, and the description adds meaningful behavior beyond them: default limit 100 with max 500, an `aviso` field appended on truncation, and the reassurance that detail calls are unnecessary to list results. It does not discuss pagination beyond the limit/aviso mechanism, so not quite 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-loads the core purpose and the criteria requirement, then moves into the recipe, return shape, and examples. It is a dense single block with mild redundancy against the output schema, but every sentence carries actionable 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 an 11-parameter search tool with an output schema, it covers preconditions, defaults, truncation behavior, routing to the detail sibling, and worked examples. The return-field enumeration duplicates the output schema and could be trimmed, but 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; the description goes further by explaining parameter interactions (ordenarPor: 'dataApresentacao' with ordem: 'desc' and a low limite) and accepted date formats (YYYYMMDD or ISO). It also clarifies that `codigo` is used as input to senado_obter_materia.

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 and enumerates the exact dimensions searchable (tipo, número, ano, palavra-chave, autor, período, situação). It also implicitly separates itself from senado_obter_materia by stating the lookup is for listing, not detail retrieval.

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 precondition ('informe ao menos um critério'), a concrete recipe for the common 'matérias recentes sobre X' request, and an explicit routing rule: only call senado_obter_materia when the user wants detail/tramitação/textos. Alternatives and exclusions are both 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behaviour: negative lançamentos with no label that flow into sums and surface as min/bottom, plus the truncation aviso. However, it states 'limite cap 100' while the schema allows up to 1000, an inconsistency that could mislead an agent planning page sizes.

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 well front-loaded: the negative-values caveat and the estatisticas routing decision come first, followed by the two output branches. Some content (the estatisticas purpose, default values) duplicates the schema descriptions of estatisticas/topN/agruparPor and could be trimmed without loss.

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 an output schema, the description covers the decision logic an agent needs: which mode, when to enable statistics, what the ranking structure looks like, and the truncation signal. The only gap is the overstated limite cap, which conflicts with the structured maximum and could cause an agent to under-request rows.

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 semantics beyond the schema: the modo/estatisticas interaction ('modo ... Ignorado quando estatisticas=true'), what grupos[0] means under agruparPor, and that free-text filters are partial matches. The 'limite cap 100' claim contradicts the schema's maximum of 1000, which weakens otherwise strong parameter guidance.

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 the specific resource (Despesas da Cota para Exercício da Atividade Parlamentar dos senadores) scoped to a year, so an agent knows exactly what data comes back. It does not explicitly contrast itself with near-neighbours like senado_orcamento_parlamentar or senado_remuneracoes_servidores, but the CEAPS scope is distinctive enough to disambiguate in practice.

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: 'para perguntas de maior/menor/média/mediana/distribuição/ranking use estatisticas=true', with a stated reason (aggregate modes only sum, they don't reveal distribution or individual extremes) and concrete example queries. It also specifies the estatisticas-without-agruparPor vs with-agruparPor branches and the default aggregate mode, and points to senado_listar_senadores to obtain codSenador.

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 (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the return payload shape, truncation signaled by count < total, the distinction between an empty section and a nonexistent id, error behavior for invalid secao×tipo combinations, and the important caveat that the source never publishes contract value except in aditivos.

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 constraints, return shape, and caveats in a logical order. It is dense and mostly earns its length, but restates a few schema facts (tipo meanings, limite default/max) that the schema already carries.

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 output schema and full annotation coverage, the description still closes the important gaps an agent would hit: empty-versus-missing id, truncation, invalid combinations, and the absence of contract value in most sections. Nothing needed to call or interpret results 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. The description goes further by documenting cross-parameter validity rules (aditivos only for contratos, acionamentos only for atas_registro_preco) and the truncation meaning of count versus total, though it also repeats some enum descriptions already present in 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 ('Detalha uma seção específica de uma contratação já identificada pelo id') and explicitly distinguishes itself from the locating tools senado_contratos and senado_contratacoes_lista. An agent can tell immediately this is the drill-down tool, not the search 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?

Explicitly routes the agent: obtain the id via senado_contratos or senado_contratacoes_lista, and use those instead when the goal is to locate rather than detail. It also spells out which secao values are valid for which tipo, which functions as use-case gating.

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 annotations (which already declare readOnly/idempotent): it discloses that the text filter runs in the Worker over all fields, states truncation behavior with an `aviso`, defines pagination via `offset`, and notes that `menores_aprendizes` returns raw, non-normalized upstream records. These are non-obvious behaviors an agent needs to interpret results 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 and format before descending into ordering/pagination edge cases; most sentences carry distinct facts. It is dense and long, but the density is justified by the three record types and pagination semantics — only lightly 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?

Covers the multi-type dispatch, return shape, filter scope, ordering, pagination, limits, truncation, and the empty-result case. Sufficient for an agent to call correctly even though it restates return shape that the output schema also provides.

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?

With 100% schema coverage, a 3 would be the floor, but the description adds real meaning: `filtro` is applied server-side across all fields, `ordem` maps to upstream id order, `offset` paginates the 'tail', and `limite` max is 500 with truncation warning. This clarifies parameters beyond their 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 verb (Lista) plus the exact resource set it enumerates — atas de registro de preço, notas de empenho, menores aprendizes — and the `tipo` discriminator. It also distinguishes itself from the sibling `senado_contratacao_detalhe` by pointing to it for deeper lookups.

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 tells the agent to use `senado_contratacao_detalhe` with the returned `id` to drill into a single ata/empenho, giving a clear primary alternative. It lacks guidance on choosing among broader siblings like `senado_contratos` or `senado_licitacoes`, so the routing is not fully 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?

Goes well beyond the read-only annotations: it discloses that the full base is downloaded and filtered in the Worker, that search is partial and accent-insensitive, that results are capped with an `aviso` on truncation, and that the source publishes no contract value anywhere. It also flags that the list mixes subespécies (CT/AC/TD) which must be disambiguated via the `subEspecie` field.

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: the search scope comes first, then the return shape, then the critical caveat about missing values, then routing. A single long paragraph with no filler sentences, though the return-field enumeration could have been trimmed since 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?

Covers everything an agent needs: what is searched, how matching works, the return shape, truncation, the data-source gap on contract values, subespécie ambiguity, and the correct next-step sibling. No material question is left open before invoking it.

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 earns above that by clarifying accent-insensitive partial matching on objeto/fornecedor/número and the cap behavior (`limite` default 50, max 500, plus `aviso`). It does not elaborate on `maoDeObra` or the exact-vs-partial distinction for `cnpj` beyond what the schema already says.

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 contratos administrativos do Senado') plus the dimensions searchable (fornecedor, CNPJ, ano, número, objeto, mão de obra). It does not explicitly differentiate itself from close siblings like senado_contratacoes_lista, senado_licitacoes or senado_empresas_contratadas, so the agent must infer the split from context.

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 routing: use the returned `id` in senado_contratacao_detalhe for itens, pagamentos, garantias or aditivos, and explicitly warns not to spend calls looking for a monetary value. That is a strong when-to-use and when-not-to-burn-calls signal, though it never contrasts with senado_contratacoes_lista.

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 and openWorldHint=true, so the safety profile is fully covered elsewhere. The description's behavioral contribution is limited to naming the return envelope and its fields, which duplicates the output schema rather than adding new context such as result limits or how large a period the external API tolerates.

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 routing information is well front-loaded, but the long enumeration of return fields (codigo, data, casa, tipoUsoPalavra, resumo, indexacao, url, nomeParlamentar, codigoParlamentar, partido, uf) consumes most of the text and is fully 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?

With annotations covering safety, both parameters documented in the schema, and an output schema present, the description supplies what remains needed: purpose, scope and sibling routing. Only minor gaps remain, such as no mention of result caps or practical limits on the date range against an open-world API.

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% — both dataInicio and dataFim are documented with the YYYYMMDD pattern — so the schema already does the heavy lifting. The description restates the required status and format but adds no semantics the schema lacks, such as inclusive bounds, ordering, or any maximum span.

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 scope constraint (a date period). It actively distinguishes itself from the two closest siblings, senado_discursos_senador and senado_discurso_texto, so an agent can select it 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?

Explicit routing: use this tool for plenary-wide lists, use senado_discursos_senador for a specific parliamentarian, and senado_discurso_texto to get the full speech text. The mandatory date parameters are also stated up front, 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?

With annotations already declaring readOnlyHint/idempotentHint, the description still discloses non-obvious behavior: no pagination, empty list plus count 0 when nothing exists, internal year-by-year reading for long periods, and the periodosNaoLidos/aviso fields surfacing source gaps. It also warns that the returned items omit the full speech text.

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 the type distinction, with the ATENÇÃO warning placed before the heavy caveats. However, it runs as one dense unbroken paragraph where the return-shape enumeration and the period warning compete for attention, making it easy to skim past the 30-day trap.

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 still documents the return shape (codigoSenador, tipo, count, discursos, periodosNaoLidos, aviso) and the item fields, including the notable absence of full text. For a 5-parameter tool with an upstream-dependent data source, 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 already 100%, yet the description adds semantics the schema cannot: `tipo` switches the upstream data source and the content shape while preserving structure, and period omission has asymmetric effects between discursos (30-day default) and apartes (full history). That is genuine meaning beyond the field 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 ('Lista pronunciamentos de um senador') and explicitly names what it is not ('Para discursos de todos os senadores num período use senado_discursos_plenario, não esta'). An agent can distinguish it from senado_discursos_plenario and senado_discurso_texto 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 routing: obtain codigoSenador via senado_listar_senadores, get full text via senado_discurso_texto using the codigo field, and use the plenary tool for all-senator queries. It also spells out the critical when-not: omitting dataInicio/dataFim for tipo=discursos silently yields only the last 30 days.

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 the description adds genuinely new operational facts: the return shape { codigoPronunciamento, texto }, that the text can be tens of KB and is never truncated or paginated, and that a missing code or a speech without text yields an error. These output-size and failure semantics are not 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?

Front-loaded with the verb, the key parameter, the return shape and the size caveat before moving to the sibling routing. Every sentence carries either output-shape, error, or alternative-selection 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?

Covers the full chain an agent needs: where the id comes from, what is returned including size expectations, and what fails. Although an output schema exists, the description's added notes on non-truncation and error cases complete the picture for a single-record fetch.

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 already explains that the parameter is the 'codigo' field from the two listing tools and is unique per speech, so the description largely restates it. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 texto integral de um único pronunciamento pelo codigoPronunciamento') and contrasts it with the listing siblings senado_discursos_senador and senado_discursos_plenario. The agent can distinguish this retrieval tool from listing tools 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?

Explicitly states the prerequisite workflow (obtain codigoPronunciamento first via the two discursos tools) and the exclusion rule (use those tools to list/filter, this one only for an already-identified speech). Both the when and the when-not 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 readOnly/idempotent/non-destructive/openWorld, and the description adds materially beyond them: the exact return shape, ordering by quantidade desc, the absence of pagination, and the count=0 edge case for committees with no records. The cross-parameter caveat that codigoParlamentar has no effect in relatoria is exactly the kind of silent-filter behavior an agent needs disclosed.

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 parameter axis, then the return contract, then routing. Dense but every sentence carries distinct information — no filler or restatement of the name.

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?

Everything needed to call correctly is present: required param sourcing, the type axis, the no-op parameter case, and the output contract. With an output schema available the return description is a bonus rather than a gap-filler.

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 the enum axis for tipo is already documented per-parameter. The description still adds value by explaining the interaction between tipo and codigoParlamentar (effective only in autoria) as a single coherent rule and by tying siglaComissao to its discovery path.

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 and resource: ranks parliamentarians by number of matérias in a committee, framed as measuring legislative workload. It explicitly distinguishes itself from senado_buscar_materias ('para a lista das matérias em si (não a contagem)') and from senado_listar_comissoes, so an agent can select it without opening sibling 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/when-not guidance: discover the sigla via senado_listar_comissoes, obtain the codigo via senado_obter_senador, and use senado_buscar_materias if the actual list rather than the count is needed. It also states the exclusion that codigoParlamentar is ignored when tipo=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 readOnly/idempotent/non-destructive, so safety is covered; the description adds non-obvious data-coverage behavior: 'encerrada' only covers consultations closed since ingestion, grows over time, and consultations closed before the first load are not captured. It also discloses defaults applied when parameters are omitted, which materially affects results.

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 mode breakdown, then constraints, then sibling disambiguation — a sensible ordering. It is dense but largely earns its length; minor waste from restating schema defaults ('padrão 85%', 'padrão 1000', 'padrão 10') and the return shape that an output schema already covers.

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 6-parameter, all-optional analytical query tool with an output schema and full annotation coverage, nothing needed to call it correctly is missing: mode semantics, threshold meanings, status scope caveats, and sibling routing are all present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents each parameter; the description adds the interaction semantics of which threshold applies in which mode (percentualMinimo for consenso, margemPolarizacao for polarizada) and the defaults/minimoVotos filter. It repeats default values already present in the schema, so it adds meaning but not a full step above the 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 ('Analisa') and resource ('conjunto completo de consultas públicas abertas') and immediately enumerates the two analytical modes with their ordering criteria. It also names exactly which siblings it is not (senado_ecidadania_consultas_votos, senado_ecidadania_obter_consulta), so an agent can discriminate it 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?

Contains an explicit routing clause: 'É esta a ferramenta para consultas mais votadas, ranking ou panorama ATUAL' and 'não confundir com senado_ecidadania_consultas_votos, que é o acervo HISTÓRICO'. It also explains mode selection (consenso vs polarizada), the default status scope, and redirects single-consultation detail to obter_consulta.

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), and the description adds genuinely new behavioral context: source dataset, approximate size (~15 mil matérias), weekly refresh cadence, and the caveat that source `status` is always `Descontinuado`. It also discloses the response envelope and default page size, which annotations cannot convey.

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 one dense paragraph but well front-loaded: scope first, then routing away from siblings, then the return shape, then parameters. A few clauses restate the same point about the archive vs. current opinion, costing some tightness, 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?

For a 5-parameter, zero-required read tool with an output schema and full annotations, the description covers routing, data provenance, the archive-vs-live distinction, and per-parameter nuance. An agent has everything needed to call it correctly and interpret the results.

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 earns above that by explaining that `uf` both filters and ranks, that only matérias with votes in that UF are kept, and that each item then gains a `recorteUf` field. It also clarifies that `materia` accepts either a numeric code or a name/ementa fragment, which the schema states only tersely.

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 resource and scope: a historical archive of e-Cidadania public-consultation votes with a per-UF breakdown, sourced from the Arquimedes CSV. It explicitly distinguishes itself from both `senado_ecidadania_consultas_analise` (current opinion/ranking) and `senado_ecidadania_listar_consultas` (consultations in progress), so an agent can pick it 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?

It gives an explicit use condition ('apenas quando o pedido for pelo acervo/arquivo histórico ou por votos por estado') and names the alternative to use for 'mais votadas', ranking or current opinion. It even explains why the archive's `status = Descontinuado` should not be read as current opinion, closing a likely misroute.

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), yet the description adds real behavioral context: every consultation starts as `aberta`, flips to `encerrada` when the matéria leaves trâmite, and consultations closed before the first ingestion are never captured, so the encerrada/todas sets grow over time. It also lists the returned fields, which is partly redundant given an output schema exists, keeping this 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 and dataset scope, then return shape, then freshness caveats, then sibling routing – a sensible order with no filler sentences. The enumerated return fields are the one mildly wasteful passage, since 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?

Covers what an agent needs: what the set is, how statuses evolve, the historical gap, pagination via limite, and where to go for detail or analysis. With full schema coverage, an output schema, and rich annotations already in place, 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 description coverage is 100% and the schema already documents limite, pagina (default/min/max) and the status enum with its encerrada caveat in nearly identical wording. The description mentions only `limite` (default 20) and restates the status behavior, adding no syntax, format, or interaction detail beyond the schema. 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?

Names a specific verb+resource ("Lista consultas públicas do e-Cidadania") and pins down the exact dataset: the full set of open consultations (~7.7k), where citizens vote yes/no. It also names the two closest siblings and what they are for, so an agent can differentiate 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?

Explicitly routes: use senado_ecidadania_obter_consulta with an id for a single consultation's detail, and senado_ecidadania_consultas_analise for analytical cuts (consensus/polarization). It also states the boundary of the encerrada/todas sets, so the agent knows which status to pick and what it will and won't get.

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?

Adds context annotations cannot convey: the corpus is persisted in D1, refreshed weekly, spans thousands of events including closed ones, and the default limit is 20. It does not mention pagination/cursor behavior or latency despite the large corpus, which is the only meaningful gap for a read tool of this scale.

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: scope and corpus freshness come first, return shape second, filters third, alternatives last. Slightly long single-block prose, but no sentence 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?

Covers the corpus scope and staleness, the filterable dimensions, the sorting strategy, and the sibling for detail — everything needed to call it correctly for a five-optional-parameter read tool. The return shape is already backed by an output schema, so the description does not need to carry that burden.

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 genuine value by showing how `ordenarPor` and `ordem` combine to produce a ranking and by flagging `comissao` as a sigla. The remaining restatement of status/limite adds little 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 ('Lista eventos interativos do e-Cidadania') and enumerates the subtypes (audiências públicas, sabatinas, lives), so there is no ambiguity with agenda or committee-meeting siblings. It also explicitly contrasts with `senado_ecidadania_obter_evento` for single-item 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 an explicit routing rule ('Para o detalhe completo de um evento use senado_ecidadania_obter_evento') and a concrete scenario for sorting ('Para um ranking dos mais comentados, ordene por comentários'). The agent knows both when to call this tool and when to call the 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 cover read-only/idempotent/open-world safety, but the description adds important operational context: the corpus is persisted in D1, updated daily, includes closed and converted ideas, and some detail fields are null until backfill has read the idea. It also discloses non-obvious semantics such as status categories, 'removida' retaining the last known state, and the distinction between dataPublicacao and the estimated dataCriacaoEstimada.

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 purpose and corpus scope, then moves through return shape, status semantics, date caveats, filtering, ranking, and the sibling alternative. It is dense and parenthetical-heavy but every sentence carries operational value; it is long only because the domain semantics genuinely require it.

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 tool's complexity and the presence of an output schema, the description still supplies the return shape, field meanings, null/backfill behavior, status distinctions, date estimation caveats, and routing to the detail sibling. An agent has enough context to call it correctly without opening other documentation.

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 baseline is 3. The description adds meaningful semantics beyond the schema: it expands the meaning of each status value, notes the default limite of 20, and explains the ranking combination of ordenarPor: 'apoios' with ordem: 'desc'. Pagination is left to 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: 'Lista ideias legislativas propostas por cidadãos no e-Cidadania'. It scopes the corpus as complete (~118 mil ideias, incluindo encerradas e convertidas) and explicitly distinguishes itself from the sibling detail tool senado_ecidadania_obter_ideia.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states how to get a ranking ('ordene por apoios (ordenarPor: "apoios", ordem: "desc")') and when to use the alternative ('Para o detalhe completo de uma ideia ... chame senado_ecidadania_obter_ideia com o id'). Filtering via status and limite is also described.

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 by disclosing that `dataAbertura`/`dataEncerramento`/`comissao`/`linkMateria`, `comentarios`, and `relator` are *always* null and explaining the upstream reason for each. This is exactly the kind of non-obvious behavior an agent cannot infer from annotations or an 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?

Front-loads the purpose and the returned fields, then moves into caveats and the id prerequisite in a logical order. It is slightly repetitive in restating null fields one by one and re-enumerating fields the output schema already covers, which keeps it 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?

Although an output schema exists, the description supplies the crucial caveat that several fields are permanently null, which no schema can convey, plus a fallback route for relator data. Nothing an agent needs in order to call and interpret this tool 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 single parameter is already documented, but the description adds real meaning: the `id` corresponds to the matéria's `codigoMateria`, and it tells the agent which sibling calls produce a valid value. That goes beyond the schema's bare "ID da consulta pública".

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 immediately enumerates the returned object, so it is clearly distinguishable from the listing tools. An agent knows exactly what this tool produces without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit prerequisite — get the `id` first via `senado_ecidadania_listar_consultas` or `senado_ecidadania_consultas_analise` — and routes relator lookups to `senado_obter_materia` with the same código. It stops short of contrasting the output of this tool with `senado_ecidadania_consultas_votos` or `consultas_analise`, but the context for when to use it 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?

Beyond the readOnly/idempotent annotations, it discloses real behavior: unfilled fields return `null`, an inexistent `id` returns an error, `pauta` is capped at 15 items, and `videoUrl` is a YouTube embed or `null`. These are the failure and edge-case semantics an agent needs before calling.

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 usage rules are correctly front-loaded, but the sentence then enumerates every returned field (`id`, `titulo`, `descricao`, `status` values, `pauta`, `convidados`, `videoUrl`) even though an output schema exists, making the definition longer than it needs to be.

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?

Everything needed to call it correctly is present: identifier source, error/null behavior, and the alternative tool. The return-value enumeration is redundant given the output schema but does not leave gaps; only rate limits or auth expectations are unmentioned.

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 `id` as the identifier from the listing tool, so the baseline is 3. The description reinforces the same with the workflow pointer ('Obtenha o id antes'), which adds a small amount of routing value but largely repeats 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?

The definition opens with a specific verb+resource ('Obtém o detalhe completo de um evento interativo do e-Cidadania') and names the concrete subtypes it covers (audiência, sabatina, live). It is clearly distinguishable from the sibling `senado_ecidadania_listar_eventos`, 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?

It states the prerequisite workflow ('Obtenha o id antes via senado_ecidadania_listar_eventos') and gives an explicit exclusion rule: for listing/ranking without description/pauta/convidados, use the listar tool instead. 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 declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuine behavioral context beyond them: the data is scraped live from the page, `comentarios`/`problema`/`solucao` come back null because the page doesn't publish them, status may be server-classified from the timeline when the idea isn't in the corpus (with `origemStatus` disclosing that), and unrecognized events land in `avisos` unparsed. No failure modes, rate limits, or error behavior are mentioned, 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?

Purpose and prerequisite are front-loaded and the **Situação**/**Datas** headings help scanning, but the bulk of the text enumerates every return field — which is largely redundant given a full output schema exists. For a one-parameter read tool the description is heavy; the only sentences that truly earn their place are the status-classification rule, the date-name disambiguation, and the null-field disclosure.

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?

Everything an agent needs is present: how to obtain the id, what the call does (live page read), how to interpret the ambiguous `status`/`origemStatus` pair, which date field is authoritative versus the legacy aliases, and which fields are deliberately null. With an output schema covering return shape, no material gap remains.

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?

Single parameter with 100% schema description coverage ("ID da ideia legislativa"), so the baseline is 3. The description only adds that the id comes from the listing tool; it gives no format or provenance detail beyond that, so 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?

Opens with a specific verb+resource: "Obtém o detalhe de uma ideia legislativa do e-Cidadania, lido ao vivo da página da ideia." This clearly separates it from senado_ecidadania_listar_ideias (the listing sibling) and from obter_consulta/obter_evento (other e-Cidadania detail 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 states the prerequisite workflow: "Obtenha o `id` antes via `senado_ecidadania_listar_ideias`." This tells the agent both the ordering and the sibling to call first. It stops short of stating when NOT to use this tool (e.g., when a list-level summary suffices), so it is not a full 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?

Beyond the read-only, idempotent annotations, the description explains that the tool analyzes the complete set of open consultations and ideas, applies filtering criteria, returns up to 10 suggestions ordered by participation, and distinguishes `count` from `totalQualificados`. It also discloses default filter behavior such as `apenasEmTramitacao` using real status to consider only open consultations.

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 purpose and then explains criteria and output shape efficiently. It is somewhat long and repeats return-field details already available in the output schema, which keeps it from being maximally concise.

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 tool's complexity, single nested parameter, rich schema coverage, and existing output schema, the description supplies enough context to call it correctly and interpret its results. It also covers follow-up tooling for investigating suggestions.

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 meaningful semantics: it presents all criteria as optional, states defaults for polarization/consensus avoidance, minimum participation, and open-consultation filtering, and clarifies that `apenasEmTramitacao` relies on real status. This meaningfully exceed what the schema alone conveys, though not exhaustively.

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: it suggests themes for a monthly public poll by analyzing open consultations and e-Cidadania ideas and selecting those with highest citizen engagement. It clearly distinguishes the operation from retrieval siblings by pointing to `senado_ecidadania_obter_consulta` and `senado_ecidadania_obter_ideia` for investigating a suggestion.

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 a clear usage context for selecting a poll theme and explicitly routes follow-up investigation to the correct `obter_*` sibling based on suggestion type. It does not include an explicit when-not-to-use statement or contrast with all related analysis/list tools, so it falls short of the highest level.

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, so safety is covered; the description adds the non-obvious operational constraint that a broad scan of the base is disallowed and each item carries at most 30 contract numbers. It does not discuss auth, rate limits, or pagination beyond `limite`, which keeps 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 sentences, front-loaded with purpose, then return shape, then constraints, then next-step routing — all load-bearing. Slightly dense with back-to-back parenthetical qualifiers, but no sentence 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?

For a 3-parameter lookup with full schema coverage and an output schema, this covers everything an agent needs: what it matches on, the mandatory-filter rule, the row cap, and where to go for contract-level detail. 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 something the schema does not encode: although no parameter is formally required, at least one of `nome`/`cnpj` must be supplied. It also restates the limite default/max in context of result volume, giving the agent a reason for the cap.

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 empresas que contratam com o Senado") and immediately scopes the matchable fields (nome mín. 3 caracteres, CNPJ/CPF parcial). It is clearly distinct from the adjacent contract tools, which it names as detail-drilldown targets rather than duplicating them.

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 resolve an empresa to an id/número de contrato, then use `senado_contratos` or `senado_contratacao_detalhe` for detalhamento. It also states the precondition ("Exige `nome` ou `cnpj`") and the reason ("a base completa é grande"), so the agent knows it must supply a filter and which alternative to reach for next.

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 safety (readOnly/idempotent/openWorld), yet the description adds real behavioral context beyond them: `encontro` may be empty when a section has no data, may be an array when upstream returns multiple, and the call errors if `codigo` does not exist. That is exactly the failure-mode disclosure an agent needs.

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 return shape and section semantics are front-loaded and every clause carries information. It is dense but not padded; only minor tightening would improve it.

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 tool whose response shape varies by an enum parameter, the description fully covers the polymorphism, the empty-result case, the error case, and code acquisition. 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 goes further by explaining what each enum value of `secao` returns (`detalhes`/`pauta`/`resultado`/`resumo`) and where `codigo` comes from. It adds genuine meaning over 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+resource ('detalhes de um encontro legislativo (sessão de plenário)') and immediately discloses the exact return envelope `{ codigo, secao, encontro }`. It clearly differentiates the plenary scope from commission siblings like senado_reuniao_comissao.

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?

Tells the agent how to obtain the required `codigo` ('via senado_agenda_plenario ou senado_resultado_plenario') and explains which `secao` yields which data. It lacks an explicit 'do not use this for X' exclusion, but the section-by-section guidance effectively routes usage.

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 genuinely useful provenance context (institutional portal, not the open-data API, which doesn't publish the full tree), but it does not disclose pagination/truncation behavior even though a `limite` cap of 200 can silently cut the subtree it claims to return in full.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.