Dados Abertos Senado BR MCP

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds the return shape, default date, and filtering semantics, which enriches behavioral context without contradicting 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?

Three well-structured sentences pack purpose, parameters, return format, and alternatives with no wasted words. All content earns its 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?

For a read-only listing tool with output schema available, the description is fully sufficient: it covers inputs, outputs, defaults, and sibling distinctions, making the tool self-explanatory.

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 descriptions cover both parameters, but the tool description adds the default value for data (today) and explicitly explains siglaComissao as an optional filter. This surpasses schema-only information.

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?

Description states a specific verb and resource: 'Obtém a agenda de reuniões de todas as comissões numa data'. It also distinguishes from sibling tools by naming explicit alternatives for history and meeting details.

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

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

Provides direct when-to-use guidance: for history use senado_reunioes_comissao, for details use senado_reuniao_comissao with codigo. Also notes default date behavior, clarifying usage without alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: the exact return shape, the default date assumption, and the scope semantics (dia/mes/cn). It also clarifies the distinction between upcoming agenda (this tool) and past results (senado_resultado_plenario), which is essential for correct use. No contradiction with annotations.

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

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

The description is composed of three concise sentences: the main purpose, the return structure, and usage/alternatives. Every sentence earns its place, with no redundant or extraneous information. Key information is front-loaded in the first sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 required parameters), strong annotations, and presence of an output schema, the description is complete. It covers the return structure, default behavior, scope options, and points to related tools for different needs. Since an output schema exists, the description rightly avoids over-explaining return values.

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

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

The input schema already provides 100% description coverage for all three parameters, including formats, defaults, and enum meanings. The description adds a little usage guidance ('Use escopo dia/mes/cn') but does not substantially extend parameter semantics beyond what the schema already specifies, so the 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 uses the specific verb 'Obtém' (obtains) and clearly identifies the resource: the agenda of plenary sessions (Senado or Congresso Nacional), by day or month, including the voting agenda. It explicitly distinguishes itself from sibling tools by naming senado_resultado_plenario and senado_encontro_plenario as alternatives.

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

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

The description provides explicit direction on when to use this tool versus alternatives: 'Para o resultado já apreciado use senado_resultado_plenario; detalhes de uma sessão via senado_encontro_plenario.' It also explains the default behavior (sem data assume hoje) and the meaning of the escopo parameter, giving clear context for correct selection.

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 annotations (readOnlyHint, idempotentHint, etc.), the description discloses crucial behavioral traits: the semantic meaning of 'atual' as 'with process still in progress', the mixing of senators/deputies/ex-parliamentarians, and the possibility of the same person appearing twice with different codes. This context is not available in the annotations and significantly shapes how an agent should interpret 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?

Although the description is relatively long, every sentence carries essential information: the action, the critical semantic warning, the alternative tool, the return structure, the filter details, and the downstream usage. It is well-structured, front-loaded with the primary purpose and the most important caveat, and avoids redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and rich annotations, the description still goes above and beyond by covering edge cases like duplicate codes, misleading semantics, and integration with other tools. It provides all necessary context for an agent to select and invoke the tool correctly, leaving no ambiguity about behavior or return values.

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

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

The input schema already provides full coverage (100%) for the three parameters with descriptions, so the baseline is 3. The description adds extra semantics by clarifying that `nome` performs a partial accent-insensitive search and by restating the default/maximum for `limite`. It also links the result fields to other tools, which helps the agent understand the parameter outputs, but the parameter-related additions are modest.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Lista parlamentares autores de processos em tramitação', which clearly specifies the verb (list), resource (parliamentary authors of in-progress processes), and ordering (by production). It also distinguishes this tool from the closest sibling by explicitly warning not to use it as a list of current senators, which is a clear differentiator.

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

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

The description explicitly states when not to use the tool: 'não use como lista de senadores em exercício' and directs to the alternative `senado_listar_senadores`. It also provides downstream usage instructions, telling the agent to use the returned `codigo` in `senado_obter_senador` or `senado_search_processos`, which is concrete guidance on next steps.

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?

As anotações já cobrem readonly, idempotência e openWorld. A descrição acrescenta comportamentos específicos: erro determinístico sem filtros, ausência de paginação, significado de count (0 sem erro), campos com null, e a natureza de consulta ao vivo. Isso enriquece a transparência, embora não detalhe autenticação ou limite de taxa.

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?

O texto é relativamente longo, mas cada sentença contribui com informação relevante: propósito, filtros, comportamento de erro, formato de retorno, relacionamento com outras ferramentas. A estrutura é organizada, com a ideia principal no início e detalhes progressivos, sem redundâncias graves.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A descrição cobre todos os aspectos necessários para uso correto: finalidade, escopo, requisitos de filtro, formato de retorno (mesmo havendo output schema, explica o significado de count e campos null), comportamento de erros e ferramenta de continuação. É completa para a complexidade da operação.

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?

Apesar da cobertura do schema ser 100%, a descrição vai além ao explicar o modo AND entre parâmetros, a obrigatoriedade de ao menos um filtro (com consequência de erro), e a diferença de formato da data entre consulta (AAAAMMDD) e retorno (ISO AAAA-MM-DD). Isso acrescenta semântica de uso que não está explícita no 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?

A descrição usa o verbo específico 'Busca', identifica claramente o recurso (normas jurídicas federais já promulgadas) e lista os tipos cobertos. Além disso, diferencia-se dos irmãos ao mencionar explicitamente que proposições em tramitação devem ser buscadas em senado_buscar_materias, distinguindo o escopo com precisão.

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?

Fornece orientação direta de quando usar: para normas já promulgadas, e aponta explicitamente a alternativa senado_buscar_materias para proposições em tramitação. Também estabelece a condição de uso de pelo menos um filtro, explicando o erro determinístico, e recomenda o encadeamento com senado_obter_legislacao.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, covering the safety profile. The description adds behavioral details beyond those: default limit of 100 with max 500, truncation includes an 'aviso', default ordering by dataApresentacao to favor recent items, and the requirement to inform at least one criterion. These are useful but some (limit default) are also present in the schema, so it's not a 5.

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

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

The description is a single dense paragraph but every sentence serves a purpose: scope, usage guidance, return shape, cross-tool integration, limit/truncation, and examples. Code-formatted tokens aid scanning. It's slightly longer than necessary and could be split into sections, but it remains tight and front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters, output schema, many siblings), the description is remarkably complete: it specifies the return shape ({count, total, materias[]}), the fields in each item, the truncation 'aviso', ordering defaults, and how to chain to senado_obter_materia. It also provides two concrete examples covering both keyword and exact-number searches. No significant use case is left unexplained.

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?

While schema coverage is 100%, the description adds meaningful semantics beyond individual property definitions: it demonstrates how to combine parameters for a 'recent matters' query, explains that the output field 'codigo' corresponds to 'codigoMateria', and clarifies acceptable date formats. The worked examples show realistic usage patterns that the schema alone doesn't convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb 'Busca' and enumerates searchable criteria (tipo, número, ano, palavras-chave, autor, período, situação), making the tool's scope unmistakable. It also distinguishes itself from the sibling senado_obter_materia by explicitly mapping the returned 'codigo' to detail retrieval, which clarifies what this tool does vs. the detail tool.

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

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

The description provides explicit when-to-use guidance for 'matérias recentes sobre X' (combining palavraChave, ano, date range, ordenarPor, ordem, limite baixo) and a clear when-not-to-use: use senado_obter_materia only when details/tramitação/textos are requested. It also states that at least one criterion must be informed and says calling details isn't needed for listing, offering concrete alternatives and exclusions.

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

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

Annotations already mark this as read-only and non-destructive, but the description adds substantial behavioral context: it explains the default mode (por-senador), ordering (descending total), the effect of agruparPor (groups ranked by sum, each with mini-distribution), the behavior without agruparPor (individual distribution plus top/bottom), and the limite cap with aviso truncation. No contradiction with annotations.

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

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

