Dados Abertos Senado BR MCP

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint; description adds default date behavior and return structure but no additional behavioral traits (e.g., rate limits, auth requirements). With rich annotations, description adds moderate value beyond structured fields.

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

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

Two well-structured sentences: first covers core function and parameters, second details return structure and alternatives. No wasted words, front-loaded with essential 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 annotations and schema richness, description adequately covers input, output, and alternatives. Lacks mention of pagination or error cases, but overall complete for a simple list tool with good 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?

Schema coverage is 100%, setting baseline 3. Description adds value by specifying default date (today) and clarifying optional filter purpose, going slightly beyond 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?

Uses specific verb 'Obtém' with clear resource 'agenda de reuniões de todas as comissões'. Explicitly distinguishes from siblings by naming alternatives for historical per-commission data (senado_reunioes_comissao) and detailed meeting info (senado_reuniao_comissao).

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

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

Clearly states when to use: for agenda on a specific date, with optional filter. Provides explicit when-not-to-use by referencing sibling tools for historical periods and meeting details, fulfilling the guidelines dimension perfectly.

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 the return structure (`{ data, escopo, count, sessoes }`) and the fields within each sessão (`codigo, data, hora, tipo, situacao, pauta` with subfields). Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context on data format and scope, fully covering behavioral traits 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 concise: two sentences that efficiently front-load purpose, then return structure, then usage guidance, then alternatives. Every sentence adds value with no redundancy or filler. It is well-structured and easy to parse.

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

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

Given the tool's complexity (3 optional parameters, a non-trivial return object, and sibling tools for related functionality), the description is fully complete. It explains the tool's scope, parameter options, return format, and when to use alternative tools. The output schema exists but the description still provides the necessary behavioral 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 schema coverage is 100%, the description adds semantic value: it explains defaults (`data` assumes today), scope values (`dia` = SF+CN no dia; `mes` = mês inteiro; `cn` = plenário do Congresso), and that `dataFim` is only for escopo=cn. This clarifies parameter usage beyond the schema 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 clearly states the tool's purpose: obtaining the agenda of plenary sessions (Senate or National Congress) by day or month, with the agenda of matters to be voted. It specifies the verb 'obtém' and the resource 'agenda de sessões de plenário'. It also distinguishes itself from sibling tools by mentioning senado_resultado_plenario (for already appreciated results) and senado_encontro_plenario (for session details), 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 provides explicit usage context: when to use (to get the agenda with items to be voted), parameter guidance (use `escopo` dia/mes/cn; without `data` assumes today), and when not to use (for already appreciated results use senado_resultado_plenario; for session details use senado_encontro_plenario). This clearly guides the agent on selection and invocation.

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

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

Beyond annotations, explains the nuanced semantics of 'atual', that mixed membership and duplicate entries can occur due to different tratamentos. Discloses sorting order.

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?

Efficiently packs critical information in a few sentences, front-loaded with purpose and crucial semantic caveats. No 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?

With output schema, it covers return structure, field descriptions, and cross-tool usage. Annotations handle safety, so description completes the 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?

Adds meaningful details not in schema: 'nome' filter is partial and accent-insensitive; 'limite' default and max are reiterated with practical context.

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

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

Clearly states the tool lists parliamentary authors of ongoing processes, sorted by productivity. Explicitly differentiates from similar tools like senado_listar_senadores.

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-not-to-use guidance (not for current senators) and names the alternative tool. Also explains how to use the output codigo in other tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds concrete behavioral details: no pagination, return format with count and normas, field names and null handling, and that results may vary between calls (consistent with openWorldHint). No contradictions.

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 with the core purpose. It is slightly long but all sentences provide necessary information, including return format, alternative tool, and error condition. No fluff, but could be slightly more concise.

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

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

Given the tool's complexity (4 optional parameters, output schema with multiple fields, sibling tools), the description fully covers purpose, usage, parameter meaning, behavior, and return format. Annotations and output schema are already rich, but the description adds necessary context without gaps.

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 significant meaning: for 'tipo' it explains the format (sigla oficial) and suggests catalog via 'senado_tabelas_referencia'; for 'data' it clarifies the compact format and difference from output; for 'ano' specifies range; for 'numero' gives example and combination with tipo/ano. Each parameter is enriched beyond 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 searches for already-promulgated federal legal norms, specifying the resource (normas jurídicas federais) and verb (busca). It distinguishes from the sibling tool 'senado_buscar_materias' for propositions in progress.

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

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

Explicitly tells when to use this tool (promulgated norms) versus 'senado_buscar_materias' (propositions in process). Also states that at least one filter is required, and calling without filters returns an error.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. Description adds beyond these: it notes the search returns a list with truncation (including 'aviso'), default limit of 100 (max 500), and the response structure. It also clarifies that calling details separately is unnecessary for listing.

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?

Description is well-organized: first sentence states purpose and required criteria, then usage guidance, then response format, then examples. Every sentence earns its place; no fluff. Front-loaded with key 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 tool's complexity (11 parameters, sibling tools, output schema exists), the description leaves no gaps. It covers purpose, usage guidance, parameter meaning, output format, and examples. It also effectively leverages the output schema to avoid repeating return value details.

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 covers 100% of parameters with descriptions, so baseline is 3. Description adds significant value: it states 'informe ao menos um critério', explains that ordenarPor defaults to dataApresentacao to favor recent requests, gives exact date formats (YYYYMMDD or ISO), and provides two illustrative examples showing parameter combinations.

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 clearly states 'Busca matérias legislativas' and enumerates all criteria (type, number, year, keywords, author, date range, situation). It distinguishes from sibling senado_obter_materia, specifying that this tool is for listing and the other for details.

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

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

Explicitly states when to use this tool (e.g., for 'matérias recentes sobre X') and when not to (use senado_obter_materia only for details). Provides concrete examples and advises on parameters like palavraChave, ordenarPor, and limite for typical queries.

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 indicate readOnly and idempotent, and the description goes beyond by detailing computation of statistics (min/max/mean/median/percentiles), output structure (grupos[], agregado[], despesas[]), truncation with aviso, and the interaction between parameters like estatisticas and modo. 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 comprehensive but somewhat lengthy (~20 sentences). It is front-loaded with purpose and well-organized, but could be condensed to improve readability. Still, it earns high marks for clarity.

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, enums, output schema present), the description covers all essential behaviors: aggregation modes, statistics, filtering, limits, truncation warnings, and cross-reference to another tool. The agent can 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?

