Dados Abertos Senado BR MCP

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 still adds value by clarifying what the open-world hint means in practice ('a live GET against the public source when the document needs it') and by disclosing the unknown-id error behavior. It does not cover latency or 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?

Front-loaded with the return shape, then contract/scope, then behavior — a sensible ordering with no wasted clauses. The final sentence partially restates the read-only/idempotent annotations and the return-field list overlaps the existing output schema, which costs a point but does not obscure the message.

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 fetch tool with a full output schema and rich annotations, the description supplies everything else that matters: contract role, id provenance, error on unknown id, and live-fetch behavior. Return-value semantics are already in the output schema, so nothing an agent needs 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 baseline is 3; the description goes beyond the schema by tying the `id` parameter's provenance and validity to `search` and by naming the error for invalid ids. It omits the id format/syntax, but the constraint that handlers most often get wrong (using ids not produced by `search`) is stated.

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 ('Returns the full document for an id') and enumerates the returned fields { id, title, text, url, metadata }, specifying what `text` and `url` mean. It also positions itself against `search` (companion) and the `senado_*` tools (data queries), so an agent can distinguish it from ~65 siblings 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 states the precondition ('Only ids returned by `search` are valid'), the failure mode ('an unknown id returns an error'), and the exclusion/route ('The `senado_*` tools remain the tools for data queries'). This is exactly the when-to-use / when-not-to-use guidance an agent needs to select between this and the many senado_* 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, so the safety profile is covered; the description adds genuinely new context (catalog is cached in memory, empty list means nothing matched, relevance ordering, max 10 results). It does restate read-only/idempotent, which duplicates annotations, but the caching and result-count behavior goes beyond them.

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

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

Purpose and return shape are front-loaded, then usage contract, then query semantics, then behavior. The one wasteful line is the closing restatement of read-only/idempotent already carried by annotations, but overall the paragraphs are dense and earn their place.

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, yet the description still supplies the return shape and empty-result semantics, covers the single parameter's accepted languages, and explains the sibling relationship and the required `fetch` handoff. An agent has everything needed to select and invoke 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% with a single `query` param, so the baseline is 3; the description adds meaning beyond the schema by noting the query accepts Portuguese or English as well as natural language or keywords. Accent/case insensitivity is duplicated from the schema, so it falls short of 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?

States a specific verb and resource (searches the Brazilian Federal Senate open data catalog) plus concrete scope: up to 10 documents as { id, title, url }, ordered by relevance. It explicitly distinguishes itself from the `senado_*` family by declaring it is a catalog index, not a data query.

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 (OpenAI Deep Research contract requiring exactly `search` and `fetch`), the routing step (pass a returned id to `fetch`), and clear when-not-to-use (for direct questions and data like values, series, rankings, prefer `senado_*`). Nothing 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 and openWorld, so the safety profile is covered. The description adds the behavioral default ('padrão: hoje') and the exact response envelope and per-meeting fields, which is useful context beyond the annotations, though it stops short of noting rate limits or error 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 the core action and parameters, then the return shape, then the sibling routing – a sensible order. It is dense and packs the full return schema into one sentence, which is slightly more verbose than strictly necessary for selection.

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?

The tool has no required parameters and an output schema exists, so return values need explaining only lightly, which the description nonetheless supplies. Parameters, default, filter semantics and sibling disambiguation are all present; 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% and each parameter is described there, so the baseline would be 3. The description nevertheless adds meaning the schema omits: the default value of `data` when absent (today) and the fact that `siglaComissao` is an optional narrowing filter rather than a required selector.

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 reuniões de todas as comissões'), the scoping dimension (a single date), and the optional filter. It explicitly distinguishes itself from senado_reunioes_comissao and senado_reuniao_comissao by naming their distinct scopes, 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 routing rules: use this tool for the agenda of all commissions on a date, use senado_reunioes_comissao for a single commission's history over a period, and senado_reuniao_comissao (with `codigo`) for one meeting's details. When-to-use and when-to-use-something-else 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds genuine behavioral context beyond that: the default when data is omitted ("sem data assume hoje") and the day/month scope semantics. It does not add auth or rate-limit details.

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 defaults and routing, all in a compact block. Slightly penalized because the enumerated return shape (data, escopo, count, sessoes, etc.) largely repeats what the output schema already declares.

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 needn't explain returns further, and it covers the remaining gaps an agent needs: purpose, default behavior, scope enum, and sibling routing. Complete for a read-only agenda lookup.

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 data (pattern YYYYMMDD, default hoje), escopo (dia/mes/cn semantics) and dataFim. The description restates the escopo values and the no-data default but adds no syntax or format detail 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?

States a specific verb ("Obtém") plus resource ("agenda de sessões de plenário"), its scope (Senado ou Congresso Nacional), and granularity (por dia ou mês). It distinguishes itself from siblings by naming senado_resultado_plenario as the tool for already-deliberated items.

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 escopo dia/mes/cn, omit data to default to today, use senado_resultado_plenario for past results, and senado_encontro_plenario for session detail. Both when-to-use and alternatives are named, 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds non-obvious behavior: 'atual' means still-in-progress rather than current mandate, the list mixes senators/deputies/ex-parliamentarians, and the same person may appear twice under different `tratamento`. That disambiguation is exactly the context annotations cannot supply.

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 with essentially no filler — every clause carries semantics, filtering, or routing information. Slightly front-loaded on purpose but the critical semantic warning is pushed into the second sentence rather than leading.

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 sketches the return shape ({count, total, autores} with codigo, nome, tratamento, uf, quantidadeMaterias) and enumerates all optional filters and their bounds. 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%, so the baseline is 3; the description lifts it by adding accent-insensitive partial matching for `nome` ('busca parcial sem acento'), which the schema does not state. `limite` default/max is merely repeated from the schema, so it does not go further.

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+scope ('Lista parlamentares autores de processos em tramitação, ordenados por produção') and explicitly names the sibling it is not (senado_listar_senadores). An agent can select this tool 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 an explicit when-not ('não use como lista de senadores em exercício') with the correct alternative, and adds downstream routing guidance ('Use o codigo em senado_obter_senador ou senado_search_processos'). Both the selection decision and the follow-up path are 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 cover safety (readOnly, idempotent, non-destructive, openWorld), and the description still adds substantive behavior: a filterless call returns a deterministic error rather than an empty list, and results may vary between calls because it queries the live open-data base. It also discloses the exact return shape and no-pagination 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?