The description is long but information-dense, with every sentence contributing actionable details about modes, outputs, filters, and parameters. It is front-loaded with the core purpose, but the lack of paragraph breaks makes it harder to scan. The comprehensiveness is justified for a tool with 11 parameters and multiple modes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the presence of an output schema, the description covers all essential aspects: return shapes for each mode (agregado[], grupos[], despesas[], distribuicao, top/bottom), ordering, defaults, filters, limits, and the relationship between parameters. It also explains when to use estatisticas vs. aggregation, making it self-sufficient for an agent to select and use 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%, but the description adds critical semantics beyond the schema. It clarifies interactions: modo is ignored when estatisticas=true, agruparPor is only relevant with estatisticas=true, limite has a cap of 100 with a truncation warning, and topN default/max. These relationships are essential for correct invocation and are not evident from the schema alone.

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 clearly identifies the resource (CEAPS expenses of senators) and the timeframe (a year), with an explicit verb implied by the tool's function (query/list expenses). It distinguishes this tool from siblings like senado_orcamento_parlamentar by focusing specifically on CEAPS and detailing its multiple aggregation modes.

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

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

The description provides explicit guidance on when to use estatisticas=true vs. regular modes, differentiates comportamento with agruparPor, and clarifies when aggregates hide distribution details. It also directs users to senado_listar_senadores for obtaining codSenador, giving a clear 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses important behaviors: return shape {id, tipo, secao, count, total, itens}, truncation semantics (count < total), empty section response, invalid combination errors, and the fact that only aditivos may contain a null valor. No contradiction with annotations.

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

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

The description is long but every sentence carries essential information: parameter explanations, return format, edge cases, and cross-tool guidance. It is well-structured, front-loading the core action and then layering details logically.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the rich annotations, the description is complete. It covers return values, truncation, empty results, invalid combinations, and the critical caveat about monetary values. The output schema exists, so return value explanation is a bonus, and the description still adds necessary contextual warnings.

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 semantic meaning by explaining 'tipo' as nature of the record and 'secao' with valid combos, plus the limitation behavior of 'limite'. While some repetition exists, it enriches understanding of the parameters and their interplay.

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 starts with a specific verb+resource+scope: 'Detalha uma seção específica de uma contratação já identificada pelo id.' It clearly distinguishes itself from sibling tools by explicitly stating that senado_contratos and senado_contratacoes_lista are for locating, not detailing.

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

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

The description provides explicit when-to-use guidance, including how to obtain the id via sibling tools and which secao×tipo combinations are valid. It also warns about invalid combinations and the absence of monetary values, giving clear direction for correct tool usage.

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

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

Beyond the annotations, the description discloses the return structure `{ tipo, count, total, registros }`, highlights differing record formats for `menores_aprendizes` (raw, non-normalized) vs others, explains sorting semantics based on upstream id sequence, mentions a truncation warning (`aviso`), and notes empty results for `tipo` without records. No contradiction with annotations.

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

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

The description is information-dense without redundancy: it opens with the core action, then covers return shape, type-specific formats, sorting, pagination, limits/truncation, and ends with an alternative tool pointer. Every sentence earns its 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?

For a list tool with 5 parameters, an output schema, and diverse subtypes, the description covers all key behaviors: return shape, record format variations, order semantics, pagination, truncation, empty-list handling, and the cross-reference to the detail tool. It is fully complete.

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

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

Although schema descriptions cover all parameters, the tool description adds substantive meaning: it maps each `tipo` enum to a specific data source, explains the `ordem` default (desc = most recent first), clarifies `offset` paginates the tail, and describes `limite`'s truncation behavior. This goes well beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists three specific types of procurement records (atas de registro de preço, notas de empenho, menores aprendizes) based on the `tipo` parameter. It distinguishes from the sibling `senado_contratacao_detalhe` by noting the latter is for deeper detail on a specific ata/empenho.

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

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

The description provides explicit guidance: use `tipo` to select the list, apply `filtro` for textual search, control ordering and pagination with `ordem` and `offset`, and cap results with `limite`. It explicitly points to `senado_contratacao_detalhe` for deepening into a specific record, acting as a clear alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context beyond that: it explains the data source (base baixada e filtrada no Worker), the partial accent-insensitive search behavior, the result envelope `{ count, total, contratos }`, the truncation via 'limite' and 'aviso', the mix of subespécies, and the absence of monetary values. No contradictions with annotations.

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

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

The description is longer than average but every sentence carries useful information—search filters, accent behavior, return shape, the no-value warning, and the pointer to the detail tool. It is front-loaded with the core purpose and includes the caveat about missing monetary fields in a prominent 'Atenção' paragraph. Slightly dense, but justified by the tool's complexity.

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 description fully covers the tool's behavior for a complex search endpoint: it explains the queryable fields, the response structure including nested `empresa` object, the `subEspecie` distinctions, the truncation mechanism, and the relationship to senado_contratacao_detalhe. It also warns about a likely data gap (no monetary value), which prevents wasted calls. Given the output schema is not provided separately, this description carries the completeness burden and does so admirably.

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 extra meaning by clarifying that searches on objeto/fornecedor/número are partial and accent-insensitive, and by grouping the filters into a natural-language list. It also repeats the 'limite' default and max, which slightly duplicates schema info, but the partial-match detail and the explicit mention of CNPJ exactness (from schema) enrich the parameter understanding.

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 starts with a specific verb ('Busca') and a clear resource ('contratos administrativos do Senado'), listing all filters (fornecedor, CNPJ, ano, número, objeto, mão de obra). It distinguishes itself from siblings like senado_contratacao_detalhe by explicitly directing the user to use the returned id for details, and it differentiates partial vs. exact search behavior.

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

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

The description provides explicit when-to-use context: it is the filtered search tool for contracts, with partial accent-insensitive matching. It also gives a strong 'when not to' warning—'não gaste chamadas procurando valor'—because the source does not publish contract values. It points to senado_contratacao_detalhe for related data, making the choice of tool and follow-up actions 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 mark the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description goes further by disclosing the exact return shape (`{ periodo, count, discursos }` with field list) and implicitly states that this tool returns metadata rather than full text, since it directs users to senado_discurso_texto for the full text. While it doesn't discuss pagination or limits, it provides solid behavioral context beyond 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?

Two dense sentences front-load purpose, then return shape, then alternatives. No filler or redundant restatement of annotations; each clause contributes useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple two-parameter schema, strong annotations, and the fact that an output schema exists, the description is complete: it names the parameters and their format, states the output structure, and points to sibling tools for adjacent needs. It does not leave significant gaps for an agent to guess.

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 provides both parameter names, descriptions, patterns, and required flags, so coverage is 100%. The description repeats the required date format and emphasizes that the parameters define the period, but does not add substantive semantics beyond what the schema conveys (e.g., inclusivity or max range). Thus a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with 'Lista todos os discursos realizados em plenário num período de datas', which names a specific verb (Lista), resource (discursos em plenário), and scope (date range). It also distinguishes itself from sibling tools by explicitly directing users to senado_discursos_senador for individual parlamentar speeches and senado_discurso_texto for full text, making its purpose unambiguous.

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

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

It provides clear usage context: use this tool to list all plenary speeches within a required date range, and explicitly names alternative tools for filtering by parlamentar or retrieving full text. The final sentence gives concrete when-to-use-versus-alternative guidance, so an agent can decide correctly.

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

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

Goes well beyond annotations by disclosing no pagination, empty response format, and the 30-day default window for `discursos` when dates are omitted. These are critical behaviors not inferable from readOnlyHint or idempotentHint.

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 long but every sentence earns its place, covering purpose, variants, output shape, warnings, and cross-references. It is well-structured with a clear warning section and no redundant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers output structure, edge cases (empty results), and important gotchas (30-day limit). Despite the tool's complexity, the description provides sufficient context for an agent to select and invoke it correctly without needing the output schema.

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

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

Even with 100% schema coverage, the description adds deeper meaning: `tipo` changes the upstream source and content, and date parameters interact with `tipo` to affect the returned range. This clarifies usage implications beyond the schema's field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists a senator's pronouncements with period and house filters, and explicitly distinguishes `discursos` vs `apartes`. It differentiates from siblings by referencing `senado_discursos_plenario` and `senado_discurso_texto`.

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

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