Schema description coverage is 100% and the tool description adds significant context: it explains how estatisticas, agruparPor, modo, and topN interact, clarifies that modo is ignored when estatisticas=true, and describes output differences per mode. This goes well beyond 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 clearly states the tool retrieves CEAPS expenses for senators in a given year, with examples of statistical queries. It distinguishes from siblings by focusing on this specific expense type and referencing a companion tool for senator codes.

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 for ranking/distribution queries versus aggregation modes, explains grouping options, and references senado_listar_senadores for obtaining senator codes. It covers both normal and statistical use cases thoroughly.

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 annotations by explaining behaviors like truncation (count < total), empty sections returning count 0, error on invalid combos, and absence of monetary values in most sections. Annotations confirm readOnly, idempotent, non-destructive, so no contradiction.

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

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

The description is well-structured with a clear first sentence stating purpose, followed by parameter explanations, return format, and warnings. It is somewhat lengthy but each sentence serves a purpose; minor redundancy in parameter explanations could be tightened.

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

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

Given the tool's complexity (multi-enum parameters, valid combos, truncation, error conditions, missing data warnings), the description covers all necessary contexts. The return structure is described, and behavioral nuances are fully addressed, making it complete for correct agent invocation.

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

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

With 100% schema coverage, the description still adds significant value by explaining enum meanings in depth (e.g., tipo values as contract, price commitment, budget reservation) and the practical meaning of limite (truncation indicator). It also clarifies valid secao×tipo pairs.

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 detail a specific section of a procurement identified by id. It explicitly distinguishes itself from sibling tools like senado_contratos and senado_contratacoes_lista by noting they are for locating procurements, not detailing them.

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

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

The description provides explicit when-to-use guidance, including valid section×type combinations and that invalid combos return errors. It also gives important warnings (e.g., value only in aditivos) and explains truncation behavior with limit parameter.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral details: return format for each tipo, ordering behavior, pagination with offset and limit, truncation warning, and that menores_aprendizes returns raw non-normalized fields. No contradictions.

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, starting with the main purpose and then detailing parameters and behavior. It is slightly verbose but each sentence adds value, so it earns a 4 rather than 5 for being perfectly concise.

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

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

Given the complexity of the tool (5 parameters, three tipos, pagination, filtering, output structure), the description covers all necessary aspects: return format, pagination mechanics, filtering, ordering, and links to the sibling detail tool. Output schema exists and the description adequately explains the 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?

Schema description coverage is 100%, but the description enriches each parameter with context: e.g., 'filtro' applied on all fields, 'ordem' over id sequence, 'offset' for paginating the tail, and 'limite' default 50 max 500 with truncation warning. This adds meaning beyond the schema.

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

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

The description clearly states the tool lists contract records (atas de registro de preço, notas de empenho, or menores aprendizes) from Senado, with optional text filtering. It distinguishes itself from the sibling tool senado_contratacao_detalhe by explicitly mentioning its use for detailed views.

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: 'Para aprofundar uma ata/empenho, use o id em senado_contratacao_detalhe.' It also explains pagination and limits, making it clear when this list 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?

Beyond annotations (readOnly, idempotent, not destructive), the description adds: partial accent-free search, worker-side filtering, absence of monetary value fields, truncation behavior, and return structure. 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 well-structured, front-loaded with purpose and parameters, then return structure, warnings, and cross-reference. Every sentence provides value, and it is not overly verbose.

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 (7 params, external data source, sibling relation) and existence of output schema, the description covers return structure, edge cases (no monetary value, subespécies mix), truncation, and cross-reference to sibling tool. It is fully informative.

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 context: search is partial and accent-insensitive for certain fields, and summarizes search dimensions. This adds marginal value beyond 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 clearly states it searches administrative contracts of the Senate by various criteria (fornecedor, CNPJ, ano, etc.). It distinguishes from sibling tool senado_contratacao_detalhe by mentioning its use for detailed info. The resource and action are 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 provides explicit guidance: use the returned 'id' in senado_contratacao_detalhe for details, warns against looking for monetary values since the source doesn't publish them, explains subespécies, and notes the 'limite' parameter and truncation behavior.

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, non-destructive. Description adds return structure, mandatory date parameters, and that it lists all speeches (no filtering beyond dates). No contradiction. Could mention pagination or limits, but overall good.

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

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

Three sentences: first states purpose and required params, second describes return structure, third gives sibling alternatives. No fluff, front-loaded with essential 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 tool's purpose (list floor speeches with date filter) and presence of an output schema, the description is complete. It covers what, how, and where to go for related tasks.

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

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

Schema coverage is 100% with basic descriptions. Description adds that parameters form a date range, specifies mandatory nature, and the exact format. This clarifies the relationship between the two parameters 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?

Description clearly states the verb (Lista) and resource (discursos em plenário) with a specific date range. It explicitly distinguishes from siblings by naming alternative tools for specific senator speeches and full text.

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

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

Provides explicit when-to-use (listing all floor speeches in a date range) and when-not-to-use (for specific senator or full text), naming alternative tools `senado_discursos_senador` and `senado_discurso_texto`.

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?

Description adds key behavioral details beyond annotations: no pagination, empty list when no results, different period behavior for discursos vs apartes, and full return structure. Annotations (readOnly, idempotent, not destructive) are consistent and description provides necessary 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?

Description is detailed and informative, front-loaded with purpose. While slightly long, each sentence adds value and there is no redundancy. Could be marginally shorter but remains clear.

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 complexity (5 parameters, conditional behavior based on tipo and date omission, multiple sibling tools), the description fully covers input, output, behavior, and relationships. Output schema is described in text, providing complete guidance.

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

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

Schema coverage is 100% and description adds significant meaning: explains casa filter, tipo enum with impact, date parameters with the important caveat about 30-day default for discursos, and codigoSenador. Enhances understanding beyond 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 speeches of a specific senator, filterable by period and house. It distinguishes between 'discursos' (own speeches) and 'apartes' (interventions), and differentiates from sibling tools senado_discursos_plenario (all senators) and senado_discurso_texto (full text).

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

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

Explicitly tells when to use this tool (list speeches of a senator), how to obtain codigoSenador via senado_listar_senadores, and to use senado_discurso_texto for full text. Warns about default 30-day limit for discursos and recommends explicit period for history. Advises to use senado_discursos_plenario for all senators.

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

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