Dense but well front-loaded: scope, constraint, semantics, return shape, and routing in a tight sequence. It is longer than strictly necessary, yet nearly every clause carries a distinct fact, so nothing reads as 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 four-parameter search tool with a live data source, the description covers scope, required-input rule, AND semantics, return shape, and handoff to the sibling that retrieves full text — everything an agent needs to call it correctly and interpret the result.

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 the schema cannot express: filters combine in AND mode and at least one must be supplied even though the schema declares zero required parameters. It also points tipo lookups to senado_tabelas_referencia.

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 (buscar) and resource (normas jurídicas federais já promulgadas), enumerating the species it covers. It explicitly distinguishes itself from siblings: senado_buscar_materias for proposições em tramitação and senado_obter_legislacao for full text.

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 (já promulgadas), when-not (PEC/PL/PLP/MPV in tramitação → use senado_buscar_materias), the required precondition (at least one filter or a deterministic error), and the follow-up path via codigo. Nothing 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 the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds real behavioral context beyond that: the requirement to supply at least one criterion, the default/max `limite`, and that truncation appends an `aviso`. The returned-field enumeration is largely redundant with the existing output schema, which is the only thing keeping this below 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?

Information is front-loaded (search scope first, then routing, then returns, then limits, then examples). It is dense but some content restates the schema (e.g. `limite` default 100/max 500) and the single long sentence chain is slightly run-on rather than bulleted.

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 full schema coverage and an output schema, the description covers selection criteria, required-condition rule, routing to the detail sibling, result shape, and pagination/truncation behavior. 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 description coverage is 100%, so the baseline is 3. The description goes further by showing which parameter combinations answer which query patterns (e.g. `{palavraChave, ano, limite}` vs `{sigla, numero, ano}`) and noting accepted date formats, adding meaning beyond the raw 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 and resource (search legislative 'matérias') and enumerates the dimensions it can search over (tipo, número, ano, palavras-chave, autor, período, situação). It explicitly distinguishes itself from the sibling `senado_obter_materia` by reserving that tool for detail requests, so an agent can separate the two 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 routing guidance: for 'recent matters about X', use `palavraChave`/`ano`/date range with `ordenarPor: 'dataApresentacao'`, `ordem: 'desc'` and a low `limite`, and it warns not to call the detail tool just to list. It names the condition that selects the alternative (`senado_obter_materia` only on explicit detail/tramitação/text requests).

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 bar is lower, yet the description still discloses that estatisticas computes over all filtered expenses and returns top/bottom lists, and that limite truncates with a warning. It does not address anything about cost/rate or sorting stability beyond that.

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 one dense paragraph with heavy bolding and multiple run-on clauses; purpose is front-loaded but the middle is a wall of mode/estatisticas detail that overlaps the schema. Size is somewhat justified by 11 params and five modes, but it is not 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 an 11-parameter, multi-mode tool with an output schema, the description covers mode interactions, filter semantics and the codSenador workflow adequately. One gap: it says 'limite cap 100 com aviso' while the schema allows a maximum of 1000, an unresolved inconsistency an agent must reconcile.

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. Most of the description's parameter narrative (estatisticas overrides modo, agruparPor requires estatisticas, busca parcial on filters) restates what the schema already documents, so it adds limited meaning beyond the structured 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?

The opening sentence states a specific resource and scope: CEAPS parliamentary-quota expenses for senators in a given year, which is a clear verb+resource. It does not, however, differentiate itself from the plausible sibling senado_orcamento_parlamentar or other spending tools, so an agent cannot route between them from this text alone.

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 rules: estatisticas=true for max/min/mean/median/distribution/ranking questions, agruparPor for grouped ranking, the default aggregate modes otherwise, and modo='detalhe' for line-level rows. It even names the workflow dependency ('Obtenha codSenador via senado_listar_senadores').

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 substantial behavior: truncation signalled by `count < total`, empty section vs. nonexistent contratação, error on invalid `secao`×`tipo` combos, and the important caveat that the source publishes no contract monetary value except `valor` in `aditivos`. That last point prevents a real class of failed queries.

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 and front-loaded: it opens with what the tool does, then argument semantics, then return shape, then caveats. It is long and repeats some schema-level definitions of `tipo`/`secao`/`limite`, which costs a point, but nearly 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 a four-parameter detail tool with an output schema, the description covers everything an agent needs: argument validity matrix, pagination/truncation, error cases, empty-result interpretation, and the data-availability caveat. Nothing material is left to inference.

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 all four parameters, including the enum meanings and the `limite` truncation rule. The description largely restates those definitions (tipo natures, secao validity, count/total) rather than adding new syntax or format detail, 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 ('Detalha uma seção específica de uma contratação') and scopes it to a record already identified by `id`. It explicitly distinguishes itself from `senado_contratos` and `senado_contratacoes_lista`, which locate rather than 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 routing: obtain the `id` via `senado_contratos` or `senado_contratacoes_lista`, and use those tools when the goal is locating rather than detailing. It also enumerates which `secao` values are valid for which `tipo`, so an agent can pick arguments without guessing.

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, but the description adds substantial behavior beyond them: the filter is applied in the Worker over all fields, records differ in shape per `tipo` (normalized contract format for atas/empenhos vs raw API fields for menores aprendizes), truncation emits an `aviso`, and an empty `tipo` returns an empty list. This is rich, non-obvious operational context.

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 type enumeration, then layers return shape, ordering, pagination, and routing in a logical order. It is slightly verbose because it re-states `ordem`, `limite`, and `offset` semantics already present in the 100%-covered schema, but every other sentence carries distinct 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 a multiplexed list tool with three `tipo` values, an output schema, and rich annotations, the description covers all the essentials: what each type returns, field-shape differences, ordering, pagination, truncation behavior, empty-result behavior, and where to go for details. Nothing needed to call the tool correctly 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying that `filtro` is applied in the Worker over all fields, that `offset` paginates the tail after sorting, and that truncation at `limite` produces an `aviso`. These details go past the per-field schema descriptions, though `ordem` and `limite` semantics are largely restated 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?

The description names a specific verb and resource ('Lista... atas de registro de preço, notas de empenho ou menores aprendizes') and enumerates the three data types, making it distinguishable from sibling tools. It also explicitly routes to the sibling `senado_contratacao_detalhe` for depth, so an agent can tell what this tool does versus its nearest alternative 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?

It clearly states the context of use (list one of three collections, optional textual filter, pagination via offset) and names the alternative for drill-down (`senado_contratacao_detalhe`). However, it gives no explicit exclusions or guidance relative to other listing siblings such as `senado_contratos` or `senado_licitacoes`, so the when-not-to-use side is inferred rather than 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?