Provides explicit when-to-use guidance: obtain `codigoSenador` via `senado_listar_senadores`, full text via `senado_discurso_texto`, and all senators via `senado_discursos_plenario`. Also explains when to provide explicit date ranges vs. omitting them.

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?

The annotations already mark the operation as read-only and idempotent. The description goes beyond by disclosing that the text is complete (not truncated or paginated), can be tens of KB, and that a nonexistent code or a speech without text returns an error. This gives the agent concrete expectations about size and failure modes.

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 compact—four sentences in Portuguese—and each sentence adds distinct value: purpose, return shape/size, error behavior, and usage context. It is front-loaded with the primary function and avoids repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter retrieval tool, the description covers all essential aspects: what it returns, how to get the input, error conditions, and alternatives. The existence of an output schema further underscores that return values are well-defined, and the description still explains the key return characteristics. It is complete.

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

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

The input schema already provides a thorough description of codigoPronunciamento, including its source ('campo codigo de senado_discursos_senador ou senado_discursos_plenario') and uniqueness. With 100% schema description coverage, the description's mention of how to obtain the code is redundant but harmless; it adds no new parameter-level semantics. 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 clearly states the tool's function: 'Obtém o texto integral de um único pronunciamento' (Gets the full text of a single speech). It specifies the resource (pronunciamento) and distinguishes it from sibling list/filter tools by noting this one returns the full text of an already identified speech. This makes the purpose unambiguous.

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

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

The description provides explicit usage guidance: obtain the codigoPronunciamento first via senado_discursos_senador or senado_discursos_plenario, and use those tools instead when only listing/filtering is needed. It even says 'Para apenas listar/filtrar discursos... use aquelas ferramentas' (to just list/filter, use those tools), giving a clear when-not-to-use instruction.

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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description aligns with this by describing a read-only ranking operation. It adds valuable behavioral context beyond annotations: no pagination, count=0 for empty commissions, ordering by quantidade desc, and codigoParlamentar being ignored in relatoria mode.

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

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