Annotations declare `readOnlyHint=true`, `idempotentHint=true`, `destructiveHint=false`. The description adds that the text is a complete transcript, not truncated or paginated, can be large (dezenas de KB), and that invalid codes or speeches without text result in errors. 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 concise (4 sentences) and front-loaded. The first sentence states the purpose and the parameter. The second details the return format and behavior. The third gives context on obtaining the code. The fourth contrasts with alternatives. No 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 presence of an output schema (implicit from description), the description covers the return structure, error conditions (invalid code, no text), data size, and input sourcing. For a simple retrieval tool, all relevant aspects are addressed.

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 coverage is 100%, so the description does not need to explain parameters, but it adds value by specifying that `codigoPronunciamento` comes from the `codigo` field of the sibling tools, reinforcing the required input and its source.

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 retrieves the full text of a single speech by `codigoPronunciamento`. It distinguishes itself from sibling tools `senado_discursos_senador` and `senado_discursos_plenario` by noting that those are for listing/filtering, while this one fetches the complete text of an already identified speech.

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

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

The description explicitly tells when to use the tool (to get the full text of a speech), when not to (for listing/filtering), and recommends alternative tools (`senado_discursos_senador` or `senado_discursos_plenario`). It also mentions that an invalid or textless speech returns an error, providing clear guidance.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds critical behavior: no pagination, count=0 for empty committees, and that codigoParlamentar is only effective for autoria and ignored in relatoria.

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

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

Multiple sentences but all are informative and front-load the main purpose. No redundant information; every sentence adds value.

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

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

Output schema exists, so description doesn't need to detail return values, but it still describes the structure. Covers all relevant aspects: parameters, behavior, and cross-references to other tools.

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. Description adds context beyond schema by stating the default for tipo (autoria) and the conditional effectiveness of codigoParlamentar.

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 clearly states the tool ranks parliamentarians by quantity of matters in a committee, specifying the two axes (autoria/relatoria) and parameters. It distinguishes from sibling tools like senado_buscar_materias.

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

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

Explicitly instructs to use senado_listar_comissoes for committee sigla and senado_obter_senador for parlamentar codigo. Also provides when-not-to-use: for the list of matters themselves, use senado_buscar_materias.

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, idempotentHint, etc. The description adds significant context: explains the meaning of each status, the coverage limitation for closed consultations, the return format, and that all modes accept minimoVotos and limite. No contradictions.

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-organized and front-loaded with purpose, but it is slightly verbose. Some details like 'cresce com o tempo' are repeated. Overall, it earns its length by providing essential differentiation and behavioral details.

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

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

Given 6 parameters, 0 required, 100% schema coverage, and output schema, the description is thorough: it explains modes, status nuances, default values, return structure, and differentiates from siblings. No missing critical information for correct 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?

Schema coverage is 100%, yet the description adds default values (percentualMinimo 85%, margemPolarizacao 15, etc.) and explains the logic for each mode, going beyond schema descriptions. For example, it clarifies that polarizada orders by smallest sim/não difference.

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 analyzes open public consultations by citizen agreement degree, explains two modes (consenso and polarizada), and explicitly distinguishes from sibling tools 'senado_ecidadania_consultas_votos' (historical) and 'senado_ecidadania_obter_consulta' (detail).

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

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

It provides explicit when-to-use guidance: consenso for high concentration, polarizada for balanced votes. It also clarifies status options (aberta, encerrada, todas) and notes that closed consultations before first ingestion are not captured, avoiding 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds source (CSV Arquimedes), update frequency (semanalmente), scope (~15 mil matérias), and explains why status is 'Descontinuado' and treated as archive. No contradiction.

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

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

Description is well-structured with bold terms, front-loaded with purpose, then usage, sibling distinction, parameter details, and return format. Every sentence is informative without 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 output schema exists and complexity (5 parameters, 2 enums, 1 UF filter with ranking), description covers all: return structure, filtering, ordering, ranking per UF, and archive vs active distinction. No gaps.

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?

All 5 parameters are described in schema with 100% coverage. Description enriches each: `uf` filters and adds `recorteUf`, `materia` can be numeric code or text snippet, `ordenarPor` metrics explained, `limite` default given.

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 clearly defines tool as historical vote archive by UF, explicitly contrasting with sibling tools `senado_ecidadania_consultas_analise` and `senado_ecidadania_listar_consultas`. Specific verb 'acervo histórico' and resource 'votos das consultas públicas do e-Cidadania com quebra por UF'.

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 usage conditions: 'Use apenas quando o pedido for pelo acervo/arquivo histórico ou por votos por estado (UF); para 'consultas mais votadas', ranking ou opinião ATUAL das consultas em tramitação use `senado_ecidadania_consultas_analise`.' Also notes difference from `senado_ecidadania_listar_consultas`.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds value by detailing that it returns a complete set of open consultations (~7.7k), the specific fields returned, how status transitions from 'aberta' to 'encerrada' when the matter leaves processing, and that encerradas before first ingestion are not captured. 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 relatively long but well-structured, front-loading the main purpose and then adding details. It contains no wasted sentences, but could be slightly more concise while retaining all necessary 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 tool has 3 parameters, full schema descriptions, output schema present, and rich annotations, the description is complete. It covers return structure, edge cases (pre-ingestion consultations), and behavioral nuances over time.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds contextual details like default 'limite' (20) and elaborates on the status parameter behavior, providing additional meaning beyond 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 verb 'Lista' and the resource 'consultas públicas do e-Cidadania', and distinguishes from sibling tools by specifying that for detail use 'senado_ecidadania_obter_consulta' and for analytical recortes use 'senado_ecidadania_consultas_analise'.

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 explains when to use this tool (to list public consultations) and when to use alternatives, naming the specific sibling tools for different purposes. It also describes the default behavior (open consultations) and the status parameter.

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 value by disclosing data source persistence ('corpus persistido em D1'), update frequency ('atualizado semanalmente'), scale ('~milhares de eventos'), and inclusion of closed events ('incluindo encerrados'). This operational context is 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 moderately sized at four sentences, gets to the main purpose immediately, and every sentence adds meaningful information. 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 that an output schema exists (so return values need not be fully explained), the description covers all essential aspects: what the tool returns, filtering options, ordering, data source, update frequency, cardinality, and a pointer to a related sibling tool. This provides 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?

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by giving concrete usage examples (e.g., ordering for ranking), mentioning the default limit (20), and stating that filters by comissao use a sigla. This helps an agent understand how to combine parameters 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 verb 'Lista' and the resource 'eventos interativos do e-Cidadania (audiências públicas, sabatinas, lives)'. It specifies the scope as 'conjunto completo' and distinguishes from sibling tools like 'senado_ecidadania_obter_evento' by noting that this tool returns the full list and that the sibling is for detailed event retrieval.

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

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