With annotations already covering readOnly/openWorld/idempotent, the description adds materially new behavior: the underlying base is downloaded and filtered in the Worker, partial no-accent search applies to objeto/fornecedor/número, the list mixes subespecies (CT/AC/TD), results are capped by `limite` (default 50, max 500) with an explicit `aviso` on truncation, and the source publishes no monetary value at all. This is unusually rich disclosure of quirks and pitfalls.

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, leading with the search dimensions before the return shape and caveats. Every clause (value absence, subspecies mixing, limit/aviso, follow-up id) carries actionable information, though it is a long single paragraph that could be split for scannability.

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, zero-required, read-only listing tool with an output schema, the description supplies everything an agent needs: filter semantics, output shape (briefly), truncation behavior, a data caveat, and the next-step tool. 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 meaning the schema does not: matching is partial and accent-insensitive for objeto/fornecedor/número, while CNPJ/CPF is exact, and it explains the `limite` truncation semantics and `aviso` flag. It adds real filtering semantics beyond the property 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 ('Busca') plus resource ('contratos administrativos do Senado') and enumerates the filterable dimensions (fornecedor, CNPJ, ano, número, objeto, mão de obra). It clearly identifies the follow-up sibling (senado_contratacao_detalhe) but does not differentiate itself from other contracting siblings like senado_contratacoes_lista, senado_licitacoes or senado_empresas_contratadas, so it stops short of a 5.

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 guidance: use the returned `id` in `senado_contratacao_detalhe` for items, payments, guarantees and additives, and an explicit 'do not spend calls looking for value' warning. Lacks an explicit when-not/alternative rule against the other contract-listing 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 readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description goes beyond them by enumerating the exact return payload (periodo, count, discursos) and the per-item fields, which tells the agent what to expect from the call. It stops short of noting pagination, volume limits, or date-range restrictions, so 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?

Three sentences, front-loaded with purpose, then return shape, then sibling routing. No filler and each sentence carries distinct information the agent needs.

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-only list tool with an output schema and full annotation coverage, the description supplies purpose, mandatory inputs, return structure, and disambiguation from the two closest siblings. 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% and both parameters are documented in the schema with the YYYYMMDD pattern. The description restates the required status and format, which is redundant rather than additive, 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 senado_discursos_senador (per-parliamentarian) and senado_discurso_texto (full text), 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?