The description is dense but every sentence earns its place: it front-loads the core purpose, then covers output shape, edge cases, parameter behavior, and cross-references to sibling tools. There is no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, the description is highly complete: it covers the return shape, sorting, pagination absence, zero-count behavior, parameter-specific effects, and how to obtain necessary inputs from related tools. The presence of an output schema lowers the burden for return-value details, but the description covers them anyway.

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 the parameters. The description adds narrative framing (e.g., tipo as the 'eixo' and codigoParlamentar's interaction with tipo), which reinforces meaning but does not significantly extend the schema's explicit parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Ranqueia parlamentares pela quantidade de matérias numa comissão', clearly stating what the tool computes. It also distinguishes itself from sibling tools like senado_buscar_materias by explicitly noting the tool returns counts/ranking, not the list of matérias.

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

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

Provides explicit guidance: use senado_buscar_materias when you need the actual list of matérias, and points to senado_listar_comissoes and senado_obter_senador for resolving IDs. It also clarifies the default tipo and the special behavior of codigoParlamentar, making it clear when the tool is appropriate.

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 and idempotent, and the description adds meaningful behavioral context beyond them: the status lifecycle (aberta vs. encerrada), the limitation that consultations closed before first ingestion are not captured, and the sorting/criteria logic per mode. No contradiction with annotations.

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

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

The description is dense and information-rich, front-loading the core purpose and then systematically covering modes, status, defaults, and sibling distinctions. It is longer than typical but every sentence adds value; no filler, though a slightly tighter structure could make it easier to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, annotations, and output schema presence, the description covers all essential aspects: modes, parameter semantics, status subtleties, return format, and relationship to sibling tools. It leaves no significant ambiguity about what the tool does or when it should be used.

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?

Input schema provides 100% parameter coverage with descriptions, so the baseline is 3. The tool description adds semantic nuance by explaining what consenso and polarizada mean operationally and how percentualMinimo and margemPolarizacao drive the ranking. This extra context justifies a 4, though it mostly reinforces schema details.

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 clearly states the tool analyzes the complete set of open e-Cidadania consultations by citizen agreement, with specific verbs and a precise resource. It also explicitly distinguishes itself from senado_ecidadania_consultas_votos (historical) and senado_ecidadania_obter_consulta (detail), making it unmistakable which tool to use.

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

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

The description gives explicit when-to-use guidance: "É esta a ferramenta para 'consultas mais votadas', ranking ou panorama ATUAL" and contrasts with the historical sibling tool. It also explains when to use consenso vs. polarizada modes and the meaning of status values, so the agent can select the right parameters.

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, and non-destructive behavior. The description adds meaningful context beyond these hints: the source CSV marks status as `Descontinuado` (so data is treated as archive, not current opinion), and it mentions weekly updates and ~15k items. This deepens the agent's understanding of data freshness and interpretation.

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 that front-loads the core purpose, then usage boundaries, return shape, and parameter behavior. Every sentence contributes useful information without redundancy, using bold text and semicolons to improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers tool scope, usage exclusions, data source and freshness, return format, and parameter semantics. With output schema and annotations present, nothing critical is missing for an agent to correctly select and invoke the tool. The archive-vs-current distinction and UF-specific behavior are especially valuable.

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

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

Although the schema provides descriptions for all 5 parameters (100% coverage), the description adds significant semantic value. It explains how `uf` affects ranking and adds a `recorteUf` field to results, clarifies that `materia` filters by numeric code or text fragment, and specifies defaults for `ordenarPor` and `limite`. This goes well beyond the schema field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as providing historical e-Cidadania public consultation votes with UF breakdown, using specific language about the resource and scope. It explicitly distinguishes itself from sibling tools `senado_ecidadania_consultas_analise` and `senado_ecidadania_listar_consultas`, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: only for the historical archive or votes by state (UF). It also states when NOT to use it (current opinion/rankings) and names the alternative tool `senado_ecidadania_consultas_analise`. It further contrasts with `senado_ecidadania_listar_consultas` to clarify the archive nature.

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 annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses important behavioral traits: the status lifecycle ('Toda consulta entra como aberta; quando a matéria sai de tramitação ela passa a encerrada'), the expanding set of encerrada/todas over time, and the limitation that consultations closed before first ingestion are not captured. This is meaningful behavioral context not present in annotations.

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

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

The description is dense and front-loaded, starting with purpose, then return shape, then behavioral details, and ending with sibling tool routing. Each sentence adds value (e.g., the lifecycle and pre-ingestion closure caveat), but it is longer than strictly necessary and the return-shape listing overlaps with the output schema. Still, it remains well-organized without wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the comprehensive schema, annotations, and output schema, the description adds the essential context an agent needs: scope, behavioral nuances, limitations, and clear routing to related tools. It does not miss critical information for deciding when to invoke and what to expect, making the tool well-specified for autonomous use.

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 covers 100% of the three parameters with rich descriptions, including the default for limite, pagination via pagina, and the status parameter's meaning and caveat. The description only repeats the limite default and status evolution, adding no new parameter semantics 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 uses a specific verb ('Lista') and a clear resource ('consultas públicas do e-Cidadania'), and states it returns the complete set of open consultations (~7,7 mil). It distinguishes from siblings by mentioning alternative tools like senado_ecidadania_obter_consulta for detail and senado_ecidadania_consultas_analise for analytics, making its unique scope explicit.

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

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

The description explicitly tells when to use this tool vs alternatives: 'Para o detalhe de uma consulta chame senado_ecidadania_obter_consulta com o id; para recortes analíticos (consenso/polarização) use senado_ecidadania_consultas_analise.' It also explains the status behavior (open consultations become closed when matters leave review), providing context for when the returned set changes.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the corpus is persisted in D1, updated weekly, includes thousands of events including encerrados, and exactly what the response contains (`{ count, eventos }` with fields). It also explains ordering behavior for ranking by comments, adding valuable 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 a dense single sentence with semicolons, packing purpose, scope, return shape, fields, filters, and ordering into one breath, plus a second sentence for the alternative. It is efficient but could be slightly better structured, yet every clause earns its 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?

For a tool with 5 optional parameters, rich annotations, and an output schema, the description covers the full use case: what data is returned, how to filter, how to order for rankings, the default limit, and when to switch to the detail tool. Nothing essential 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 100% schema coverage, the baseline is 3; the description elevates it by explaining how the parameters work together, e.g., that limite defaults to 20 and that ranking by comments requires setting ordenarPor and ordem together. It doesn't fully restate each schema description but adds contextual usage that the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb 'Lista' and resource 'eventos interativos do e-Cidadania' with concrete types (audiências públicas, sabatinas, lives), immediately distinguishing it from sibling list tools for consultas and ideias. It also contrasts with the detail tool by pointing to senado_ecidadania_obter_evento for full details.

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

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

It explicitly states this returns the complete set of events including closed ones, and gives direct guidance for filtering by status/comissao/limite and for ranking by comments using ordenarPor and ordem. It names the alternative for detail retrieval (senado_ecidadania_obter_evento), satisfying the when-to-use vs alternative requirement.

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 annotations (read-only, idempotent, non-destructive), the description discloses important behavioral traits: the corpus is persisted in D1, updated weekly, contains ~114k ideas including closed and converted ones, and returns only summary fields with `autor`/`dataPublicacao` as `null`. It also clarifies that sorting by `data`/`comentarios` is only supported in the detail, not in this corpus.

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?

Although somewhat long, the description is dense and well-structured: it opens with the core purpose, then covers data source, return shape, filters, sorting, and the sibling detail tool. Every sentence adds information, and formatting with bold and backticks aids readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and annotations already cover safety, the description is complete: it explains the response shape, field availability, status values, default limit, sorting behavior, and the appropriate sibling for detail. There is no obvious missing context for an agent to invoke and interpret 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?

Schema description coverage is 100%, yet the description adds significant semantic value by showing how to use parameters together: 'Para um ranking das mais apoiadas, ordene por apoios (ordenarPor: "apoios", ordem: "desc")'. It also explains that `data` and `comentarios` sorting options are not available in this listing, which is not obvious from the schema alone.

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 clearly identifies the tool as listing citizen-proposed legislative ideas from e-Cidadania, using a specific verb and resource. It explicitly distinguishes itself from the sibling tool for retrieving a single idea: 'Para o detalhe completo ... chame senado_ecidadania_obter_ideia com o id.'

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

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

The description gives explicit usage context: when you need the complete corpus, filtering by status, or sorting by support count. It also prescribes the alternative tool for full idea details, and warns that fields like `autor` and `dataPublicacao` are only available via the detail endpoint, effectively telling users when not to use this listing.

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 destructiveHint, but the description adds valuable behavioral context: it discloses that `dataAbertura`/`dataEncerramento` (and `comissao`/`linkMateria`) always come null due to portal limitations, and that `comentarios` is also null. This goes well beyond the structured annotations.

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

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

The description is four sentences, each contributing essential information: the primary action and return fields, the always-null behavior, the absence of comments, and the id source. It is front-loaded with the main purpose and contains no filler or redundancy.

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 there is only one parameter, an output schema exists, and annotations cover safety traits, the description completes the picture by detailing null-field behavior, status interpretation, and prerequisite id retrieval. This is fully sufficient for an agent 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?

The schema covers 100% of the parameter (`id`) with a basic description. The tool description adds meaning by instructing where to get the `id` (from list or analysis tools) and by explaining the return object, which reinforces the parameter's role. This is a useful addition beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states exactly what the tool does: 'Obtém o detalhe de uma consulta pública específica' (gets the detail of a specific public consultation). It uses a specific verb and resource, and distinguishes itself from sibling list tools by emphasizing specificity and referencing how to obtain the id from the list tools.

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

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

The description explicitly instructs to obtain the `id` via `senado_ecidadania_listar_consultas` or `senado_ecidadania_consultas_analise`, providing a clear prerequisite and usage flow. While it doesn't explicitly list when not to use it, the contrast with list tools is implicit and clear enough.

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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses critical behaviors: unfilled fields return null, a non-existent id returns an error, 'videoUrl' is a YouTube embed or null, and 'pauta' is limited to 15 items. This adds valuable context for the agent's expected runtime 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?

The description is structured in four sentences, beginning with the purpose and then detailing the return object, null/error behavior, and alternatives. While somewhat lengthy, each segment provides necessary information without fluff. It could be tightened but remains focused.

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 description fully covers the necessary context for a read-only detail-fetching tool: prerequisites, return fields, error cases, and the alternative tool for lighter queries. With an output schema and annotations already present, the description adds the remaining context an agent needs to 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?

The schema already covers the single parameter 'id' with 100% description coverage, including its source ('campo `id` de senado_ecidadania_listar_eventos'). The description repeats the instruction to obtain the id first, adding no new semantic detail about the parameter itself. Baseline 3 is appropriate given the schema's high coverage.

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 the tool's purpose with a specific verb and resource: 'Obtém o detalhe completo de um evento interativo do e-Cidadania (audiência, sabatina, live).' It distinguishes itself from the sibling tool 'senado_ecidadania_listar_eventos' by focusing on full details versus listing/ranking.

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

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

The description provides explicit usage guidance: 'Obtenha o `id` antes via senado_ecidadania_listar_eventos' states the prerequisite, and 'Para apenas listar/rankear eventos (sem descrição/pauta/convidados) use senado_ecidadania_listar_eventos, não esta' clearly indicates when not to use this tool and directs to 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?

Beyond the read-only, idempotent, and non-destructive annotations, the description discloses critical behavioral quirks: the truncation of `descricao` to ~2000 characters, the `plConvertido` field meaning, and especially that `comentarios` is always null because the idea page has no comment feature. This prevents agent confusion and provides context annotations cannot convey.

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

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

The description is concise and front-loaded with the main purpose. It lists fields efficiently and spends the remaining sentences on important caveats (truncation, null comments) and workflow. The field enumeration is slightly verbose but each element adds clarity, earning a 4 rather than 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?

Given the tool's simple nature (single ID parameter), the description covers all essential aspects: purpose, return object shape, special quirks, and the prerequisite workflow. With good annotations and an output schema present, nothing critical is missing for an agent to invoke 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 describes the `id` parameter fully (integer, min/max, 'ID da ideia legislativa') with 100% coverage. The description adds value by telling the agent to obtain the id from `senado_ecidadania_listar_ideias`, which enriches the semantic meaning beyond the raw schema. Baseline 3 plus this extra workflow detail justifies a 4.

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 clearly states the tool's purpose: 'Obtém o detalhe de uma ideia legislativa do e-Cidadania.' It specifies the resource (ideia legislativa) and differentiates itself from sibling tools like listar by focusing on detail retrieval. The return fields are enumerated, leaving no ambiguity about what the tool does.

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

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

The description provides explicit workflow guidance: 'Obtenha o `id` antes via `senado_ecidadania_listar_ideias`.' This tells the agent exactly when to use this tool (after obtaining an ID via the list tool) and points to the correct sibling alternative for getting the ID. It establishes clear context for usage without ambiguity.

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/openWorld/idempotent annotations, the description reveals substantial behavior: it analyzes the full set of open consultations and ideas, applies default filters (minimoParticipacao=500, evitarPolarizacao/evitarConsenso=true, apenasEmTramitacao=true meaning only open consultations based on real status), returns at most 10 suggestions ordered by participation, and distinguishes count from totalQualificados. No contradiction with annotations.

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

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

The description is appropriately dense, front-loaded with the primary purpose, then methodically details the return format, optional criteria, and follow-up tools. Every sentence contributes essential information without redundancy, making it efficient despite being longer than average.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one optional nested parameter and an output schema, the description is remarkably complete: it specifies the exact return object fields, criteria behaviors, defaults, limits (up to 10), ordering, and points to related tools for deeper investigation. An agent could invoke this tool correctly with no further context.

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

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

Although the schema already describes all parameters at 100% coverage, the description adds meaning by explaining how the nested `criterios` object controls the selection logic (e.g., defaults and their effect) and clarifies that `apenasEmTramitacao` actually relates to open consultations rather than the schema's wording 'matérias em tramitação'. This enriches the agent's understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: it suggests topics for a monthly public e-Cidadania poll by analyzing open consultations and ideas, selecting those with highest citizen engagement. It specifies the output structure and distinctly positions itself from siblings by offering a synthesized recommendation rather than raw listing, and even points to related detail tools for follow-up.

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

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

The description explicitly tells the agent when to use this tool (to generate poll topic suggestions) and when to use alternatives: 'Para investigar uma sugestão, use senado_ecidadania_obter_consulta ou senado_ecidadania_obter_ideia conforme o tipo.' This provides a clear when-not and names specific alternatives, meeting the highest bar.

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?

The description explains the return structure `{ count, total, empresas }` and that each company includes `contratos` limited to 30 numbers, plus `totalContratos` – behavioral details not captured by annotations. It also reveals the constraint that at least one identifier is needed due to the large database.

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 three sentences that efficiently cover the search's purpose, output format, required inputs, and next steps, with no redundant wording.

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 search tool, the description provides all necessary information: search method, expected output, parameter limitations, and pointers to related tools, making it self-sufficient given the output schema and annotations.

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?

While the schema fully documents each parameter, the description adds the essential constraint that `nome` or `cnpj` must be provided (since both are optional in the schema), and confirms the meaning of partial search. This compensates for the schema's lack of required-field enforcement.

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 clearly states the tool searches for companies that contract with the Senate, with specific search criteria (name or CNPJ/CPF), distinguishing it from other Senate tools like senado_contratos which likely handles contract details.

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

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

It explicitly states that a `nome` or `cnpj` is required because the full base is large, and it directs users to use the returned `id` or contract number in `senado_contratos` or `senado_contratacao_detalhe` for further details, providing clear alternatives.

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?

The description enriches the annotations by explaining the return structure (`encontro` can be an object or array, possibly empty), the variability of fields by section, and the error condition when `codigo` does not exist. This is beyond the read-only/idempotent hints and provides valuable behavioral detail.

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

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

The description is well-structured and concise, covering the core purpose, output structure, section semantics, edge cases, and input sourcing in a compact paragraph. Every sentence provides relevant information without unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (two parameters, one enum, and several behavioral variations), the description is remarkably complete. It covers return format, possible empty results, error conditions, parameter meaning, and how to obtain the required `codigo`, so the agent can confidently invoke it.

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

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

While the schema already documents the parameters with descriptions, the description adds significant meaning by detailing the semantic effect of the `secao` parameter (e.g., `pauta` returns planned matters, `resultado` returns appreciated items) and by clarifying the `codigo` source. This helps the agent choose the correct parameter values effectively.

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 clearly states the tool's purpose: to retrieve details of a legislative plenary session encounter, returning `{ codigo, secao, encontro }`. It distinguishes itself from siblings by explaining how `encontro` varies by `secao` and by referencing how to obtain the `codigo` via other specific 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?

The description gives practical usage context by explaining the different `secao` options (detalhes, pauta, resultado, resumo) and explicitly instructs to obtain the `codigo` from `senado_agenda_plenario` or `senado_resultado_plenario`. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions, though the guidance is clear.

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

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

Beyond the readOnly/openWorld annotations, it discloses the full return contract: caminho represents superior organs, subordinadas includes ALL descendant units with sigla, nome, and nivel, and it notes the source limitation (official open data API does not publish the complete tree). This adds meaningful behavioral 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 compact and information-dense, with a clear front-loaded definition followed by output semantics, usage examples, alternative tool reference, and data-source caveat. No filler sentences are present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description need not repeat return details, yet it still provides the core output structure, clarifies depth semantics, names the appropriate alternative tool, and explains the data source. This fully equips an agent 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% for both parameters, and the description adds value for `unidade` by giving concrete examples (sigla like 'DGER' or name like 'Diretoria-Geral'). The `limite` parameter is not elaborated in the description, but the schema already defines it adequately.

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 purpose: returning the organizational hierarchy (organograma) of the Senado Federal up to service level for a given unit. It specifies the exact output shape and explicitly contrasts with sibling tool senado_servidores, making differentiation clear.

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 provides explicit usage scenarios: 'Use para responder...' for hierarchy queries, and explicitly directs users needing headcounts or server lists to senado_servidores with subordinadasA. This is strong when-to-use vs. 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses rich behavioral details: how `estatisticas` changes the response depending on `agruparPor`, ordering of aggregated results, automatic selection of the value column, the `limite` default of 100 with an `aviso` when truncating, and the structure of the response envelope. This is far beyond what annotations 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?

The description is dense and highly informative, but it is a single long paragraph without structural breaks (e.g., bullets or headings). Every sentence contributes useful detail, yet readability could be improved. Given the complexity, the length is justified, but a more structured layout would make it clearer.

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 description covers the tool's full behavioral surface: input modes, output envelope, statistics behavior, aggregations, pagination/limits, and exceptions. It also clarifies the relationship to a sibling tool. With an output schema present, the description need not enumerate every return field, so the coverage is complete for this complex tool.

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

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

Although the input schema already has 100% coverage and detailed descriptions, the description adds extra meaning: it explains the interplay between `estatisticas` and `agruparPor`, that `modo` is ignored when `estatisticas=true`, how the analyzed column is chosen automatically, and the semantics of aggregation modes. This significantly enriches the schema's formal parameter definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb-resource relationship: it provides budget execution data for the Senate (expenses and own revenues), with clear detail on which measures and time ranges are covered. It also explicitly distinguishes itself from the sibling `senado_orcamento_parlamentar`, making its purpose unambiguous.

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

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

The description offers explicit guidance on when to use this tool and how to combine parameters: it tells users to use `tipo=despesas` with specific `modo` values, `tipo=receitas` with `por-origem`, and to filter by `ano` before requesting `detalhe`. It also names the alternative `senado_orcamento_parlamentar` and explicitly warns not to confuse them.

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 annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true), the description richly discloses behavior: it details the exact return shapes in both estatisticas modes, explains how grouping and ranking work, notes that limite is ignored when estatisticas=true, and clarifies the meaning of top/bottom and mini-distributions. No contradictions with annotations.

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

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