The description provides explicit guidance for a ranking use case ('Para um ranking dos mais comentados, ordene por comentários') and directs to a sibling tool for detail ('Para o detalhe completo de um evento use senado_ecidadania_obter_evento'). While it doesn't explicitly state when not to use this tool, the context of the sibling differentiation covers typical decision points.

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: data persistence in D1, weekly updates, null fields in listing, confirming read-only nature. No contradictions.

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?

Description is well-structured: first sentence states purpose and data scope, then return format, then filter options, then usage hints. No fluff, each sentence adds value.

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

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

Given the tool's complexity (5 parameters, output schema present), the description fully covers return shape, field constraints, filtering, and ordering behavior. No gaps.

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% (all parameters documented). The description adds meaning beyond schema by explaining which ordenarPor values are actually available ('apoios' in corpus, others only in detail) and gives a specific usage for ranking.

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 lists citizen-proposed legislative ideas from e-Cidadania, specifying it returns the complete corpus (including closed and converted), the data fields, and distinguishes from the detail tool obter_ideia.

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

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

The description explains when to use this tool (list ideas) and when to use the sibling tool (obter_ideia for detail), and provides a usage example for ranking. It implies context but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining that fields like 'dataAbertura', 'dataEncerramento', 'comissao', 'linkMateria', and 'comentarios' are always null, revealing internal data constraints beyond what annotations provide. No contradictions.

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 paragraph that efficiently covers purpose, return structure, null constraints, and input prerequisite. It front-loads the main verb and resource, and every sentence adds necessary information without 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 the output schema exists, the description does not need to detail return values. It explains which fields are null and why, and instructs how to obtain the required input. This is fully adequate for a simple look-up tool with clear 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?

The single parameter 'id' is already described in the schema as 'ID da consulta pública'. The description adds context on how to obtain a valid ID via sibling tools, which provides practical guidance beyond the schema. With 100% schema coverage, baseline is 3, and the extra context justifies this score.

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 'Obtém o detalhe de uma consulta pública específica do e-Cidadania', clearly stating the specific verb ('obtém') and resource ('consulta pública'). It lists the returned fields, distinguishing it from sibling tools like 'senado_ecidadania_listar_consultas' which lists consultations, and 'senado_ecidadania_consultas_analise' which likely analyzes multiple consultations.

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 the agent to obtain the 'id' via 'senado_ecidadania_listar_consultas' or 'senado_ecidadania_consultas_analise' before calling this tool. It also clarifies that certain fields are always null due to portal limitations, preventing misinterpretation.

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 annotations já declaram readOnlyHint, idempotentHint, etc. A descrição adiciona detalhes sobre o formato do retorno, campos nulos, e erro para id inexistente, complementando sem contradizer.

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?

Descrição concisa em um parágrafo, iniciando pelo propósito, listando campos retornados e finalizando com orientações de uso. Cada frase agrega valor, sem redundância.

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?

Para uma ferramenta de busca por id com output schema existente, a descrição cobre propósito, pré-requisitos, diferenciação de siblings, tratamento de erro e campos nulos. Completa e auto-suficiente.

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?

Único parâmetro (id) já bem descrito no schema. A descrição menciona a origem do id, mas não agrega significado adicional ao que o schema já provê. Cobertura 100%, baseline 3.

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

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

A descrição claramente especifica o verbo 'obtém', o recurso 'detalhe completo de um evento interativo do e-Cidadania (audiência, sabatina, live)', e distingue do sibling senado_ecidadania_listar_eventos que apenas lista eventos sem detalhes.

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?

A descrição instrui explicitamente a obter o id via senado_ecidadania_listar_eventos e recomenda usar listar para listagem simples, evitando esta ferramenta. Fornece orientação clara sobre quando usar e quando não.

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. Description adds valuable behavioral details: description field is truncated to ~2000 characters, 'comentarios' is always null (a potential user expectation), and 'plConvertido' appears only when idea becomes a law. This adds 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?

Description is concise: 3 sentences. First sentence states purpose, second lists returned fields with notes, third provides necessary usage instruction. No extraneous 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 simplicity of the tool (one parameter), the description fully covers what the agent needs: purpose, return field details including special cases (truncation, null field, plConvertido), and prerequisite step. Output schema is present, so return structure documentation is not required.

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

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

Schema coverage is 100% with a description for the 'id' parameter. The description does not add further semantic meaning beyond stating the prerequisite to get id from another tool. 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?

Description clearly states it obtains the detail of a legislative idea from e-Cidadania. It uses a specific verb ('obtém') and resource ('detalhe de uma ideia legislativa'), and distinguishes itself from sibling tool 'senado_ecidadania_listar_ideias' by specifying the prerequisite 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?

Provides explicit prerequisite: obtain id via 'senado_ecidadania_listar_ideias'. Does not explicitly state when not to use, but the context of a detail retrieval tool is clear. Also warns that 'comentarios' is always null.

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?

All behavioral traits are disclosed: the tool is read-only, idempotent, and non-destructive (as annotations confirm). The description adds detail on filtering logic, defaults, and output structure, complementing 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 efficient, front-loaded with purpose, then details output, then criteria. No redundant sentences. Each part serves a 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 nested parameter, output schema, and many siblings, the description covers everything needed: purpose, criteria, output format, follow-up actions. Completeness is high.

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 covers 100%, and description adds value by explaining default values, the meaning of 'apenasEmTramitacao' (considering real status), and overall criteria behavior beyond 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's goal: to suggest topics for a monthly public poll by analyzing consultations and ideas. It distinguishes from siblings like senado_ecidadania_consultas_analise by focusing on suggestion of topics for poll, not just analysis.

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 follow-up guidance (use senado_ecidadania_obter_consulta or obter_ideia), but does not explicitly state when to prefer this tool over siblings. It implies usage context well.

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

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