Names two alternatives and the exact condition that selects each: use senado_discursos_senador for a specific parliamentarian, senado_discurso_texto for the full text. It also flags that dataInicio/dataFim are obligatory, which is the key precondition for calling it at all.

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 safety profile, but the description adds operationally critical behaviour the annotations cannot express: the upstream source and content change when tipo=apartes, the no-pagination contract, the empty-list/count=0 outcome, and the trap that omitting the period for tipo=discursos silently restricts results to the last 30 days.

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 alternatives, and each caveat is load-bearing. It is long and dense, however, and the exhaustive enumeration of return fields is redundant given that 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 five-parameter, read-only listing tool, the description covers source acquisition, period prerequisites, the tipo switch, empty-result behaviour, and sibling routing. Return values are already carried by the output schema, so 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 baseline is 3; the description earns one extra point by explaining that tipo swaps the upstream source and returned content while keeping the same structure, which the enum description only hints at. The period caveat it repeats for dataInicio/dataFim is already documented in the schema, so it adds no new meaning there.

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 (lists a single senator's speeches) with the filtering axes (período, casa) up front. It explicitly distinguishes itself from both senado_discursos_plenario (all senators) and senado_discurso_texto (full text), so the agent can route between siblings 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?

Names three concrete alternatives with the condition that selects each: get codigoSenador via senado_listar_senadores, full text via senado_discurso_texto, all-senator lists via senado_discursos_plenario. It also states when to pass an explicit period versus relying on the default window.

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 genuinely useful behavior beyond that: the payload can be tens of KB, is neither truncated nor paginated, and an unknown code or speech without text returns an error rather than an empty result.

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 return shape, then size/error behavior, then prerequisites and alternatives. Dense but each clause carries new information; slightly long, though nothing is 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?

Combines prerequisite sourcing, error semantics, payload-size expectations and sibling routing, while the output schema covers the return object — an agent has everything needed to call this correctly on the first attempt.

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 parameter is documented there, but the description goes further by naming the exact source field (`codigo` from the two discursos tools) and clarifying it identifies one speech per call, which the schema alone does not say.

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') and distinguishes itself from list/summary siblings by committing to the full, untruncated transcript of one already-identified speech.

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 prescribes the workflow: fetch `codigoPronunciamento` first via `senado_discursos_senador` or `senado_discursos_plenario` (field `codigo`), and explicitly routes listing/filtering (resumo, data, autor) to those tools instead. 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real behavioral context beyond them: no pagination, descending sort by `quantidade`, `count` = 0 for a committee with no records, and the conditional no-op of `codigoParlamentar`. It stops short of anything about rate limits or failure modes, so 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?

Dense paragraph but front-loaded: purpose first, then return shape, then the parameter caveat, then sibling routing. Every sentence carries information; it is slightly packed into one block rather than broken into steps, keeping 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?

For a 3-parameter ranking tool with an output schema, the description covers purpose, return shape, sort order, empty-result behavior, parameter interaction, and sibling alternatives. 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 description coverage is already 100%, so the baseline is 3. The description goes beyond restating fields by explaining the interaction of `tipo` and `codigoParlamentar` (the filter is silently ignored under relatoria) and naming the ordering field `quantidade`, which is the key semantic an agent needs.

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') plus the axis distinction (autoria vs relatoria). An agent can separate this from senado_buscar_materias (raw lists) and senado_obter_senador 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?

Explicit routing: discover the sigla via `senado_listar_comissoes`, get the parlamentar `codigo` via `senado_obter_senador`, and use `senado_buscar_materias` when the actual list rather than counts is wanted. It also warns upfront that `codigoParlamentar` is ignored for relatoria, which prevents a wrong 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 declare readOnly/idempotent/non-destructive, and the description adds real behavioral context on top: the meaning of each modo, the ordering direction per mode, and the important coverage caveat that `encerrada`/`todas` only capture consultations closed since first ingestion (closed-before-first-load are not captured). This is exactly the kind of non-obvious trait the schema 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?

Front-loaded with the core purpose before the mode breakdown, and each paragraph earns its place. It is dense and slightly repetitive (the encerrada coverage caveat is stated in both description and schema), but that redundancy is minor and the ordering of information is agent-friendly.

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 no prose, and the description still names the return shape { modo, criterio, count, consultas }. With annotations, full schema coverage, and sibling routing all present, nothing an agent needs to select or call the 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%, so the baseline is 3, and the description earns above that by explaining how parameters interact with behavior: percentualMinimo drives the consenso ordering, margemPolarizacao defines the polarizada threshold, and minimoVotos/limite apply across modes. It does not, however, add much beyond the schema for limite/minimoVotos.

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 do e-Cidadania) plus the analytical axis (grau de concordância cidadã), then splits the behavior by `modo`. It explicitly distinguishes itself from the two nearest siblings, consultas_votos (historical archive) and obter_consulta (single 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?

Says exactly when to reach for it ('consultas mais votadas', ranking ou panorama ATUAL) and names the alternatives with the condition that selects them: consultas_votos for historical/UF data and obter_consulta for a single consultation's detail. Explicit when-to-use and when-not.

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/openWorld annotations, the description discloses update cadence (weekly), provenance (CSV Arquimedes), and a non-obvious data caveat: `status` arrives as 'Descontinuado' in the source archive, explaining why the tool treats results as an archive rather than live opinion. That is meaningful operational context an agent could not derive from annotations alone.

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

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

Front-loaded with purpose and scope, then disambiguation, then return shape, then parameters — a sensible order. It is a dense single paragraph with mild repetition of 'acervo/arquivo histórico', but nearly every clause carries routing or semantics value, so the length is largely earned.

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, the description supplies everything else needed: routing rules, data provenance and freshness, the status caveat, and parameter interaction. Even the return envelope is summarized, leaving nothing an agent must infer before calling.

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: `uf` not only filters but ranks by that state and adds a `recorteUf` field per item, `materia` accepts either a numeric code or a name/ementa fragment, and `ordenarPor` drives the ranking. This interaction behavior goes beyond the per-parameter 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 and scope: the historical archive of e-Cidadania consultation votes, broken down by UF, with source (CSV Arquimedes) and size (~15k matérias). It explicitly distinguishes itself from two named siblings (consultas_analise and listar_consultas) 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 an explicit when-to-use rule ('apenas quando o pedido for pelo acervo/arquivo histórico ou por votos por estado') and names the alternative tool for the excluded case ('consultas mais votadas', current opinion). The archived-vs-current split is stated as a decision criterion, not 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, openWorld and non-destructive, so the safety profile is covered. The description adds genuine lifecycle context beyond that: every consultation enters as 'aberta', transitions to 'encerrada' when its matéria leaves tramitação, the encerrada/todas set grows over time, and consultations closed before the first ingestion are never captured.

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 what the tool is and its scope before the routing sentences, and every clause carries information. It is somewhat dense and repeats the schema's status-timing explanation, which is a minor redundancy rather than 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?

For a three-param, paginated list tool with an output schema already present, the description covers scope, lifecycle, sibling routing and the one default parameter. Explaining the return shape (`{ count, consultas }` with field names) is mildly redundant given the output schema, but otherwise nothing an agent needs 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 limite, pagina and status with their defaults, bounds and enum semantics. The description only echoes limite (padrão 20) and restates the status behavior, adding no syntax or format beyond the schema, so the baseline of 3 holds.

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 consultas públicas do e-Cidadania') plus the exact scope (the full set of aberta consultations, ~7,7 mil, where citizens vote sim/não). It explicitly names the sibling tools for detail (senado_ecidadania_obter_consulta) and analytics (senado_ecidadania_consultas_analise), so an agent can separate it 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 routes the agent: call obter_consulta with the id for a single consultation's detail, and consultas_analise for analytical cuts (consensus/polarization). The condition selecting each alternative is stated, leaving little 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 readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds genuinely non-structured context: the corpus is persisted in D1 and refreshed weekly, and it is a complete set (~thousands of events) that includes already-closed ones — important for trusting completeness of 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?

Two dense sentences, purpose-first, then return shape, then filters, then alternatives — a logical front-loaded order. Slightly overloaded with return-field enumeration that is redundant given the output schema, but nothing 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?

An output schema exists, and annotations carry the safety profile, so the description need not detail return values — yet it supplements with data freshness, corpus scope and sibling routing. For a 5-param, all-optional read tool, 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%, so baseline is 3, but the description adds value beyond the schema by explaining how parameters combine for a specific goal (ordenarPor="comentarios" + ordem="desc" for a most-commented ranking). Minor gap: it lists statuses as agendado/encerrado/cancelado while the schema enum also includes "todos".

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 ("eventos interativos do e-Cidadania") and even enumerates the subtypes covered (audiências públicas, sabatinas, lives). It explicitly distinguishes itself from the sibling senado_ecidadania_obter_evento, so an agent can route between them 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?

Names the alternative for detail retrieval ("use senado_ecidadania_obter_evento") and gives a concrete use case for the sort parameters (ranking by comentarios with ordenarPor/ordem). It lacks an explicit when-not-to-use statement or guidance on combining filters, but the routing context 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial beyond that: D1 persistence, daily refresh, ~118k corpus, status semantics (removida = withdrawn from portal, corpus retains last known state), and that some fields are null until backfill. It stops short of describing pagination behavior or rate limits, but the added context is rich.

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?

Long but dense and front-loaded: the core purpose leads, followed by status/date semantics and routing. The date-field explanation is somewhat verbose with repeated content (avisoDatas restates it), but every block carries needed information for a mutant complex 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?

Given an existing output schema the description needn't explain returns, yet it usefully documents the response shape ({ count, ideias, avisoDatas }) and the field-level quirks (dataPublicacao as the future-dated support deadline, dataCriacaoEstimada as a server-side estimate). Nothing needed to call 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; the description goes further by explaining the status filter semantics and clarifying that "apoios" is the available ordering field in the corpus while data/comentarios exist only in the detail view, which adds meaning beyond the enum 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?

States a specific verb ("Lista") and resource ("ideias legislativas propostas por cidadãos") with precise scope: the full corpus of ~118k ideas including closed and converted ones. It explicitly distinguishes itself from the sibling senado_ecidadania_obter_ideia, 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?

Explicit routing: use this tool to list/filter/rank, and call senado_ecidadania_obter_ideia for full detail (text, author, whether it became a bill). It also names the specific arguments for a ranking use case (ordenarPor: "apoios", ordem: "desc"), removing 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?

Beyond the readOnly/idempotent/openWorld annotations, it discloses non-obvious behavior: dataAbertura/dataEncerramento/comissao/linkMateria are always null because the portal doesn't publish the period (lifecycle reflected in `status`), and comentarios is always null because there is no comment feature. This prevents an agent from misreading null as missing data.

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 null-semantics, then prerequisite ordering, which is logical. The enumeration of return field names is partly redundant given the output schema exists, costing some 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?

Given a single required parameter and an available output schema, the definition supplies everything needed: the id source, the always-null fields, and the lifecycle interpretation via `status`. No essential calling information 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% for the single `id` parameter, so the schema already documents it; baseline 3 applies. The description adds only the source of the id (sibling tools), not new syntactic or semantic detail about the parameter itself.

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 o detalhe) and resource (uma consulta pública específica do e-Cidadania), which is distinct from sibling listing/analysis tools like senado_ecidadania_listar_consultas and senado_ecidadania_consultas_analise. An agent can identify its role 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 instructs to obtain the `id` beforehand via senado_ecidadania_listar_consultas or senado_ecidadania_consultas_analise, which is clear orchestration guidance. It lacks an explicit 'when-not-to-use', but the prerequisite routing is stronger than most.

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, openWorld), and the description adds substantial context beyond them: missing fields return null, videoUrl is a YouTube embed or null, pauta is capped at 15 items, id inexistente returns an error, and status carries an enum of agendado/encerrado/cancelado. These are exactly the behavioral traits an agent needs and that annotations cannot express.

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 routing constraint, then the return shape, then prerequisites/alternatives — good ordering and no filler. It is slightly over-packed: the long field enumeration partially duplicates the existing output schema, which costs a little 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?