The description is dense but well-structured: it opens with the core purpose, then systematically explains the two operational modes, grouping, return structure, optional filters, and cross-reference. Every sentence earns its place given the tool's complexity, with no fluff or redundancy.

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 description covers all essential aspects: purpose, mode selection, parameter behavior, return shapes, limits, and an alternative tool. Even though an output schema exists, the description explains the response structure and mode-dependent variations, making it complete for an agent to select and invoke the tool correctly in various scenarios.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra value by explaining inter-parameter interactions (e.g., limite ignored when estatisticas=true), the effect of agruparPor on grouping and ranking, and the semantics of topN and default limits. This goes beyond the individual schema descriptions, earning a 4.

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 clearly states the tool lists overtime paid to Senate employees for a given year/month, with a specific verb+resource+scope. It distinguishes from siblings by explicitly naming the alternative tool for complete remuneration (senado_remuneracoes_servidores) and describing its own specialized overtime-focused functionality.

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

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

The description provides explicit when-to-use guidance: it tells the agent to use estatisticas=true for ranking/distribution questions, explains when to use agruparPor with nome/competencia, and names an alternative tool for complete remuneration. This is clear, actionable context for selecting the right mode or falling back to a sibling tool.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds the output envelope ({ count, total, licitacoes }), the raw administrative API origin, the limit default/maximum (50/500), and the error behavior when no filter is provided. This goes well beyond what annotations provide.

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

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

The description is three dense sentences: main purpose first, then output and limit details, then the requirement and sibling alternative. Every sentence earns its place with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description need not enumerate return fields. It supplies the output envelope, limit constraints, minimal filter precondition, and a cross-reference to a related tool, making it complete for a search/list operation.

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 covers all three parameters with descriptions, so the bar is already at baseline 3. The description reinforces semantics by explaining the two filter modes ('número exato' vs 'texto do objeto'), clarifying that one is required despite the schema listing zero required parameters, and restating the limit bounds. This adds meaningful nuance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Busca licitações do Senado', a specific verb and resource, and further specifies search by exact number or object text. It also distinguishes the tool from siblings by directing users to senado_contratos for the resulting contract, making the purpose unambiguous.

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

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