Adds useful behavioral details beyond annotations: output structure with count, total, empresas, each item having id, nome, cnpj, contratos (up to 30 numbers), and totalContratos; constraint that at least one input is needed; and limit on number of companies (default 20, max 100). 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?

Two concise, front-loaded sentences: first states purpose and output format, second provides constraints and cross-reference. No redundant information, every sentence adds value.

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

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

Given the tool's simplicity (3 params, output schema present, annotations cover read-only/idempotent), the description fully covers usage, output structure, and connections to sibling tools. No gaps identified.

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?

Description adds context beyond schema: explains why at least one of nome or cnpj is required, confirms partial search behavior, and reiterates default and max for limite. Schema coverage is 100% but description enriches understanding with practical usage notes.

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 clearly states the tool searches for companies contracting with the Senate by name (min 3 chars) or CNPJ/CPF, and distinguishes itself from sibling tools by mentioning use of id/contract number in senado_contratos or senado_contratacao_detalhe for 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?

Description explains the need to provide at least nome or cnpj due to large database, and directs to use other tools for further details. It does not explicitly state when not to use this tool, but provides clear guidance on prerequisites and follow-up.

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 indicate readOnlyHint, openWorldHint, idempotentHint are true, and destructiveHint false. The description adds that encontro may be empty if the section has no data and that errors occur if the codigo does not exist. This provides useful context beyond annotations and does not contradict them.

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

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

The description is multi-sentence but well-structured and front-loaded with the main purpose. It conveys necessary information without excess 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 tool's complexity (multiple sections) and the presence of an output schema, the description adequately covers the return structure and edge cases. It explains the behavior for each secao value and potential empty results.

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

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

The input schema has 100% description coverage, but the tool description adds meaning by explaining how the 'secao' parameter affects the output structure. This adds value beyond the schema's enum listing.

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 returns details of a plenary session, specifies the return fields (codigo, secao, encontro), and explains how encontro varies by secao. It distinguishes itself from sibling tools like senado_agenda_plenario and senado_resultado_plenario by mentioning they provide the codigo.

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 the tool (to get details of a specific plenary session) and how to obtain the codigo from other tools. It indirectly indicates when not to use by specifying the codigo source. However, it does not explicitly state cases where alternative tools would be more 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds significant behavioral context: it explains the output fields (caminho, subordinadas with sigla, nome, nivel), the depth level (até o nível de serviço), and the data source (portal institucional, not the open data API). No contradiction with annotations.

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

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

The description is well-structured: it starts with the core function, then explains output, use cases, and an alternative. While it is on the longer side, every sentence adds value (examples, source attribution, alternative tool). Minor room for brevity, but overall well-organized.

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 (returning a hierarchical tree structure), the description is highly complete. It explains the output shape (caminho and subordinadas with depth), the scope (up to service level), and provides examples. An output schema exists, so return values are documented. The mention of an alternative tool for server counts completes the 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?

Both parameters (unidade, limite) are fully described in the input schema (100% coverage). The description restates that unidade can be a sigla or name, and mentions the default limit (200) but does not add new semantics beyond the schema. Per guidelines, 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 purpose: returning the organizational structure (organograma) of the Senate up to service level, given a unit. It specifies the output structure (unit, path, total subordinates, subordinates with acronym, name, depth) and differentiates itself from sibling tools like 'senado_servidores' by explicitly mentioning when to use that alternative.

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

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

The description provides excellent usage guidance. It gives concrete example queries ('o que está sob a DGER', 'quais secretarias/serviços pertencem a X'), states the tool's purpose for understanding hierarchy, and explicitly directs users to 'senado_servidores' for counting or listing servers under a unit. This clear when-to-use and when-not-to-use guidance is exemplary.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by explaining automatic column selection based on tipo, return structure with `campoAnalisado`, behavior of `estatisticas` with/without `agruparPor`, and truncation with `aviso`. No contradiction.

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

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

The description is relatively long but well-structured: starts with purpose, then statistics mode, then return format, then usage tips, then sibling disambiguation. Every sentence adds value, though it could be slightly more streamlined.

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 (8 parameters, multiple modes, statistics, grouping), the description covers all aspects: parameter interactions, output structure, use cases, and distinction from alternatives. Complete and clear.

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?

Despite 100% schema description coverage, the description adds extensive meaning: explains how `estatisticas` overrides `modo`, how `campo` auto-selection works, how `agruparPor` ranks groups by sum descending, and the effect of `limite` with truncation warning.

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 covers budget execution for expenses (since 2013) and revenues (since 2012), and explicitly distinguishes it from the sibling 'senado_orcamento_parlamentar' for parliamentary budget.

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 `estatisticas=true` for statistics, filter by `ano` before requesting `detalhe`, warns against confusing with parliamentary budget. Also explains when to use `agruparPor` with statistics to get ranked groups.

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 indicate readOnly, idempotent, non-destructive. Description adds detailed behavioral context: output structure for each mode, handling of parameters (limite ignored with estatisticas, default topN), and grouping behavior (groups ranked by descending sum). No contradictions.

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?

Description is lengthy but well-organized with bold emphasis for key terms. Every sentence adds necessary detail. Slight redundancy (repeats default values) but acceptable given 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?

Given the tool's complexity (two modes, multiple parameters, statistics, grouping), the description is comprehensive. It covers all major use cases, constraints, and links to related tool. Output schema exists, so return values not required.

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% (baseline 3). Description adds significant value by explaining parameter interactions (e.g., estatisticas=true ignores limite, topN only for some modes, agruparPor only with estatisticas). Provides contextual meaning beyond 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?

Description clearly states the tool retrieves overtime hours for Senate employees for a given year/month. It distinguishes from sibling 'senado_remuneracoes_servidores' for full remuneration. The two operational modes (with/without estatisticas) are well explained.

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 specifies when to use estatisticas=true (for statistics/ranking) vs false (listing). Explains behavior with agruparPor and limit. Provides alternative tool for full remuneration. Clear guidance on parameter interactions.

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 read-only, idempotent, non-destructive. The description adds the return format '{ count, total, licitacoes }', explains raw API data, and notes error condition on no filter. No contradictions.

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

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