For a single-param read tool with annotations, full schema coverage and an output schema, the description supplies everything extra an agent needs: field semantics, null/error behavior, the pauta cap, status enum values, and the sibling routing rule. 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% and the single parameter is fully documented in the schema, so the baseline is 3. The description adds genuine semantic value by telling the agent the id must be sourced from senado_ecidadania_listar_eventos, linking the parameter to its origin rather than restating its type.

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 (obter detalhe completo) and resource (evento interativo do e-Cidadania), and immediately enumerates the three event subtypes (audiência, sabatina, live). It explicitly contrasts itself with senado_ecidadania_listar_eventos, so an agent can route 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?

Gives both a prerequisite ('Obtenha o `id` antes via senado_ecidadania_listar_eventos') and an exclusion ('Para apenas listar/rankear eventos ... use senado_ecidadania_listar_eventos, não esta'). This is explicit when-to-use and when-not-to-use guidance naming 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 carry readOnly/idempotent/destructive, but the description adds real behavioral warnings beyond them: `descricao` is truncated at ~2000 chars, `comentarios` always returns null, and crucially `dataPublicacao` is a future deadline rather than a publication date (a historical misnomer). These prevent concrete misinterpretation of the response.

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 operation, then groups the return fields and uses a bolded "Datas:" block for the tricky semantics. Dense and mostly earned, though enumerating the return object partially duplicates 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?

Despite an output schema existing, the description resolves the genuinely ambiguous parts (date semantics, truncation, null field, id sourcing) that the schema cannot express. 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?

With 1 parameter at 100% schema coverage, the schema already defines `id` as the idea identifier. The description only adds where the value comes from (listar_ideias), which is useful workflow context but marginal semantic detail, matching the baseline 3.

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 ideia legislativa do e-Cidadania"), and the field list plus the singular "detalhe" framing cleanly separates it from the sibling senado_ecidadania_listar_ideias. 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 names the alternative and prerequisite: "Obtenha o `id` antes via `senado_ecidadania_listar_ideias`." It gives clear entry conditions but no explicit when-not-to-use or contrast against the other obter_* siblings, so it falls just short of 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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: the filtering semantics (polarization/consensus avoidance, minimum participation), the defaults applied, and that apenasEmTramitacao considers only open consultas 'com base no status real'.

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 dense but information-bearing. It loses a point for detailing the return shape (`criteriosAplicados`, `count`, `totalQualificados`, etc.) that an output schema already supplies, making the paragraph longer than strictly needed.

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 zero-required-parameter analysis tool with annotations and an output schema present, the description covers purpose, criteria semantics, defaults, and follow-up routing. 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% with nested-object descriptions, so baseline is 3. The description nonetheless adds meaning: it flags the criteria as optional, restates the defaults in context, and clarifies that apenasEmTramitacao keys off real status rather than a static flag, which the terse schema text 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?

States a specific verb+resource+scope: 'Sugere temas para uma enquete pública mensal (seleção de pauta)', and explains it is an aggregation/election tool over the full set of consultas and ideias. It is clearly distinguishable from the listar_/obter_ siblings, which it explicitly names as follow-up 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?

Clearly frames the use case (monthly public poll theme selection) and routes the agent to senado_ecidadania_obter_consulta / obter_ideia for investigating a suggestion depending on `tipo`. However it gives no explicit 'when not to use' versus siblings like senado_ecidadania_consultas_analise, so it stops short of full alternative 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 cover readOnly, idempotent, non-destructive and openWorld behaviour, so the safety profile is settled. The description still adds genuinely behavioural facts: minimum 3 characters, partial matching, a hard requirement for at least one search term because of the base size, a 30-contract cap per item, and the limite bounds (padrão 20, máx 100). Return-shape detail overlaps the existing 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?

Three dense sentences, front-loaded with the capability before constraints and routing. Every clause earns its place, though the return-field enumeration is somewhat redundant given 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 read-only search tool with full schema coverage, full annotations and an output schema, the description supplies the remaining essentials: the mandatory search term, match semantics, page size bounds, and where to go for detail. 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%, so all three parameters are already documented with types, minLength, default and maximum. The description nevertheless adds rationale the schema does not carry: why one of nome/cnpj is mandatory (the full base is large) and that matching is partial. That is real added meaning, but most parameter semantics are duplicated.

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), plus the two searchable identifiers (nome, CNPJ/CPF). An agent can immediately distinguish it from the detail-oriented siblings senado_contratos and senado_contratacao_detalhe, which are explicitly named as follow-ups.

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 precondition ('Exige nome ou cnpj') with the reason the full base cannot be enumerated, and routes the agent to senado_contratos / senado_contratacao_detalhe for deeper detail using the returned id or contract number. Nothing about when to pick this tool over its neighbours 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds real behavioral context: the `encontro` payload may be an object or an array depending on upstream, may come back empty for a section with no data, and the call errors out if `codigo` does not exist. Auth, rate limits, and pagination behavior are still unstated.

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 core purpose is front-loaded in the first clause, and the section-by-section enumeration is information-dense rather than filler. It is a single long paragraph with heavy parenthetical load, so it is dense but each clause carries meaning.

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 full schema coverage, annotations, and an output schema, nothing needed to invoke it correctly is missing: purpose, prerequisite sourcing of `codigo`, section semantics, and failure/empty-case behavior are all covered.

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 would be 3, but the description actively enriches the enum beyond the schema's terse 'Qual seção do encontro consultar': detalhes yields type/date/status/attendance, pauta yields scheduled matters, resultado yields deliberated items and outcomes, resumo yields a synthesis. It also explains the integer `codigo` as the meeting identifier sourced from sibling tools.

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 qualifies the scope by section. It also names the two sibling tools that produce the required `codigo`, so an agent can distinguish it from senado_agenda_plenario and senado_resultado_plenario 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 tells the agent how to obtain the required `codigo` ('Obtenha o `codigo` via `senado_agenda_plenario` ou `senado_resultado_plenario`'), which is genuine prerequisite guidance. It stops short of an explicit when-not statement or a rule for choosing between the four sections beyond their content descriptions.

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 safety and idempotency are covered. The description adds valuable behavioral context: it explains the return shape (caminho, totalSubordinadas, subordinadas with sigla, nome, nivel), the source (portal institucional, not the open-data API), and the limitation that it goes only to service level. It does not, however, disclose rate limits or pagination behavior beyond the 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 a single dense paragraph with clear structure: purpose first, then return-shape details, then usage examples, then alternative, then source note. It is front-loaded and efficient, though slightly long for the information delivered because the return shape might be partially covered by 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?

Given that an output schema exists, the description does not need to explain return values exhaustively, but it still provides a concise contract for the response (caminho, subordinadas, etc.). It also closes the loop on the known limitation of the data source, which is crucial for an agent to avoid expecting open-data coverage. Nothing essential 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 100%, so the schema already documents both parameters, including examples for 'unidade' and the limite default/max. The description repeats the sigla/name examples but adds no new parameter syntax or constraints beyond what the schema provides. 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?

The description states a specific verb and resource: it delivers the organizational structure (organograma) of the Federal Senate down to service level, given a unit. It clearly distinguishes itself from sibling tools by naming senado_servidores as the alternative for counting/listing staff.

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 describes when to use the tool ('o que está sob a DGER', 'quais secretarias/serviços pertencem a X') and gives an exclusion: for counting or listing servants, use senado_servidores with subordinadasA. This is precise routing 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?