The description states the required input condition explicitly ('Exige ao menos numero ou objeto (sem filtro retorna erro)'), which is crucial since the schema lists zero required parameters. It also names the alternative tool for related needs: 'Para o contrato resultante de uma licitação, use senado_contratos.'

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?

The description discloses a critical behavioral trait beyond annotations: 'A fonte NÃO publica a UF do parlamentar (vem sempre null)', preventing confusion about null values. It also adds context about the default return of all houses when no filters are applied and the use of 'codigo' in another tool.

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

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

The description is front-loaded with the core purpose, and each subsequent sentence adds unique value: return structure, UF null caveat, filter options, and related tool pointers. There is no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, the description covers all essential aspects: output shape, filter semantics, default behavior, known data gap (UF null), and related tools. It is complete enough that an agent could use it effectively even without the output schema.

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

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

The schema already provides 100% coverage of all four parameters with descriptions. The tool description mostly restates these parameters in the filter summary and adds only the no-filter default behavior, which is more behavioral than semantic. Thus it does not significantly exceed the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Lista as lideranças do Senado, da Câmara e do Congresso Nacional' – a specific verb+resource that clearly defines the tool's purpose. It distinguishes from siblings like senado_listar_blocos and senado_obter_senador by focusing on leadership positions.

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 provides explicit alternatives: 'Para a composição de blocos use senado_listar_blocos' and for obtaining the missing UF, 'obtenha-a via senado_obter_senador'. It also states the behavior with no filters: 'sem filtros retorna todas as casas', guiding when to omit filters.

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?

The description discloses a critical behavioral nuance: the composition is historical, with 'dataDesligamento' indicating a party has left and the same party potentially appearing multiple times with distinct membership periods. This goes well beyond the readOnly/idempotent annotations and prevents a common misinterpretation of duplicate or contradictory 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?

The description is dense but every sentence carries essential information: first the scope and return shape, then the historical-data caveat, and finally usage guidance. No filler or repetition of schema fields, making it both efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description appropriately avoids listing all fields. It provides the return envelope ({ count, blocos }), the key fields, the important data interpretation rule, and links to related tools. This is fully sufficient for an agent 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?

The tool has zero parameters, and the input schema is empty. Per the rubric, a baseline of 4 applies to tools with no parameters because there is nothing to explain. The description adds no parameter details, but none are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Lista') and identifies the exact resource ('todos os blocos parlamentares do Senado e seus partidos membros'). It distinguishes itself from siblings by specifying the return structure and explicitly naming alternative tools for different purposes (senado_obter_bloco, senado_liderancas), making its unique scope clear.

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?

Clear guidance is provided: use this tool to discover a bloc's 'codigo' for later detail via 'senado_obter_bloco', and for leadership data use 'senado_liderancas'. This directly contrasts with two sibling tools, giving the agent explicit decision criteria.

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 annotations (readOnlyHint, idempotentHint, etc.), the description reveals an important behavioral trait: the endpoint only returns active commissions, so `ativa=false` yields an empty list. It also discloses the return shape (`{ count, comissoes }` and item fields), giving the agent a clearer expectation of what the call will produce.

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 compact: three sentences cover what the tool does, the result structure, a behavioral caveat, and a concrete use case. No redundant wording; every sentence serves a distinct purpose and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with two optional parameters, an output schema, and strong annotations, the description is complete: it states the filters, explains the active-only behavior, describes the response shape, and references downstream tools. Nothing essential is missing for an agent 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?

The input schema already provides 100% coverage with enum values and descriptions for both parameters, so the baseline is 3. The description adds value by explaining the consequence of setting `ativa=false` (empty result) and corroborating the `tipo` filter values, which goes beyond the schema text alone.

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?

Description names the exact resource ('comissões (colegiados) ativas do Senado') and the action ('Lista'), and specifies key filters. It distinguishes itself from sibling tools by noting it returns the `sigla` needed by `senado_obter_comissao` and `senado_reunioes_comissao`, clearly marking it as a discovery/list tool rather than a detail/getter.

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

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

The description explicitly says 'Use para descobrir a `sigla` exigida por `senado_obter_comissao`...', which provides a concrete use case. It also notes the active-only limitation. However, it does not mention when not to use it or name alternative listing tools, so it falls short of a full when/when-not/alternatives breakdown.

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 traits. The description adds valuable behavioral context: return shape `{ count, senadores }`, item fields, partial name matching ignoring accents/case, local filtering for uf/partido, and the official endpoint `/senador/lista/atual` as provenance. This goes well beyond the annotation hints.

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 appropriately sized, front-loaded with example queries, and every sentence adds value. It uses backticks for parameters, references sibling tools, and provides concrete examples without redundancy. A model of concise yet informative documentation.

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 and annotations cover safety, the description covers all critical aspects: what the tool does, how to invoke it (parameter semantics), what it returns, the source endpoint, and how to use the results with other tools. It even handles the edge case of out-of-exercise senators by directing to a sibling tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond schema: `emExercicio` default true, `legislatura` examples (57 for 2023-2027), `nome` partial matching and use case, and `uf`/`partido` local filtering. However, it does not clarify interactions between `emExercicio` and `legislatura` when both are provided, so a slight gap remains.

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 clearly states the tool lists senators in exercise or from a specific legislature, with optional filters. It uses a specific verb ('Lista') and resource ('senadores'), and distinguishes from sibling tools by mentioning `senado_senadores_afastados` for out-of-exercise senators.

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

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

Explicitly enumerates example user intents ('liste os senadores em exercício', 'senadores atuais', 'lista atual de senadores') and provides an explicit alternative for senators out of exercise (`senado_senadores_afastados`). Also states downstream use of `codigo` in `senado_obter_senador` and `senado_votacoes_senador`, making usage context and alternatives 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the return structure and parameter meaning, but no additional behavioral traits like pagination or data freshness. It does not contradict annotations, and the added value is moderate.

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 compact and front-loaded: first sentence states the purpose, second explains the parameter, third gives the return format and an alternative tool. No unnecessary words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with one optional parameter and an output schema, the description fully covers the purpose, parameter behavior, return shape, and differentiation from a sibling. It is complete and self-contained.

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 provides a description for the 'casa' parameter with enum values and a default, achieving 100% schema description coverage. The description reiterates the default and options but does not add meaning beyond what the schema offers, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Lista' (lists) and names the resource 'membros da Mesa Diretora' with the member roles. It clearly distinguishes itself from the sibling tool by explicitly pointing to 'senado_liderancas' for party leadership, which avoids ambiguity.

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 explains exactly when to use this tool and provides an explicit alternative: 'Para lideranças partidárias use senado_liderancas'. It also describes the two valid values of the 'casa' parameter, giving clear context for selecting the correct scope.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behaviors: invalid or absent IDs return `totalBlocos` 0 with an explanatory `aviso`; coverage excludes joint sessions and some solemn sessions; the `modo` parameter changes the payload shape; `aviso` signals truncation. These are non-obvious runtime behaviors that materially affect invocation and interpretation.

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

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

The description is dense but well-structured, front-loading the core purpose, then return shape, coverage constraints, mode semantics, and finally related-tool guidance. Every clause earns its place: no filler, and the use of semicolons and parentheses keeps it compact despite covering many contingencies.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 parameters, 2 enums, and complex mode-dependent behavior, the description is remarkably complete. It explains return fields, coverage exceptions, pagination, parameter interactions, and how to obtain the required `id`. The output schema exists, but the description still gives enough behavioral context to avoid common mistakes.

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

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

Although the schema already covers parameters 100%, the description adds meaningful semantics beyond the field descriptions: it explains that `modo=resumo` returns 200-character excerpts limited by `limite`, while `modo=texto` returns full content in a window capped at 20 blocks; it clarifies that `sequenciaFim` only acts in `texto` mode; and it states that `orador` performs a partial name search. These details are not inferable from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Transcrição oficial (notas taquigráficas) de uma sessão plenária ou reunião de comissão, em blocos sequenciais.' It clearly distinguishes the tool from siblings by naming complementary tools like `senado_videos_taquigrafia` and stating that media should be obtained there, not here.

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

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