Three sentences, no fluff. Purpose is front-loaded. Each sentence adds essential information: search methods, return structure, constraints, and sibling tool pointer.

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 output schema present, the description adequately covers required parameters, limits, error cases, and cross-references. Complete for a search tool with good 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?

Schema coverage is 100%, but the description adds examples (e.g., '19/2018') and contextual details (default 50, max 500) beyond the schema descriptions, enhancing parameter meaning.

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 verb 'Busca' (search) and the resource 'licitações do Senado', and distinguishes from sibling tools by noting that for the resulting contract, use 'senado_contratos'.

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

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

It explicitly specifies that at least 'numero' or 'objeto' is required, otherwise returns error, and mentions an alternative tool for contracts. Also details default and max limit.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds return structure, notes UF always null due to data source, and explains use of 'bloco' field. No contradictions.

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 adds value: purpose, return format, caveat, filters, sibling reference. Could be more structured but is efficient.

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 is a read-only listing with output schema, the description covers all needed context: return structure, missing UF, filtering behavior, and cross-references to other tools for additional data.

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 has 100% description coverage, so baseline 3 applies. The description adds minimal extra semantics (e.g., 'no filters returns all houses') but does not need to compensate.

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 lists leaderships of Senate, Chamber, and National Congress, using specific verbs and resource. It distinguishes from siblings like senado_listar_blocos for bloc composition and senado_obter_senador for UF retrieval.

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

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

Provides explicit context on when to use filters, notes that without filters returns all houses, and directs to alternatives for UF (senado_obter_senador) and bloc details (senado_listar_blocos).

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 and idempotentHint. The description adds important behavioral context: the list includes historical composition with dataDesligamento, and a party may appear multiple times with different periods. This goes beyond annotations, though no mention of potential pagination or rate limits (likely not needed).

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?

Single well-structured paragraph: first sentence states purpose, second details return format, third adds behavioral caveats, fourth gives usage guidance. No wasted words, 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 zero-parameter tool with output schema implied, the description covers purpose, return structure, historical data behavior, and sibling references. Annotations provide safety guarantees. Everything an agent needs to invoke correctly is present.

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

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

No parameters exist; schema coverage is 100%. Baseline for 0 parameters is 4. The description adds no parameter-specific info because none exist, but it still provides meaningful context about the tool's output.

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 clearly states it lists all parliamentary blocs and their member parties, specifies the return structure, and distinguishes from sibling tools (senado_obter_bloco, senado_liderancas).

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

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