With annotations already covering the read-only/idempotent safety profile, the description adds substantive behavior: expense figures are accumulated within the exercise up to the file's position date, the current exercise is partial and growing, revenue `arrecadada` is monthly while `prevista` is booked whole in month 1, values can be revised later, and `limite` truncation emits an `aviso`. This is exactly the kind of beyond-annotation context the dimension rewards.

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 text is long but densely front-loaded: purpose first, then estatisticas/agruparPor behavior, then return shape, then field semantics, then the sibling disambiguation. For an 8-parameter tool with six modes this size is justified, though a few clauses could be tightened.

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 orients the agent on the response shape (`agregado[]` ordering, `detalhe` arrays capped by `limite`) and the vintage/provenance semantics of each metric. Nothing needed to call it correctly — modes, filters, stats flag, value-column selection — 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 cross-parameter semantics not obvious from the schema alone: the analyzed value column is auto-chosen per `tipo` and surfaced in `campoAnalisado`, `modo` is ignored when `estatisticas=true`, and `agruparPor` reranks groups by descending sum (grupos[0]=maior). These interactions meaningfully supplement the parameter docs.

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 (execução orçamentária do Senado, despesas vs receitas próprias) and explicitly differentiates from the one confusable sibling `senado_orcamento_parlamentar` with a clear rationale (emendas/ofícios ao orçamento da União). 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?

Gives explicit routing conditions: use `estatisticas=true` for maior/menor/média/mediana/distribuição/ranking, with and without `agruparPor`; use `tipo=despesas` with specific `modo` values vs `tipo=receitas`; and filter by `ano` before requesting `detalhe` to reduce volume. It also names the tool this one should not be confused with.

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 substantial behavior: the exact return shape with and without estatisticas, what valorTotal aggregates, that limite is ignored when estatisticas=true, and that agruparPor ranks groups by descending sum with grupos[0] as the top receiver.

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 every sentence carries operational detail, but the dense backtick-heavy phrasing over ~10 clauses makes it heavier than needed; a leaner split of the estatisticas branches would read faster.

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 branching output, the description is complete: it covers filter (nome, partial match), paging, the statistics branch, grouping, and the sibling alternative. An output schema exists, yet the added return-shape detail removes any ambiguity about what each mode yields.

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 the interaction semantics between parameters — notably that limite is ignored when estatisticas=true and how agruparPor=nome vs competencia changes aggregation. It largely restates defaults already in the schema, keeping it below 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+resource: overtime pay ('horas extras') for Senate servers in a reference ano/mes, with a stated time floor (2013). It also distinguishes itself from senado_remuneracoes_servidores for the adjacent use case, so an agent can tell it apart from 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?

Explicitly routes the agent: use estatisticas=true for max/min/mean/median/distribution/ranking questions (with concrete example phrasings), and use senado_remuneracoes_servidores for full remuneration. It also states the branch condition 'sem estatisticas' for the plain listing path.

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 usefully adds that results are raw administrative-API records, are capped by limite, and that a filterless call errors out. It stops short of describing pagination/offset behavior or result ordering.

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, zero filler: query modes first, return shape second, precondition third, alternative tool last. The response contract is front-loaded where an agent will see it immediately.

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?

Return shape is stated inline even though an output schema exists, the required-filter constraint is explicit, the result cap is bounded, and the adjacent-tool relationship is documented. Nothing needed 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%, so the schema already documents all three parameters including the exact-number semantics of numero and the limite default. The description restates these (limite default 50 / max 500, numero format example) without adding matching or normalization rules the schema omits, 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 ('Busca licitações do Senado') and immediately narrows the query modes to exact number or object text. It also names the sibling senado_contratos as the destination for related data, so an agent can place it in the tool family without reading 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: 'Para o contrato resultante de uma licitação, use senado_contratos' tells the agent which alternative to pick and under what condition. It further states a hard precondition ('Exige ao menos numero ou objeto (sem filtro retorna erro)'), removing the main way an agent would misuse 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so safety is covered. The description still adds real behavioral context beyond the annotations: the source never publishes UF (always null) and it must be resolved via senado_obter_senador, and it explains that bloco/partido fields are conditionally populated. It stops short of describing pagination or rate 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 in the first clause, which is good, but the bulk of the paragraph enumerates return-object fields (tipo, descricao, unidadeLideranca, casa, dataDesignacao…) that a dedicated output schema already covers. Given the output schema exists, this is duplicated content and dilutes the signal.

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 scope, filter semantics, defaults, conditional field population, a known data quirk (null UF) with its workaround, and cross-references to senado_obter_bloco and senado_listar_blocos. An agent has everything needed to call and interpret 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, but the description goes further by explaining the default when no filters are passed and by tying codigoParlamentar and bloco.codigo to the tools that consume them. It adds cross-parameter meaning rather than merely restating 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 ("Lista") and resource ("lideranças do Senado, da Câmara e do Congresso Nacional") and immediately clarifies the entity scope with examples (líderes, vice-líderes). No sibling tool covers this resource, so the agent can identify it unambiguously.

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 filtering guidance (casa, codigoParlamentar, vigente, siglaTipoLideranca) and an explicit default ("sem filtros retorna todas as casas"), plus routing to senado_obter_senador and senado_listar_blocos for downstream needs. It doesn't state when NOT to use it, but no competing sibling exists, so the guidance is essentially complete.

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 safety profile, but the description adds genuinely non-obvious behavioral context: the list is a HISTORICAL composition, a filled `dataDesligamento` means the party left, the current composition is the null entries, and the same party may repeat across distinct adhesion periods. This warns against a real misinterpretation (a party appearing in two blocos at once).

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 scope and return shape, then the historical caveat, then the routing. Slightly long because return fields are enumerated despite an output schema existing, but every sentence carries information and none 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?

For a zero-parameter list tool with an output schema and read-only annotations, the description supplies everything an agent needs: scope, the key semantic trap (historical vs current composition), and sibling routing. Nothing required 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?