The description provides explicit when-to-use guidance and alternatives: it says to obtain the `id` via `senado_agenda_plenario`/`senado_resultado_plenario` for sessions or `senado_reuniao_comissao` for meetings, and explicitly states 'Para a mídia (vídeo/áudio) use `senado_videos_taquigrafia`, não esta.' It also clarifies coverage gaps where transcriptions are not available.

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 annotations (readOnly, idempotent, non-destructive), the description reveals key behavioral nuances: the 'partidos' field is a HISTORICAL composition (with 'dataDesligamento' indicating departed members), 'dataExtincao' is null for active blocs, and invalid codes produce an error message. These are non-obvious behaviors that significantly aid the agent in interpreting results and handling failures.

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

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

The description is dense but well-structured: opening sentence states the core function, then lists the exact return fields, then explains two important interpretations (historical membership and null for active blocs), and closes with parameter acquisition and error behavior. Every sentence carries essential information with no redundancy or 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 simple get-by-ID tool with one parameter, an output schema (which defines the return structure), and annotations covering safety, the description covers all necessary context: purpose, required input source, output composition, historical semantics, and error behavior. Nothing essential is missing for an agent to correctly select and invoke this tool.

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

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

The input schema already describes 'codigo' as 'Código do bloco parlamentar' (100% coverage). The description adds value by explaining how to obtain this parameter (via senado_listar_blocos) and what happens if an invalid code is provided (error). This is beyond the schema's descriptive content, earning a 4.

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 clearly states 'Obtém detalhes de um bloco parlamentar específico pelo seu código' – a specific verb (obtém) with a specific resource (bloco parlamentar) identified by code. It distinguishes from sibling tools like senado_listar_blocos (which lists) and other 'obter' tools by focusing on the bloc entity and its detailed structure.

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

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

The description provides explicit usage context: it instructs the agent to first obtain the 'codigo' via 'senado_listar_blocos' and notes that an inexistent code returns an error. This guides the agent on tool sequencing and error handling. However, it doesn't explicitly state when not to use this tool or name alternative tools beyond the prerequisite, so it falls 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 mark readOnly/idempotent/non-destructive; the description adds behavioral nuances: finalidade only populated for temporary committees, null+aviso for permanent ones, and sigla internally resolved to numeric code. These details go beyond annotations.

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

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

The description is dense but relatively long; however, it is front-loaded and every sentence conveys a distinct fact (output shapes, edge cases, resolution). No fluff, but it could be slightly restructured for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema available and strong annotations, the description still adds critical context: exact return structures for each secao, null/aviso behavior, and source attribution. It is complete for a moderately complex detail tool.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by explaining how secao maps to output structures, reinforces the default, and clarifies that sigla is resolved internally and should come from senado_listar_comissoes.

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 specifies the verb 'Obtém dados' and the resource 'comissão', parameterized by sigla and secao, with output shapes for each section. It clearly distinguishes from sibling senado_listar_comissoes, which is referenced for discovering valid siglas.

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

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

The description explains when to use resumo vs membros, notes the default secao, and directs the user to senado_listar_comissoes for finding a valid sigla. It also sets expectations for permanent vs temporary commissions, which prevents misuse.

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 annotations (readOnly, idempotent, non-destructive), the description discloses concrete behavioral details: fields missing in the norm come as null, and a nonexistent `codigo` returns an error 'Norma não encontrada' rather than an empty object. It also states it's a live query to the official open data base, adding useful context not in annotations.

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

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

The description is well-structured and front-loaded: it starts with purpose, then behavior, output fields, error/null semantics, and usage alternatives. It is longer than minimal but each sentence carries essential information, with only minor redundancy around the 'codigo vs law number' point that appears in 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 only one parameter, solid annotations, and an output schema present, the description fills all remaining gaps: it explains the return format, error behavior, null handling, data source, and how to obtain the required identifier. The tool is fully contextualized, leaving nothing ambiguous for the agent.

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

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

The input schema already provides a detailed description of `codigo`, including the warning not to confuse it with the law number. The tool description reinforces this and adds a procedural pointer to obtain the code from `senado_buscar_legislacao` before calling this tool, giving workflow context beyond the schema's static definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Obtém o detalhe de uma norma federal já promulgada pelo seu codigo interno.' It clearly distinguishes itself from sibling `senado_buscar_legislacao`, stating that this tool is solely for the detail of an already identified norm, while the sibling is for locating norms.

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

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

The description explicitly guides the agent: obtain `codigo` via `senado_buscar_legislacao` first, and use `senado_buscar_legislacao` to locate norms by type/number/year, while this tool serves only for detail. This gives clear when-to-use and alternatives, fully satisfying the dimension.

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?

The description goes well beyond the readOnly/idempotent annotations by disclosing return-field structure per section, chronological ordering, truncation behavior with aviso, and default limite values (100 and 50). This gives the agent accurate expectations for side-effect-free reads and edge cases.

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

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

The description is dense but well-organized: the main purpose is front-loaded, and each subsequent clause earns its place by specifying return shapes, defaults, ordering, or truncation behavior. No filler or repetition of annotation data.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-mode read tool with configurable limits, the description covers all necessary context: how to get the prerequisite codigoMateria, what each section returns, default and max limits, truncation warnings, and ordering. Combined with the output schema and annotations, the agent has a complete operational picture.

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?

Even though schema coverage is 100%, the description adds essential meaning: it maps each secao enum to concrete output structures, defines limite defaults and scope, and clarifies that codigoMateria must come from senado_buscar_materias. This significantly exceeds the schema's short 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?

The description opens with a specific verb and resource: 'Obtém dados de uma matéria pelo codigoMateria'. It distinguishes this detail-oriented tool from the sibling search tool by instructing users to obtain codigoMateria via senado_buscar_materias, and it enumerates three distinct data sections.

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 provides clear workflow guidance ('Obtenha o codigoMateria via senado_buscar_materias') and explains when each secao value is appropriate (detalhe vs tramitacao vs textos). It does not explicitly state when not to use this tool relative to other senado_obter_* siblings, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by detailing the return object structure, including `tramitando` (boolean), `situacaoAtual`, `deliberacao`, and `normaGerada`, which goes beyond the structured annotations. However, it does not mention error behavior or edge cases, 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?

The description is well-structured: first sentence states purpose, second lists return fields, and third gives usage prerequisites and alternatives. Every sentence earns its place. The field list is verbose but highly informative and necessary for agent expectation-setting.

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 only one parameter, an output schema exists, and rich annotations, the description is complete. It explains the return structure in detail, tells how to obtain prerequisite IDs, and clearly differentiates from the overlapping sibling. No critical information seems 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% for the single parameter `idProcesso` (described as 'ID do processo legislativo'). The description reinforces this by saying 'pelo seu `id`' and adds practical guidance on where to obtain the id (`senado_search_processos` or `senado_buscar_materias`), which is beyond bare schema 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?

The description states a specific verb+resource: 'Obtém detalhes completos de um processo legislativo específico pelo seu `id`.' It clearly distinguishes from siblings by explicitly directing to `senado_processo_detalhe` for emendas, relatorias, or prazos, and mentions how to get the id first via search tools.

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

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

It provides explicit when-to-use guidance: obtain `idProcesso` via `senado_search_processos` or `senado_buscar_materias` before calling, and for specific sub-details use `senado_processo_detalhe` with `secao` parameter. This is exactly the kind of alternative distinction expected.

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 destructiveHint=false, and the description does not contradict them. It adds useful boundary information by detailing the exact biographical fields returned and explicitly excluding historical categories that are directed to another tool, though it does not mention error behavior or edge cases.

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

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

The description is two sentences: the first states purpose and return shape, the second covers input sourcing and alternative tool usage. Every sentence earns its place, and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, read-only tool with strong annotations and an output schema, the description comprehensively covers purpose, input acquisition, output fields, and exclusions. It is complete and actionable without unnecessary redundancy.

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

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

The schema already describes codigoSenador with 100% coverage, but the description adds operational provenance by telling the agent to obtain it via senado_listar_senadores. This is extra value beyond the schema, even though it does not deepen the semantic meaning of the code 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?

