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.