The tool takes no parameters, so the baseline is 4; there is no parameter syntax to explain. The description correctly spends no space on inputs.

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 blocos parlamentares do Senado e seus partidos membros') and enumerates the returned fields, so an agent knows exactly what it gets. It also distinguishes itself from siblings by naming what belongs elsewhere (leaderships via senado_liderancas).

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` then detail it via `senado_obter_bloco`, and use `senado_liderancas` for leadership data. Both the when-to-use and the alternative for a different need 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 cover readOnly/idempotent/openWorld, so the safety profile is handled. The description adds genuine behavior beyond that: the source only contains active committees, so ativa=false returns an empty list, and it enumerates the return shape. It stops short of noting pagination or result-size limits.

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, the ativa caveat, and the usage pointer — all in four dense sentences. The return-shape sentence partially duplicates the available output schema, making it slightly redundant rather than wasteful.

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 carry the safety profile, so the description only needed to add the domain-specific gotcha and the routing hint — both present. Nothing an agent needs to call 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 includes the enum values for tipo, so the schema already documents both parameters. The description mirrors those values and adds the ativa=false empty-result consequence, but adds little else beyond what the schema 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?

States a specific verb and resource ('lista comissões ativas do Senado') and scopes it with the two filter dimensions. It distinguishes itself from committee-related siblings by naming senado_obter_comissao and senado_reunioes_comissao as the consumers of the returned sigla.

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 says when to use it: to discover the sigla required by senado_obter_comissao and senado_reunioes_comissao, routing the agent to the right tools. It also flags a real trap — the endpoint only returns active committees, so ativa=false yields an empty 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 cover safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description still adds real behavioral detail: backfilling against the official `/senador/lista/atual` endpoint, local filtering for `uf`/`partido` versus upstream filtering for name, and accent/case-insensitive partial matching. It stops short of pagination or rate-limit behavior, but that is minor here.

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 and front-loaded: triggers first, then behavior, then parameter guidance, then hand-off to sibling tools. Slightly long for one paragraph, but nearly every clause carries actionable information rather than restating the 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 an output schema already present, the description needn't enumerate return fields yet still summarizes them (`count`, `senadores`, item keys); combined with rich annotations and 100% schema coverage, an agent has everything needed to select and invoke 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 coverage is 100%, so baseline is 3, but the description genuinely adds meaning beyond the schema: it clarifies that `nome` does partial accent-insensitive matching and is the path to obtaining a `codigo`, while `uf`/`partido` filter locally and `emExercicio` defaults to true as the primary set selector.

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 sitting senators or a specific legislature) with scope, and explicitly distinguishes itself from siblings by pointing to senado_senadores_afastados for non-sitting senators and to senado_obter_senador for detail lookup.

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

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

Front-loads literal user phrasings that trigger the tool, names the state-selection parameters (`emExercicio`, `legislatura`), describes the search fallback ('use quando você só tem o nome e precisa do codigo'), and explicitly routes elsewhere for out-of-office senators.

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 safety is covered. The description adds the default value behavior of `casa` and the shape/content of the response, which is useful operational context 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?

Four compact sentences, front-loaded with purpose and scope, with the sibling redirect at the end. The return-shape sentence is slightly redundant given an output schema exists, but nothing 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?

For a single-optional-param list tool with an output schema and full annotations, the description covers purpose, parameter meaning, default, response contents and the nearest sibling. 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% with an enum, so the baseline is 3. The description expands the enum meaning ("Mesa do Senado Federal" vs "Mesa do Congresso Nacional") and states the default explicitly, adding modest meaning beyond the terse 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 description names a specific verb ("Lista") and resource ("membros da Mesa Diretora") and enumerates the roles covered (presidente, vice-presidentes, secretários). It explicitly distinguishes itself from the sibling tool senado_liderancas, 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?

It gives an explicit alternative and the condition for it: "Para lideranças partidárias use senado_liderancas." That is clear routing guidance, though it covers only one exclusion rather than a full when-to-use/when-not-to-use map.

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 read-only/idempotent/safe, but the description adds substantial behavioral context beyond them: the exact return shape, the empty-result contract (totalBlocos 0 with aviso), transcript coverage/timing rules, and the aviso cut-off signal for pagination.

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, coverage, modo behavior, id acquisition, and the alternative tool. Every sentence carries information, though the paragraph is dense and could be broken into shorter units.

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 7-param tool: it covers id sourcing, mode selection, pagination, filtering, empty-result handling, coverage limits, and the media alternative. Nothing an agent needs to invoke it correctly is missing, despite an output schema already existing.

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 adds cross-parameter interplay and per-block output fields (trecho 200 chars, caracteres, linkAudio, intervalo) and clarifies orador as partial-content name search and sequenciaFim as modo=texto-only. It mostly reinforces rather than exceeds the schema's own param docs.

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 (official transcription of plenary/committee sessions in sequential blocks) and immediately distinguishes scope from the sibling by naming senado_videos_taquigrafia for media. An agent can identify the tool 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 (retrieve transcript given an id), how to obtain the id (senado_agenda_plenario/senado_resultado_plenario or senado_reuniao_comissao), when-not (joint/cancelled/solemn sessions lack notes; media goes to senado_videos_taquigrafia), plus pagination guidance via sequenciaInicio.

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 beyond them by disclosing error behavior ('Bloco parlamentar não encontrado'), null semantics for dataExtincao, and the crucial historical-composition nuance (filled dataDesligamento = already 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?

One dense but front-loaded block: purpose first, then return shape, then the interpretation rule for the historical field, then the prerequisite and error case. No filler sentences.

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-explained, yet the description still supplies the semantics an agent needs (current vs. historical composition, error on bad code). 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 real value on the single parameter: where to source it (senado_listar_blocos) and what happens when it is invalid.

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 ('Obtém detalhes de um bloco parlamentar específico pelo seu código') and clearly distinguishes itself from the list-oriented sibling senado_listar_blocos, which it explicitly names as the way to obtain the identifier.

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 to fetch `codigo` first via `senado_listar_blocos`, effectively routing lookups to the sibling. It does not spell out when NOT to use this tool, but the sequencing guidance is explicit and actionable.

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 adds real behavioral context beyond them: `finalidade` is only populated for temporary colegiados and comes back null with an `aviso` for permanent ones, and the sigla is internally resolved to a numeric code.

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 verb, resource, and key parameter, and the `finalidade` caveat earns its place. However, the long brace-delimited field enumerations for both sections largely duplicate the existing output schema, adding length without adding 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 two-parameter, read-only lookup with annotations and an output schema, the description covers purpose, lookup key, section semantics, return shape, a non-obvious null-field caveat, and the sibling used for discovery. 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 baseline is 3, but the description goes further than the terse schema strings by spelling out what each `secao` value actually returns and clarifying the internal sigla→código resolution. This meaningfully exceeds the schema's own 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 dados de uma comissão') and the lookup key ('pela `sigla`'), immediately distinguishing it from the listing sibling. It also names the sibling to use for discovery, so an agent can separate detail-lookup from enumeration 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 routes the agent: 'descubra-a via `senado_listar_comissoes`', which is exactly the alternative-tool guidance needed. It also documents the default for `secao`, but offers no explicit when-not-to-use condition (e.g., when the membros section is preferable), 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 readOnly/idempotent/openWorld/destructive=false, so the 'somente leitura, sem efeitos colaterais' line is largely redundant. The description does add real behavior: nonexistent codigo returns a 'Norma não encontrada' error rather than an empty object, and absent fields come back null. That error/return semantics is valuable 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-loads purpose and routing well, but enumerates the full return field list that the output schema already provides, and restates the read-only trait that annotations cover. Slightly over-long but no sentence is fully 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?

With an output schema present, the description needn't explain returns, yet it still covers routing, error behavior, and the codigo-vs-numero distinction. Everything an agent needs to call this correctly is 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 description coverage is 100% and the schema already explains that codigo is the internal id, not the law number. The description reinforces the same point and adds the workflow hint to fetch it first, but adds no new syntax or constraint 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?

States a specific verb and resource ('Obtém o detalhe de uma norma federal já promulgada pelo seu codigo interno') and explicitly differentiates itself from the sibling senado_buscar_legislacao. An agent can select 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?

Explicit routing: get the codigo first via senado_buscar_legislacao, and use senado_buscar_legislacao to locate norms by type/number/year; this tool only serves the detail of an already-identified norm. When-to-use and the alternative 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 declare this a safe, idempotent, open-world read, so the bar is lower. The description adds real behavioral context beyond that: truncation keeps the most recent items, an 'aviso' is included when truncated, and textos are returned most-recent-first.

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 a dense enumeration of section behaviors. It is long but nearly every clause carries information an agent needs; structure is a single paragraph rather than cleanly separated, which slightly hurts scannability.

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 and annotations cover the safety profile, the description supplies everything else an agent needs: section semantics, field inventories, defaults, truncation behavior, ordering, and the prerequisite lookup step. 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 baseline is 3, but the description goes further by expanding what each secao enum value returns (distinct field sets for detalhe/tramitacao/textos). This meaningfully exceeds the schema's terse enum gloss and limit note.

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 dados de uma matéria') and resource, and immediately differentiates itself from siblings by routing to senado_buscar_materias for the required codigoMateria. An agent can tell what this tool fetches and how it relates to the search tool 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 names the alternative tool and the condition for using it ('Obtenha o codigoMateria via senado_buscar_materias'), establishing a clear two-step workflow. It also implies usage via the secao breakdown, but gives no explicit when-not-to-use 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description's extra value is the shape of the returned process state (situacaoAtual, deliberacao, normaGerada), but that overlaps the output schema. Adds modest context beyond annotations, so a 3 is appropriate.

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 in the first clause and follows with usage routing. The long enumeration of return fields is mildly verbose and partly duplicates the output schema, but the structure is logical and nothing is misleading.

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?

Purpose, prerequisite, and sibling routing are all present, and an output schema exists so return values needn't be spelled out (though they are). The definition is complete enough for an agent to call this 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?

The schema already documents idProcesso at 100% coverage, so the baseline is 3. The description adds practical meaning by telling the agent where to obtain the id (search tools), which is parameter-relevant guidance not 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 ("Obtém detalhes completos") and resource ("processo legislativo específico") keyed by an id. It explicitly distinguishes itself from the sibling senado_processo_detalhe, which handles emendas/relatorias/prazos, so an agent can route correctly.

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 ("Obtenha o `idProcesso` antes via senado_search_processos ou senado_buscar_materias") and names the alternative tool plus the condition that selects it (emendas, relatorias, prazos → senado_processo_detalhe). 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds non-obvious behavior on top: nonexistent codes produce an error rather than an empty record, and `emExercicio` is derived and can be null (never asserted) when mandates cannot be read. These are exactly the edge cases an agent needs and they are not recoverable from 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?

Dense but front-loaded: purpose first, then semantics, then error behavior, then routing to siblings. It runs long and restates the returned field list, but every sentence carries usable information and nothing is 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 one-parameter read tool with a full output schema, the description supplies prerequisite, error behavior, and null semantics, so nothing an agent needs is missing. Enumerating the return fields is partially redundant against the output schema but does not harm completeness.

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 parameter is fully documented in the schema, so the baseline is 3. The description earns an extra point by explaining how to obtain the value and what a nonexistent value yields, adding operational meaning beyond the schema's field description.

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 ('Obtém o detalhe biográfico de um senador específico') and enumerates the returned payload. It explicitly contrasts itself with senado_listar_senadores (retrieval of the code) and senado_senador_historico (filiações, profissões, licenças, comissões), so an agent can distinguish it from siblings 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?

Names the prerequisite ('Requer codigoSenador') and tells the agent exactly how to satisfy it (via senado_listar_senadores com filtro `nome`), plus a clear when-not: other senator data belongs in senado_senador_historico. Both the entry path and the exclusion are 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add context — and it does substantially: dual-code-space acceptance, divergent return shapes per code type, the temporal window scan cost, and the error-not-empty-list contract. These are non-obvious behavioral traits no annotation conveys.

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 code semantics, returns, window, and the warning. Every sentence carries necessary information given the dual-code complexity, but it is delivered as one dense paragraph rather than being broken up, slightly reducing 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?

An output schema exists, so return values needn't be spelled out, yet the description still signals the two possible shapes. Combined with annotations covering safety, the description leaves nothing an agent needs to call this correctly, including the tricky failure and window behaviors.

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 exceeds that by explaining the two code spaces, giving examples for each, and clarifying that both are accepted and map to sibling tools' output fields. It adds meaning beyond the schema, though the schema already documents the core parameter semantics.

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 ('Obtém detalhes de uma votação de plenário') and scope ('incluindo votos nominais'). It explicitly distinguishes itself from siblings by name (senado_search_votacoes, senado_votacoes_senador, senado_votacao_comissao, senado_orientacao_bancada), so 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 (fetch a specific plenary vote by either code), when to supply `ano` (votes older than ~12 months), and when-not-to-use (codes from senado_votacao_comissao and senado_orientacao_bancada belong to other numbering spaces and are invalid here). The routing conditions are fully specified.

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/non-destructive/openWorld, so safety is covered. The description adds real behavioral semantics beyond that: the note that the ofício is the post-approval execution document whose date differs from the budget year, and that the base covers multiple years. It does not cover rate limits or failure modes, but the domain semantics it supplies are substantive.

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, but the body is a single dense run-on paragraph enumerating the full return payload for both modes (`{ tipo, count, emendas }`, `autor`, `codigoAutor`, `quantidadeEmendas`, `materia`, `tipoPl`, `dataOperacao`, `ativo`, ...), which largely restates the output schema and inflates length. It is informative but over-stuffed rather than 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 read-only, dual-mode query tool with an output schema present, the description covers everything an agent needs: mode selection, the year filter caveat, pagination, the detail flag, and the routing to the sibling for internal Senate budget data. 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?

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining that `ano` filters the oficios mode by the amendment's budget year (and is recommended), that `limite`/`pagina` drive pagination, and what `incluirEmendas: true` unlocks (favorecido, CNPJ, nota de empenho). That meaning is not fully spelled out 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 resource (emendas parlamentares ao orçamento da União) and explicitly splits it into two documented modes (proposição vs execução) tied to the `tipo` parameter. It also names the sibling it is not (`senado_execucao_orcamentaria`), so an agent can separate this from the Senate's internal budget 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 routing rules: use `tipo: emendas` for proposição and `tipo: oficios` for execução, recommends filtering by `ano` because the base spans multiple years, and prescribes `limite`/`pagina` for pagination and `incluirEmendas: true` for per-emenda detail. It even states when to use a sibling (`senado_execucao_orcamentaria`) instead.

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