Explicitly advises when to use this tool (to discover a block's codigo) and when to use alternatives (senado_obter_bloco for details, senado_liderancas for leaderships).

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. The description adds that the endpoint only returns active commissions, so ativa=false results in empty list, and describes the return structure.

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 concise sentences, front-loaded with purpose, followed by behavior and usage context. No redundant information.

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

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

With 2 optional parameters, output schema provided, and clear linkage to sibling tools, the description is fully adequate for an AI agent to understand and use 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?

All parameters have schema descriptions (100% coverage). The description adds the critical insight that ativa=false will return empty because the endpoint only serves active commissions, and lists the possible tipo values.

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 lists active comissões (colegiados) with filters for tipo and ativa. It distinguishes from siblings by noting its output sigla is used by senado_obter_comissao and senado_reunioes_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?

Explicitly guides use to discover sigla for other tools, and warns that ativa=false yields empty list. However, it does not explicitly state when not to use this tool or mention alternatives beyond the two sibling tools.

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 declare readOnlyHint, idempotentHint, and destructiveHint, setting a safety baseline. The description adds behavioral context: partial name matching ignoring accents, local filtering for uf/partido, official endpoint provenance, and response structure. This adds value 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 a single dense paragraph, packing many details but could benefit from bullet points or clearer sectioning for easier parsing by AI. It is not overly verbose, but structure slightly impacts 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 the tool's purpose, parameters, return format ({count, senadores} with fields), endpoint provenance, and integration with sibling tools. Given the presence of an output schema and 100% parameter coverage, the description is complete and provides all needed context.

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

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

Schema coverage is 100%, but the description enriches each parameter: emExercicio's default, nome's partial matching behavior, partido's tolerance for short forms, and the interaction between emExercicio and legislatura. This surpasses what the raw schema provides.

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 with filters (UF, party, name) and distinguishes from siblings like senado_senadores_afastados and senado_obter_senador. The verb 'listar' is specific and the resource is well-defined.

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 examples ('Use para pedidos como...'), specifies default behavior (emExercicio=true), and directs when to use alternative tools (e.g., senado_senadores_afastados for out-of-exercise senators). It also guides chaining with other tools via código.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, so description adds minimal behavioral disclosure. It does not contradict 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 sentences front-load purpose, then parameter context, output structure, and sibling reference. Every sentence adds value.

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

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

For a simple tool with one parameter and an output schema, the description fully covers purpose, parameter, output format, and alternatives.

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

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

Schema coverage is 100%, and description adds meaning by explaining the default value and the difference between 'senado' and 'congresso' options.

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 clearly states it lists members of Mesa Diretora (president, vice-presidents, secretaries) and distinguishes it from the sibling tool senado_liderancas by explicitly directing users to use that for leadership queries.

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

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

Explicitly states when to use this tool (to get Mesa members) and when not (for party leadership, use senado_liderancas). Also explains the parameter casa and its options.

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 annotations by detailing behavioral traits: return structure for existing vs. non-existent IDs, pagination via `sequenciaInicio` and `limite`, mode differences (`resumo` vs. `texto`), filtering by `orador`, and coverage caveats (conjunct sessions not transcribed). Annotations already indicate read-only and idempotent, but the description adds rich 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 thorough and well-structured, with each sentence adding value. It is slightly long but front-loaded with the main purpose. It could be trimmed slightly without losing meaning, but it remains clear and organized.

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 (7 parameters, two modes, pagination, filtering, coverage caveats, multiple sources for `id`), the description covers all necessary context. The output schema exists and the description explains the return structure, so the description 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?

All 7 parameters have descriptions in the input schema (100% coverage), so baseline is 3. The description adds extra meaning: e.g., `sequenciaInicio` explained as pagination in resumo and window start in texto, `sequenciaFim` only effective in texto mode, `orador` filters by name cite, and defaults/limits clarified. This elevates the score to 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 returns official transcriptions (notas taquigráficas) of plenary sessions or committee meetings in sequential blocks. It distinguishes from sibling tools by explicitly mentioning that media (video/audio) should be obtained via `senado_videos_taquigrafia`.

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 this tool: for official transcripts, and when not to: for media (use `senado_videos_taquigrafia`). It also explains how to obtain the required `id` from other tools like `senado_agenda_plenario` or `senado_reuniao_comissao`, and notes coverage limitations for certain session types.

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. The description adds valuable behavioral details: the meaning of null in dataExtincao, the historical nature of partidos array, and the error message for non-existent codes, going 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 two sentences with no wasted words. The first sentence states the action and result, the second provides key details about return fields and usage. Every sentence adds value.

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

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

Given the tool's simplicity (one parameter, existing output schema, complete annotations), the description fully covers what an agent needs: how to get the code, what the response contains, and edge cases like inactive blocs and errors.

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

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

The input schema has 100% coverage for the single parameter 'codigo', including a description. The description repeats the parameter's purpose but does not add new semantic meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Obtém detalhes' and the resource 'bloco parlamentar específico pelo seu código'. It lists the returned fields, distinguishing it from sibling tools like senado_listar_blocos, which only lists blocs.

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 'codigo' parameter from senado_listar_blocos first and notes that an invalid code returns an error. It does not explicitly state when not to use it, but the context is clear enough for an agent.

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, etc. Description adds behavioral details like internal sigla resolution, finalidade field behavior (null for permanent commissions with aviso), and return structure. No contradictions.

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?

Description is well-structured and front-loaded with purpose. Each sentence adds value, though slightly verbose. No wasted 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 output schema, the description provides complete context including edge cases (finalidade null), internal behavior, and discovery via sibling. All necessary information for correct invocation is present.

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

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

Schema coverage is 100%, but description adds significant meaning: explains return details for each secao value, the finalidade edge case, and internal resolution of sigla. This goes beyond the schema's brief 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 it obtains commission data by sigla and section, with detailed return structures for each section. It distinguishes from siblings like senado_listar_comissoes (for discovery) and senado_reuniao_comissao (meetings).

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 directs to use senado_listar_comissoes to discover the sigla, providing clear context. Could be more explicit about when not to use, but the alternative is well-stated.

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

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

Adds value beyond annotations by describing live query, no side effects, return format, null handling, and error response. Annotations already cover readOnly, idempotent, nondestructive.

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?

Single dense paragraph front-loads purpose, then details return and usage. Every sentence earns its place; no 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?

Complete for a simple retrieval tool: explains all return fields, null behavior, error case, and relationship to sibling tool. Output schema exists but description still adds value.

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%, but description adds meaning: explains codigo is internal identifier, not law number, references sibling tool, and provides exclusiveMinimum.

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 clearly states the verb 'Obtém' and resource 'detalhe de uma norma federal promulgada por codigo interno', distinguishing from sibling tool senado_buscar_legislacao.

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 specifies when to use (when codigo known), when not (for search by type/number/year), and prerequisite (obtain codigo via senado_buscar_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, and idempotentHint=true. The description adds behavioral details beyond annotations: it explains that tramitacao returns chronological history ordered by date, textos returns documents from most recent to oldest, and truncation includes an 'aviso' field. This provides practical transparency about data ordering and limit handling.

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 uses colons and parenthetical lists effectively to organize information about sections and their outputs. It is concise with no filler, though a bulleted list might improve readability. Every sentence provides necessary detail, earning 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?

Given the output schema exists, the description need not detail exact return values. It sufficiently covers the three secao options, their output structures, default limits, truncation behavior, and the prerequisite to use senado_buscar_materias. The description is complete for an agent to invoke the tool correctly without ambiguity.

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

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

Schema description coverage is 100%, so all three parameters have schema descriptions. The description adds significant value by explaining the meaning of secao values and their outputs, clarifying default limits and truncation behavior for limite, and providing context for codigoMateria as a foreign key from another tool. 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 'Obtém dados de uma matéria pelo codigoMateria', specifying the verb (obtém), resource (matéria), and key parameter (codigoMateria). It distinguishes from sibling senado_buscar_materias by instructing the agent to first obtain the code from that search tool. The description also lists three sections with distinct outputs, making the tool's 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 explicitly tells the agent to 'Obtenha o codigoMateria via senado_buscar_materias', providing clear guidance on prerequisites. It explains when to use each secao value (detalhe, tramitacao, textos) with descriptions of their output structures. It also covers default limit values and truncation behavior, giving comprehensive usage context.

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

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

As anotações já declaram readOnlyHint, idempotentHint e destructiveHint como true/true/false, cobrindo o perfil de segurança. A descrição adiciona valor ao listar os campos retornados, mas não fornece contexto comportamental além das anotações. Não há contradição com as anotações.

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

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

A descrição é front-loaded: começa com o propósito, depois lista os campos retornados, e termina com orientações de uso. Embora seja um pouco longa, não contém informações redundantes e está bem organizada.

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 que a ferramenta tem apenas 1 parâmetro, anotações completas e a descrição já detalha o retorno e fornece orientações de uso, a descrição é suficientemente completa para um agente. Não menciona condições de erro, mas isso é aceitável para uma ferramenta de leitura com anotações adequadas.

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?

O esquema de entrada possui 1 parâmetro (idProcesso) com descrição 'ID do processo legislativo' e cobertura de 100%. A descrição da ferramenta menciona 'pelo seu id', mas não acrescenta significado além do esquema. Como o esquema já é completo, a nota base 3 é adequada.

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 afirma claramente 'Obtém detalhes completos de um processo legislativo específico pelo seu `id`', usando verbo específico ('Obtém') e recurso ('processo legislativo'). Diferencia-se de ferramentas irmãs ao mencionar que o id deve ser obtido via 'senado_search_processos' ou 'senado_buscar_materias', e que detalhes adicionais (emendas, relatorias, prazos) requerem 'senado_processo_detalhe'.

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 explícita sobre quando usar esta ferramenta: 'Obtenha o idProcesso antes via senado_search_processos ou senado_buscar_materias; para emendas, relatorias ou prazos use senado_processo_detalhe'. Isso informa claramente o contexto de uso e 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 declare readOnlyHint and idempotentHint. The description adds value by detailing the return object structure, but does not disclose additional behavioral traits beyond what's annotated.

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

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

Three sentences, each with distinct value: purpose, required param with source, and alternative tool. No redundant information; very concise.

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

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

Given the single parameter, explicit return fields, and adequate annotations, the description provides complete context for an AI agent to select and use 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 coverage is 100% and describes the parameter as a unique code. The description adds meaning by stating the parameter is required and how to obtain it via another tool, which aids correct invocation.

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 obtains the biographical detail of a specific senator, listing the exact fields returned. It explicitly distinguishes from sibling tools like senado_listar_senadores (obtain the code) and senado_senador_historico (other historical 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 tells when to use (get biographical detail), how to get the required parameter (via senado_listar_senadores), and when to use an alternative tool (senado_senador_historico for other data). This provides clear usage 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?

Description adds significant behavioral context beyond annotations: describes return format (object with votos or with codigoSessao/count/votacoes), and warns about numeric coincidence with comissao codes. Annotations already declare readOnly/ idempotent/ non-destructive, so bar is lower; description adds value without contradiction.

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

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

Description is moderately concise but front-loaded with purpose. It contains essential details (return format, prerequisite, warnings) without redundancy. Could be slightly shortened, but every sentence adds value.

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

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

Given that there is an output schema (not shown), the description explains return variants, how to obtain input, and warns about pitfalls. For a single-parameter tool, it covers prerequisites, behavior, and edge cases thoroughly.

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 already describes the parameter (codigoVotacao) with type and description. Description adds clarifying context: it is the codigoSessao from plenary sessions, and that it must not come from comissao. This adds meaning beyond the schema, especially warning about numeric overlap.

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 obtains details of a plenary vote by codigoVotacao, including nominal votes. It explicitly distinguishes from the sibling tool senado_votacao_comissao, noting that comissao codes are not valid 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?

Explicitly tells when to use: after obtaining codigoSessao via senado_search_votacoes. Clearly states when not to use: codes from senado_votacao_comissao are invalid. Provides clear alternative (senado_search_votacoes) for obtaining the input.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. Description adds behavioral details: response structure for each mode, pagination behavior, and the temporal relationship between oficios and emendas. No contradictions found.

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?

Description is concise but dense; it could benefit from line breaks or bullet points for clarity. However, it front-loads the core purpose and uses a single paragraph effectively with minimal waste.

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

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

Given the complexity of two modes and multiple parameters, the description covers essential usage context, output structure, and a crucial note about the alternative tool. Output schema exists, so return values are not needed in text. Adequate for an agent to 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 coverage is 100% (all parameters described). Description adds value by explaining the meaning of 'oficios' as execution documents and the role of 'incluirEmendas'. Reinforces pagination and filtering concepts 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?

Description clearly states the tool handles parliamentary budget amendments (emendas) with two distinct modes: 'emendas' (proposed amendments) and 'oficios' (execution documents). It specifies the verb 'conforme' and distinguishes from the sibling 'senado_execucao_orcamentaria' in the note.

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 guidance on when to use each mode (tipo) and recommends filtering by ano for oficios. Explicitly mentions an alternative tool for internal Senate budget execution. Could include more explicit 'when not to use' statements, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral context: returns detailed structure with 'count, votacoes', including voting codes, descriptions, totals, and orientations. Does not contradict 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 sentences, each earning its place: purpose, output structure, usage guidance. No fluff, front-loaded. Extremely efficient.

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 (read-only query, 3 params, output schema exists), description covers all necessary aspects: purpose, output, usage, sibling differentiation. Complete for agent decision-making.

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 covers 100% of parameters with descriptions. Description adds semantic guidance: the mutual exclusivity between 'data' and the 'dataInicio/dataFim' pair, clarifying usage beyond 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?

Description clearly states purpose: 'Orientação de bancada nas votações de plenário' with a specific verb (returns orientation) and resource (bench guidance in plenary votes). Distinguishes from sibling tools like 'senado_resultado_plenario' by focusing on party discipline analysis.

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

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

Explicitly tells when to use: 'essencial para análise de disciplina partidária'. Provides alternatives: 'Para o resultado das sessões use senado_resultado_plenario'. Also explains parameter usage: 'Informe data (um dia) ou o período dataInicio/dataFim'.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: return format (tabela, count, total, aviso?, registros[]), default limit (100, max 2000), empty result behavior, and optional textual filter. 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 well-structured with a clear front-loaded sentence and a bullet-like use of colons. It is somewhat lengthy but every sentence adds value. Minor redundancy could be trimmed, but overall it is effective.

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 (multiple tables, different result types), the description is remarkably complete. It covers all tables, parameters, limits, empty results, and points to an alternative tool. The output schema is indicated, so no need to explain return values further.

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 enriches parameter meaning: it explains the two categories of tables (quantitativos vs listas), clarifies that 'limite' defaults to 100 and max 2000, and describes the 'filtro' as matching any field. This adds value 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 'Tabelas de pessoal do Senado conforme o parâmetro `tabela`, specifying both quantitative aggregations and nominal lists. It distinguishes between different table types and mentions the alternative tool 'senado_servidores' for nominal cadastro of effective/commissioned servers, providing clear differentiation from siblings.

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

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

The description explicitly recommends using 'senado_servidores' for a specific use case (nominal cadastro of effective/commissioned servers), indicating when not to use this tool. However, it does not mention prerequisites or broader when-not scenarios, 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 indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the response format (secao, count, total, aviso?, itens), pagination limits (default 100, max 500), and date format expectations. This goes beyond the annotations.

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

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

The description is detailed but verbose (over 400 characters). While well-structured and front-loaded, it could be more concise. Every sentence adds value, but some redundancy exists in listing sub-fields.

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 complexity (10 parameters, 3 secao options), the description covers all necessary aspects: required vs optional filters, default values, response structure, cross-references, and examples. The presence of an output schema further supports completeness.

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

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

Schema descriptions cover all 10 parameters (100% coverage). The description enhances meaning by explaining parameter interactions (e.g., codigoParlamentar used only when secao=relatorias) and providing detailed sub-field structures for each 'secao'. This adds significant 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 the tool's purpose: detailing legislative processes by 'secao' (emendas, relatorias, prazos). It distinguishes itself from sibling tools by focusing on process details, and the name/title align well.

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 each 'secao', required filters (at least idProcesso or codigoMateria), default limits, and examples. It also cross-references related tools (senado_search_processos, senado_tabelas_processo). However, it lacks explicit statements about when not to use this tool.

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