The description opens with 'Obtém o detalhe biográfico de um senador específico', a specific verb and resource, and enumerates the returned fields. This clearly distinguishes it from sibling tools like senado_listar_senadores and senado_senador_historico.

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 instructs how to obtain the required codigoSenador via senado_listar_senadores (filtro nome) and when to use senado_senador_historico for affiliations, professions, licenses, commissions, or positions. This provides clear when-to-use and 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?

Beyond the readOnlyHint/idempotentHint annotations, the description reveals detailed return structures (single vote object vs. {codigoSessao, count, votacoes} for multiple votes), lists the exact fields, and highlights a critical namespace collision gotcha. This goes well beyond what annotations provide.

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

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

The description is dense but every sentence contributes essential information: purpose, return shapes, prerequisite, and a warning. It is well-structured with bold and semicolons, making it readable without unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, the description covers purpose, both return variants, the prerequisite call to another tool, and a critical exception. It is complete enough that an agent can select and invoke the tool correctly even before consulting the output schema.

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

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

The schema already fully describes the parameter (100% coverage), so baseline is 3. The description adds meaningful disambiguation by explaining that codigoVotacao is codigoSessao from a plenary session and explicitly warns against using committee codes, enriching the semantic context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves details of a plenary vote ('Obtém detalhes de uma votação de plenário') using codigoVotacao, including nominal votes. It also distinguishes itself from sibling tools by explicitly noting this is for plenary votes only, unlike senado_votacao_comissao.

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

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

It explicitly instructs to obtain codigoSessao via senado_search_votacoes before calling, and provides a strong exclusion: committee vote codes from senado_votacao_comissao are not valid here, even if they coincide numerically. This gives clear when-to-use and 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?

A descrição explica a diferença entre proposição e execução, a estrutura da resposta, o significado da data do ofício em relação ao ano orçamentário, e a cobertura multi-anual da base. Complementa as annotations (readOnlyHint, idempotentHint) com detalhes operacionais relevantes sem contradizê-las.

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?

O texto é longo, mas a complexidade da ferramenta (dois modos, múltiplos campos de resposta) justifica o comprimento. Cada sentença entrega informação essencial, sem redundância com o schema, e usa estrutura clara com exemplos code-like.

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?

Considerando a complexidade da ferramenta e a presença de output schema, a descrição é completa: cobre os dois modos, os parâmetros, as estruturas de retorno, notas sobre datas e recomendações de uso. Não há lacunas significativas para o agente executar corretamente.

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?

Embora o schema já descreva todos os parâmetros (cobertura 100%), a descrição adiciona contexto crucial: como 'ano' filtra ofícios pelo ano das emendas, como 'limite' e 'pagina' controlam a paginação, e como 'incluirEmendas' expande o retorno. Isso torna o uso dos parâmetros mais intuitivo.

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?

A descrição declara explicitamente que a ferramenta trata de 'Emendas parlamentares ao orçamento da União' e diferencia os dois modos de operação ('emendas' e 'oficios'). O escopo é específico e a distinção da ferramenta irmã 'senado_execucao_orcamentaria' está clara.

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?

Fornece diretrizes diretas: recomenda filtrar pelo 'ano' do orçamento, paginar com 'limite'/'pagina', usar 'incluirEmendas' para detalhes, e explicitamente orienta usar 'senado_execucao_orcamentaria' para orçamento interno do Senado. Isso define quando usar esta ferramenta versus alternativas.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by detailing the exact return structure (`{ count, votacoes }` with nested fields) and explicitly naming the alternative tool for session results, which goes beyond the annotations. It does not disclose potential edge-case behaviors (e.g., what happens when no orientations exist), but that is a minor gap given the rich annotations.

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

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

The description is two sentences, front-loaded with purpose, and efficiently packs in the return schema and usage instructions. Every sentence adds value, with no filler or repetition of the title or 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 still provides a detailed field-by-field breakdown of the return payload, which is helpful for an agent. It explains the two alternative date input modes and explicitly names the alternative tool for related but distinct needs. The description is complete for a read-only, idempotent query tool with no required parameters.

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

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

Although schema description coverage is 100% (each parameter has a description), the tool description adds crucial semantic guidance by explaining the relationship between the parameters: 'Informe data (um dia) ou o período dataInicio/dataFim.' This clarifies that `data` and the `dataInicio`/`dataFim` pair are alternative ways to specify the time window, which is not evident from the schema alone.

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 clearly states the tool reports party leadership voting orientations in plenary sessions with vote tallies, using a specific verb ('Orientação de bancada') and resource ('votações de plenário'). It explicitly distinguishes itself from the sibling tool `senado_resultado_plenario` by pointing users there for session results, and the focus on 'disciplina partidária' sets it apart from other voting 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?

The description gives explicit usage context: it is essential for party discipline analysis, and it directly instructs the user to use `senado_resultado_plenario` when they need session results instead. It also clarifies the date parameter options ('Informe data (um dia) ou o período dataInicio/dataFim'), making the tool's intended invocation 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 declare read-only and idempotent behavior, so the description adds valuable behavioral context: the exact return shape `{ tabela, count, total, aviso?, registros[] }`, the default and maximum `limite`, the empty-result behavior (`count` 0 and empty list), and that `filtro` matches any field. This goes well beyond the annotation safety profile.

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

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

The description is a single, well-organized paragraph that front-loads the resource and parameter, then logically enumerates table categories, return format, limits, filter behavior, and the alternative tool. Every sentence carries substantive information with no filler or redundancy.

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 description fully equips an agent to select and invoke the tool correctly: it covers all 8 enum values, return format, limit/pagination behavior, filter semantics, empty results, and the alternative tool for a related case. With a robust schema and this description, no critical 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?

Although the schema already provides 100% parameter descriptions, the description supplements it with essential semantics: it maps each enum value of `tabela` to aggregate vs. list categories, clarifies the default/max for `limite`, and explains the `filtro` matching behavior against any record field. This adds meaning beyond the structured 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 clearly identifies the resource (Senate personnel tables) and the parameter-driven behavior via `tabela`. It enumerates the specific table types (aggregate and nominal) and distinguishes the tool from the sibling `senado_servidores` for nominal server registry, making the purpose explicit and non-overlapping.

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 directs users to `senado_servidores` for the nominal registry of effective/commissioned servers, which serves as a clear when-not and alternative. It also delineates the two categories of tables (quantitative aggregates vs. nominal lists), helping the agent choose the right table and tool.

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?

Although annotations already declare readOnlyHint=true and destructiveHint=false, the description adds meaningful behavioral context: it discloses the return structure `{ secao, count, total, aviso?, itens }`, the `limite` default and maximum, and that `prazos` returns raw API records. It also notes the conditional applicability of `dataReferencia` for specific secões, going beyond what annotations provide.

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

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

The description is long but highly structured, using semicolons, arrows, and lists to pack a large amount of necessary detail into a compact form. It is front-loaded with the main purpose, and every clause contributes useful information, though the density could be considered slightly overwhelming. Given the tool's complexity (10 parameters, 3 modes), the length is justified.

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 description covers all key aspects for a complex tool: the three sections with their specific outputs and filters, common parameters, return format, limits, examples, and how to obtain prerequisites from sibling tools. Despite the presence of an output schema, the description provides enough contextual completeness to understand the tool's operation without redundant detail.

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%, satisfying the baseline. The description enriches parameter understanding by grouping parameters by `secao` (e.g., `codigoParlamentarAutor` for emendas, `codigoParlamentar`/`codigoColegiado`/`dataReferencia` for relatorias) and explaining that all sections share common filters (`idProcesso`, `codigoMateria`, `dataInicio`/`dataFim`). This adds value beyond the individual schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb and resource: 'Detalha um aspecto de processos legislativos conforme o parâmetro `secao`', immediately distinguishing three sub-modes (emendas, relatorias, prazos) with detailed field lists. This clearly differentiates it from sibling tools like senado_obter_processo, which likely fetches a whole process rather than a specific aspect.

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

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

Explicit guidance is given: 'Obtenha o `idProcesso` via `senado_search_processos`; tipos de prazo via `senado_tabelas_processo`', and the requirement to provide at least one filter is clearly stated. It also illustrates valid calls with examples, making it easy for an agent to know exactly when and how to invoke this tool.

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