Dados Abertos Senado BR MCP

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

Annotations already cover the safe read-only, idempotent, open-world profile. The description adds behavioral details beyond that: default date is today, the scope is all committees, the siglaComissao filter is optional, and the returned envelope/meeting fields are listed. It does not discuss error cases or rate limits, but those are minor for a simple read-only query.

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

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

The description is compact and front-loaded: purpose and default behavior first, then return shape, then sibling routing. Every sentence earns its place, and there is no redundant restating of the schema.

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

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

Given the output schema and annotations exist, the description covers all necessary calling context: what the tool does, default behavior, optional filter, return structure, and which sibling tools to use in other situations. An agent can invoke this tool correctly without further inference.

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

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

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds value by stating the default value for data (today), reinforcing the YYYYMMDD format, and clarifying that siglaComissao is an optional filter and how it shapes the result.

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

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

States it retrieves the meeting agenda for all committees on a given date, with an optional committee filter. The verb 'Obtém' plus the resource 'agenda de reuniões de todas as comissões' and the explicit date scope distinguish it from the many sibling tools; it even names related siblings.

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

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

Explicitly explains when to use this tool versus alternatives: use senado_reunioes_comissao for the history of a single committee over a period, and senado_reuniao_comissao for meeting details via codigo. This is direct when/when-not guidance with named alternatives.

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

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

The annotations already declare this as a safe read-only, idempotent operation, and the description adds the concrete return contract (`{ data, escopo, count, sessoes }`), the per-session fields, and the default-date/scope behavior. It goes well beyond the annotations without contradicting them, though it does not discuss pagination or error behavior, which are not critical here.

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

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

Three compact sentences cover purpose, return shape, scope usage, and sibling routing without repeating annotation or schema fields. The most important selection guidance is placed at the end but is still direct and economical.

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 rich output schema, fully documented parameters, and read-only annotations, the description supplies everything needed to select and call the tool correctly. It covers default behavior, scope options, return structure, and the two relevant sibling 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?

The input schema already documents all three parameters at 100% coverage, including defaults, patterns, and enum meanings. The description only reinforces the `escopo` usage and the default `data` behavior rather than adding substantive new parameter-level semantics, so the schema-heavy 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?

Opens with the verb 'Obtém' and identifies the exact resource: agenda de sessões de plenário, with variants for Senado and Congresso Nacional. It also names the scope dimensions (dia/mês) and the pauta contents, and the closing sentences distinguish it from the closest plenary siblings.

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

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

Explicitly instructs which `escopo` values to use and states the default behavior when `data` is omitted. It also names concrete alternatives—`senado_resultado_plenario` for already-appreciated results and `senado_encontro_plenario` for session details—so an agent can route between siblings without ambiguity.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds valuable behavioral facts: the list mixes senators, deputies, and former parliamentarians; a person may appear twice with distinct codes; results are ordered by `quantidadeMaterias`; and the default/max limits are stated. No contradiction with annotations.

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

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

The description is dense but every clause earns its place: purpose, semantic warning, sibling disambiguation, return shape, filters, limits, and next-step usage. The most critical caveat is front-loaded immediately after the verb phrase.

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

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

For a read-only list tool, the description is complete: it covers what is returned, what filters are available, ordering behavior, the semantic trap, and how to chain the returned code into related tools. Nothing essential is missing.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds a useful nuance beyond the schema: `nome` is a partial search 'sem acento', and it restates optionality and limits in a way that reinforces correct usage.

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 and resource: 'Lista parlamentares autores de processos em tramitação' and adds ordering by production. It also distinguishes itself from the sibling senado_listar_senadores by explicitly warning not to use it as a list of current senators.

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

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

It gives explicit when-to-use guidance and an explicit alternative: 'não use como lista de senadores em exercício (para isso, senado_listar_senadores)'. It also explains the semantic trap ('atual' means 'with process still in progress', not 'current mandate') and suggests downstream uses for the returned `codigo`.

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

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

The annotations already declare readOnlyHint, idempotentHint, and openWorldHint, but the description adds meaningful behavioral context: it is a live query against the official open-data base whose results may vary between calls, a no-filter call errors deterministically, there is no pagination, and absent fields are returned as null. This goes well beyond the structured hints without contradicting 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 dense but every sentence earns its place: core purpose, filtering semantics, error behavior, read-only/live nature, return shape, null handling, and routing to the related sibling tool. It is front-loaded with the primary purpose and avoids redundant restatement of the tool name or title.

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

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

For a search tool with no required parameters but a non-obvious precondition, the description fully covers the agent's needs: valid input combinations, error behavior, output structure without pagination, null-field semantics, and how to continue using the returned codigo with senado_obter_legislacao. The routing guidance for senado_buscar_materias closes the main ambiguity with sibling 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?

The schema already documents each parameter at 100% coverage, so the description does not need to repeat individual parameter meanings. It adds value by specifying the AND combination semantics across tipo, numero, ano, and data, and by imposing the at-least-one-filter rule that the schema itself does not enforce. This is a strong supplement, though the individual parameter details remain schema-driven.

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

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

The description clearly identifies the tool as searching already-enacted federal legal norms, naming concrete types (leis, decretos, leis complementares, emendas constitucionais) and the filtering mechanism. It distinguishes itself from the sibling senado_buscar_materias by explicitly limiting scope to promulgated norms, so an agent can select it correctly.

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

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

The description gives explicit when-to-use guidance: enacted federal norms only. It also names the alternative for pending proposals (senado_buscar_materias) and specifies the critical precondition that at least one filter must be provided, warning that a filterless call returns a deterministic error rather than an empty list.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is known. The description adds meaningful behavioral context beyond that: the hard constraint 'informe ao menos um critério', the default/max limit (100/500) with aviso when truncated, accepted date formats (YYYYMMDD or ISO), and the ordering/limit formula for recency queries. 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?

Although the description is long, every sentence earns its place: purpose, minimum criteria, recency recipe, return shape, sibling routing, limit behavior, and examples. The main verb and resource are front-loaded, and the structure flows from what the tool does to how to invoke it to what to expect.

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 11 parameters, an output schema, and annotations, this description is remarkably complete. It covers required criteria despite zero required params, explains ordering and limits, describes the return structure, disambiguates from senado_obter_materia, and gives both a keyword-style and an exact-lookup example. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant value: it maps natural-language request types to parameter combinations (palavraChave+ano+limite for recent matters; sigla+numero+ano for precise lookup), explains when to use ordenarPor/ordem with dataApresentacao, and provides two concrete JSON examples. This goes well beyond the schema field descriptions.

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

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

The description opens with a clear verb-resource pair, 'Busca matérias legislativas', and enumerates the filter dimensions (tipo, número, ano, palavras-chave, autor, período, situação). It also explicitly distinguishes itself from senado_obter_materia by saying the latter is only for detail/tramitação/textos, so an agent can tell them apart without opening the schema.

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

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

It gives explicit when-to-use patterns ('Para pedidos como matérias recentes sobre X, use...' with concrete parameter combinations) and an explicit when-not-to-use statement: 'não é necessário chamar detalhes para listar resultados' and 'Use codigo em senado_obter_materia apenas quando o usuário pedir detalhe/tramitação/textos'. This routes the agent to the correct sibling and prevents unnecessary follow-up calls.

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

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

The annotations already establish readOnly, idempotent, and non-destructive behavior, so the description adds genuine behavioral context: `modo` is ignored when `estatisticas=true`, grouped results are ordered by descending sum with `grupos[0]` as the top spender, `limite` truncates with an `aviso`, and filters use partial search. There is no contradiction with 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 dense but every clause earns its place: mode selection, output structures, ordering, filtering, caps, and warnings. The core purpose and the statistics-vs-aggregate decision are front-loaded, and the semicolon-driven structure keeps the long text scannable for an agent.

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 11 parameters and multiple interacting modes, the description is complete: it covers all output forms (`estatisticas`, `grupos[]`, `agregado[]`, `despesas[]`), sorting, truncation, partial filters, and how to resolve `codSenador` via a sibling. The output schema exists, so return-value documentation is not required, but the prose still supplies enough structure for correct invocation.

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

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

Although schema coverage is 100%, the description adds substantial cross-parameter meaning: how `estatisticas` interacts with `agruparPor`, how `topN` sizes the top/bottom lists, when `modo` is ignored, and what each output shape contains. This goes far beyond the individual field descriptions in the schema.

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

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

The description opens with a specific object and scope: CEAPS expenses of senators in a given year. It clearly identifies the resource and what operations are available, distinguishing it from the many senate sibling tools about agendas, legislation, payroll, or procurement.

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

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

It gives explicit decision rules: use `estatisticas=true` for distribution/ranking/median questions, use aggregate modes for totals, and use `modo='detalhe'` for itemized expenses. It even warns that aggregate modes only sum by group and thus cannot reveal distribution or extremes, and it directs the agent to `senado_listar_senadores` for obtaining `codSenador`.

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

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

The annotations already declare readOnly, idempotent, and non-destructive, and the description adds valuable behavioral detail: truncation semantics (count < total), empty-section behavior, invalid-combination errors, raw administrative fields, and the important caveat that the source does not publish contract value except in aditivos. No contradiction with annotations.

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

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

The description is dense but every sentence serves a purpose: purpose, parameter semantics, return shape, caveats, and sibling routing. It is front-loaded with the core action and clearly structured so an agent can extract the needed behavior quickly.

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

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

For a tool with two enums, one long id parameter, and numerous behavioral edge cases, the description covers everything an agent needs: valid combinations, defaults, limits, error cases, empty responses, return shape, data caveats, and how to obtain the required id. It is complete even without relying on the output schema.

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

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

Schema coverage is 100%, but the description goes beyond it by explaining how tipo and secao interact, which combinations are valid, and what limite means in terms of count < total. It also tells the agent where to obtain id, adding operational meaning not present in the schema.

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

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

The description opens with a specific verb and resource: 'Detalha uma seção específica de uma contratação já identificada pelo id'. It clearly distinguishes this tool from the sibling lookup tools by stating that senado_contratos and senado_contratacoes_lista are for locating the contracting record, not detailing it.

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

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

The description explicitly tells the agent when to use this tool versus alternatives: use senado_contratos or senado_contratacoes_lista to locate the contracting id, and use this tool to detail a specific section. It also states invalid secao×tipo combinations produce errors, so the agent knows which calls to avoid.

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, open-world, and non-destructive behavior. The description adds meaningful details beyond those annotations: filtering happens on the Worker across all fields, menores_aprendizes are returned as raw unnormalized API records, ordering follows upstream id sequence, truncation produces an aviso, and empty tipos return an empty list.

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

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

Two dense sentences carry all core information with no filler. The description front-loads the resource scope and then efficiently covers return shape, type-dependent differences, ordering, pagination, limits, edge cases, and the sibling tool for detail.

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, annotations, and the tool's moderate complexity, the description is complete. It covers all behavioral subtleties an agent needs—type variations, normalization differences, ordering semantics, truncation behavior, empty results, and a pointer to the detail tool—without requiring the agent to infer anything.

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 enriches parameter meaning: 'ordem' is tied to the upstream id sequence, 'offset' is described as paginating the tail, 'limite' is linked to truncation warnings, and 'filtro' is clarified as applying across all fields. This goes beyond the schema but not every parameter needs additional commentary.

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

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

The description names a specific verb ('Lista') and resource, then enumerates the three concrete listing types: atas de registro de preço, notas de empenho, and menores aprendizes. It also distinguishes itself from the detail sibling by explicitly pointing to senado_contratacao_detalhe for deeper inspection.

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

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

It clearly states what the tool covers and gives an explicit alternative: 'Para aprofundar uma ata/empenho, use o id em senado_contratacao_detalhe.' It also explains when filters, ordering, offset, and truncation apply, giving the agent enough context to decide when to call this tool.

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

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

The description discloses important behavioral details beyond the annotations: search is partial and accent-insensitive for particular fields, the source does not publish contract monetary values, results mix subespécies, and results are truncated with a warning when over the limit. These caveats are exactly the kind of non-obvious behavior an agent needs before calling the tool.

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

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

The description is dense but well structured, front-loading the core search capability, then return shape, then caveats, and finally the routing to the detail tool. Every sentence adds necessary operational information, with no filler or repetition.

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

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

For a complex search tool with 7 optional filters, mixed record types, truncation, and a follow-up detail tool, the description covers all relevant context: search semantics, output fields, missing monetary values, subespécie distinction, limite behavior, and how to proceed for more detail. Nothing essential is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real value by clarifying that fornecedor, objeto, and numero use partial, accent-insensitive search. It also reinforces the limite default/max behavior and the mão de obra filter. It does not add per-parameter detail for every field, but the added semantics are meaningful.

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 a specific action and resource: 'Busca contratos administrativos do Senado por fornecedor, CNPJ, ano, número, objeto ou mão de obra', and specifies the return shape. It is highly understandable, but it does not explicitly distinguish itself from close siblings like senado_contratacoes_lista or senado_empresas_contratadas, so it stops short of full sibling differentiation.

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

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

The description gives explicit when-not guidance ('não gaste chamadas procurando valor') and routes to the correct follow-up tool ('Use o id retornado em senado_contratacao_detalhe para itens, pagamentos, garantias ou aditivos'). This is practical, actionable context that tells an agent where this tool fits and where to go next.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavior beyond that: both date parameters are required, the format is YYYYMMDD, and the response structure is `{ periodo, count, discursos }` with a detailed field list. It does not mention pagination or maximum date ranges, but the annotated read-only/idempotent hints lower the burden.

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 and front-loads the core purpose and required constraints before mentioning alternatives. The long enumeration of response fields is slightly redundant with the output schema, but it still helps the agent quickly understand the result without opening the schema, so it is acceptable.

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

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

For a read-only date-range listing tool with full parameter schema coverage and an output schema, the description is largely complete: it specifies required params, date format, response shape, and sibling routing. Minor gaps like date inclusiveness or pagination behavior exist, but they are not likely to prevent correct invocation.

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

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

Schema description coverage is 100%, with both parameters already documented as 'Data início/fim (YYYYMMDD)' and validated by a `^\d{8}$` pattern. The description repeats these constraints but adds little semantic meaning beyond the schema, such as inclusiveness of dates or any special date-range behavior.

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

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

The description uses a specific verb ('Lista') and a specific resource ('discursos realizados em plenário num período de datas'), clearly defining the tool's scope. It also distinguishes itself from siblings by explicitly naming senado_discursos_senador and senado_discurso_texto as alternatives for other needs.

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

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

It states exactly when to use this tool (list all plenary speeches in a date range) and provides explicit routing guidance: use senado_discursos_senador for a specific parliamentarian and senado_discurso_texto for full text. This gives an agent clear decision criteria without needing to inspect sibling schemas.

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

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

Annotations already mark this as read-only and idempotent, and the description adds substantial behavioral detail beyond that: no pagination, count=0 with empty list semantics, items lacking full text, and the upstream source's 30-day restriction when date range is omitted. No contradiction with annotations.

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

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

The description is dense but well-structured: purpose, return shape, a prominent ATTENTION caveat, and cross-references to sibling tools. It is longer than minimal, but each sentence carries operational value and the key warning is front-loaded with caps.

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 period/tipo interaction, the description is remarkably complete: it covers return fields, empty-result behavior, no-pagination rule, missing full text, how to obtain required identifier, and where to go for alternatives. An agent has everything needed to invoke the tool correctly.

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

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

Schema coverage is 100% and each parameter already has a description, so baseline is 3. The tool description adds meaningful interplay semantics: how tipo changes the upstream source and content, and how omitting dataInicio/dataFim affects discursos vs apartes. This goes beyond the schema's individual parameter descriptions.

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

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

The description opens with a specific verb and resource ('Lista pronunciamentos de um senador'), then explicitly disambiguates from sibling tools: it says to use senado_discursos_plenario for all senators and senado_discurso_texto for full text. This makes the tool's scope unmistakable.

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 routing guidance: get codigoSenador via senado_listar_senadores, get full text via senado_discurso_texto, and use senado_discursos_plenario for all senators. It also warns about the 30-day default for discursos and specifies when apartes gives full history without a period.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior, and the description adds meaningful context beyond that: the text is not truncated or paginated, can be tens of KB, and an invalid or textless speech returns an error. There is no contradiction with 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 compact and front-loaded: it states the core purpose first, then the return format and error behavior, then the required workflow and alternatives. Every sentence earns its place without filler.

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

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

For a single-parameter read tool, the description covers the return object, payload size and truncation behavior, error conditions, and how to obtain the prerequisite code. Nothing an agent needs to call this correctly is missing, especially with an output schema available.

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

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

The schema already fully describes the only parameter, including its source tools and one-per-speech nature, so the description adds little new parameter-level meaning. The extra detail about error behavior is behavioral transparency rather than parameter semantics, so the high schema coverage 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 states a specific verb and resource: it obtains the full text ('texto integral') of a single pronunciamento using `codigoPronunciamento`. It also distinguishes itself from sibling list/filter tools by explaining that the others return summaries, dates, and authors, while this one returns the full transcript.

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

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

The description gives explicit when-to-use guidance: obtain the `codigoPronunciamento` first via `senado_discursos_senador` or `senado_discursos_plenario`, then use this tool for the full text. It also states when not to use it—for listing or filtering—and names the alternative tools for that purpose.

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

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

Annotations already mark readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description layers substantial behavior on top: no pagination, ordering by quantidade desc, count=0 for empty committees, the return envelope { siglaComissao, tipo, count, parlamentares }, and the non-obvious quirk that codigoParlamentar is ignored when tipo=relatoria. These disclosures go beyond both the schema and the annotations and would cause mis-calls if omitted.

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?

Five dense sentences, each carrying distinct information: purpose, axis choice, return envelope, ordering/pagination/zero-case, parameter quirk, and sibling routing. It is front-loaded with the ranking purpose and contains no filler or restatement of the title.

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

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

Given an existing output schema and read-only annotations, the description covers everything needed to call it correctly: valid signature, the tipo default and quirk, the empty-committee edge case, absence of pagination, and cross-tool resolution of both main parameters. Nothing material is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by pointing to where parameter values come from ('Descubra a sigla via senado_listar_comissoes; use o codigo do parlamentar em senado_obter_senador') and by reiterating the codigoParlamentar/tipo interaction. This provenance guidance is genuine added meaning, though the schema already documents the core parameter semantics.

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

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

States a specific verb ('Ranqueia') and resource (parlamentares por quantidade de matérias numa comissão), and explicitly differentiates from siblings by naming senado_buscar_materias as the alternative for the matters list itself. The description also points to senado_listar_comissoes and senado_obter_senador for parameter discovery, so an agent can distinguish it within the crowded senado_* family.

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 cross-tool routing: 'Para a lista das matérias em si (não a contagem) use senado_buscar_materias' sets a clear when-not condition, and the guidance to resolve siglaComissao via senado_listar_comissoes and codigoParlamentar via senado_obter_senador tells the agent exactly how to prepare valid inputs. This exceeds the 4-bar of clear context without exclusions.

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

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

Annotations already signal readOnly/idempotent/non-destructive, so the description carries a lower safety burden and instead adds rich behavioral context: per-mode ordering rules, status semantics, the ingest-boundary limitation for 'encerrada', defaults, and the return shape. This goes well beyond what the annotations alone provide.

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

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

The description is dense but every sentence earns its place: purpose, mode behavior, status caveat, defaults, return shape, and sibling routing. Formatting with bold, inline code, and arrows keeps it scannable, and the primary purpose is front-loaded before the 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?

For a six-parameter read-only analytics tool with an output schema, this description is fully sufficient. It covers input semantics, defaults, temporal edge cases, return structure, and correct sibling routing. Nothing necessary for correct invocation is missing.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond field descriptions: it explains what consenso vs. polarizada actually compute, how each mode orders results, which threshold parameter applies to which mode, and that minimoVotos and limite apply across all modes. This is considerably more than the baseline for schema-covered parameters.

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

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

The description opens with a specific verb and resource: it 'Analisa o conjunto completo de consultas públicas abertas... do e-Cidadania por grau de concordância cidadã'. It precisely names the two operating modes and explicitly distinguishes itself from sibling tools senado_ecidadania_consultas_votos (historical) and senado_ecidadania_obter_consulta (detail), making selection unambiguous.

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

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

The description states exactly when to use this tool: 'É esta a ferramenta para consultas mais votadas, ranking ou panorama ATUAL...'. It also gives an explicit exclusion: 'não confundir com senado_ecidadania_consultas_votos', and routes detail lookups to a sibling. The status lifecycle caveat ('fechadas antes da 1ª carga não são capturadas') further clarifies appropriate usage.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior, and the description adds valuable context: source data is a CSV, updated weekly, treated as an archive with 'Descontinuado' status, not as current opinion. This helps the agent set correct expectations beyond the structured annotations.

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

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

The description is dense but each sentence serves a purpose: scope, sibling differentiation, semantic status, return shape, and parameter usage. It is front-loaded with the core purpose and not padded with filler.

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

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

For a read-only, optionally-parameterized tool with an output schema and rich annotations, the description covers all relevant aspects: when to use, what differentiates it, the return contract, parameter semantics, and data provenance. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema, such as how 'uf' filters and re-ranks only materials with votes in that state and that each item gains 'recorteUf', which is not in the schema. It also clarifies the combined filter behavior of 'materia'.

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

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

The description states a specific verb and resource: a historical archive of e-Cidadania public consultation votes, broken down by UF. It explicitly distinguishes itself from sibling tools 'senado_ecidadania_consultas_analise' and 'senado_ecidadania_listar_consultas', so an agent can identify the intended use without guessing.

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

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

It gives clear when-to-use guidance ('Use apenas quando o pedido for pelo acervo/arquivo histórico ou por votos por estado') and names the exact alternative for current rankings/opinions. It also contrasts the archive with the in-progress consultations tool, removing ambiguity.

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

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

Annotations already mark it read-only, open-world, and idempotent. The description adds valuable runtime semantics: every consulta starts as `aberta`, transitions to `encerrada` when the matter leaves tramitação, and consultations closed before the first ingestion are never captured. This is exactly the kind of data-cutoff/state-evolution context annotations cannot express.

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

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

At roughly six sentences, the description front-loads the purpose and scope, then return shape, dynamic status behavior, and sibling routing in logical order. Each sentence adds distinct information and none repeats annotations or schema fields unnecessarily.

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

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

For a list tool with an output schema and read-only/idempotent annotations, the description is complete: it covers what is returned, the key open-world caveat, and how to route to siblings for detail or analysis. Even the unmentioned `pagina` parameter is fully described in the schema, so an agent has everything needed to invoke correctly.

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

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

Schema description coverage is 100%: all three parameters have descriptions, defaults, and enum constraints. The description only reinforces `limite` (padrão 20) and the status transition behavior already present in the schema, so it adds no independent parameter semantics. Baseline 3 applies because the schema carries the burden.

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

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

States a specific action and resource: 'Lista consultas públicas do e-Cidadania' with scope delimited to the complete set of abertas (~7,7 mil). It also distinguishes itself by naming sibling tools for detail and analytical views, so an agent can tell it apart from senado_ecidadania_obter_consulta and 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?

Gives explicit routing guidance: 'Para o detalhe de uma consulta chame ... obter_consulta com o id; para recortes analíticos ... use consultas_analise.' It also implies this tool is for the full list and defines status-scoped alternatives in the schema. No ambiguity remains about when to choose this sibling.

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?

Even with readOnlyHint and idempotentHint annotations already present, the description adds meaningful context about data scope and freshness: a complete persisted corpus in D1 updated weekly, thousands of events, and inclusion of closed events. It also exposes the expected status vocabulary and return shape, going beyond what the annotations alone disclose.

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

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

The description is a single dense paragraph that front-loads the action and scope, then covers return shape, filters, sorting, and the sibling alternative in logical order. Every sentence contributes operational information with no filler.

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

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

Given that no parameters are required and an output schema exists, the description covers everything an agent needs to call this tool correctly: data scope, return fields, valid filters, defaults, sorting recipe, and routing to the detail tool. No important behavioral gaps remain for this list operation.

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

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

Schema description coverage is 100%, and the schema already documents all parameter enums, defaults, and meanings. The description mostly restates the filters (status, comissao, limite) and adds only a modest goal-oriented tip about ranking by comments, which is not enough to move substantially beyond the baseline.

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

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

The description opens with a specific verb and resource ('Lista eventos interativos do e-Cidadania') and adds concrete examples (audiências públicas, sabatinas, lives). It also distinguishes itself from the sibling senado_ecidadania_obter_evento by noting this endpoint returns the complete list while the other returns full event 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 clearly states the canonical use case for this tool and gives an explicit alternative for detailed event info ('Para o detalhe completo de um evento use senado_ecidadania_obter_evento'). It also explains the sorting strategy for the most-commented ranking, though it does not explicitly say when to prefer the other e-Cidadania list tools (consultas, ideias).

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

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

Beyond the readOnly/idempotent annotations, it discloses the dataset is persisted in D1, updated weekly, has ~114k ideas, and includes closed/converted ones. It also transparently warns that autor and dataPublicacao are null in list responses, which prevents false expectations.

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

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

The description is dense but every sentence earns its place: scope, data freshness, return shape, null field caveats, filter/sort usage, and pointer to the sibling detail tool. The most decision-relevant facts are 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 list tool with all parameters documented in the schema, the description covers the essential operational context: what the corpus represents, how results are returned, how to filter/sort, and when to switch to the detail tool. Nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful operation-level guidance by explaining how to combine ordenarPor with ordem=desc for ranking and which parameters are relevant for filtering, going slightly beyond the schema's enum 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 states a specific verb and resource: it lists legislative ideas proposed by citizens on e-Cidadania, and clarifies it returns the complete corpus. It also explicitly distinguishes itself from senado_ecidadania_obter_ideia, which is the complementary detail tool.

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

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

It tells the agent exactly when to use the detail tool instead ('Para o detalhe completo... chame senado_ecidadania_obter_ideia com o id') and gives concrete instructions for ranking use cases ('ordene por apoios... ordem: desc'). This routes the agent correctly compared with the most relevant sibling.

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?

Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description adds valuable behavioral caveats: several fields are always null, why they are null, and how status reflects the consultation lifecycle. It also explains that comentarios is always null because the page lacks that feature.

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

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

The description is front-loaded with the core purpose, followed by essential return details, then important null-field caveats, and finally sourcing instructions. Every sentence earns its place and none of it is redundant with the schema or annotations.

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 is complete for a single-parameter read-only tool: it covers prerequisites, return shape, known null behavior, and points to the right sibling tools. With an output schema and safety annotations also present, nothing necessary for correct invocation is missing.

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

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

The schema already thoroughly documents the single id parameter, so the baseline is 3. The description adds value by telling the agent exactly where to get the id from, which is meaningful practical guidance beyond the schema's type and description.

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

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

The description opens with a specific action and resource: 'Obtém o detalhe de uma consulta pública específica do e-Cidadania.' It clearly differentiates from the listing/analysis siblings by requiring an id obtained from them, so the agent knows this is the detail-by-id tool.

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

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

It explicitly tells the agent to obtain the id beforehand via 'senado_ecidadania_listar_consultas' or 'senado_ecidadania_consultas_analise', establishing a clear when-to-use workflow. This is more concrete than most tool descriptions.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior; the description adds value by disclosing return semantics: unfilled fields come as `null`, nonexistent id returns an error, and `videoUrl` is `null` when no YouTube embed exists. It also enumerates the status enum values.

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

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

The description is front-loaded with the core verb and resource, and its long return-field list is dense and purposeful. It is slightly long for a single-parameter read operation, partially overlapping what an output schema would already carry, but it contains no filler.

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

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

For a single-parameter read tool with rich annotations and an output schema, the description covers the source of the id, error and null behavior, statuses, return fields, and the alternative listing tool. Nothing needed to call it correctly is missing.

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

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

The lone `id` parameter is fully documented in the schema as an integer sourced from senado_ecidadania_listar_eventos. The description reinforces where to obtain the id before calling, adding complementary guidance beyond the schema's 100% coverage.

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

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

States a precise verb and resource: 'Obtém o detalhe completo de um evento interativo do e-Cidadania.' It also separates itself from the listing sibling by naming the richer payload (pauta, convidados, videoUrl), so an agent can pick it without opening schemas.

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

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

Explicitly tells the agent to first obtain `id` via senado_ecidadania_listar_eventos and explicitly says not to use this tool for simple listing/ranking. This is fully actionable routing guidance.

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

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

Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description discloses meaningful behavioral quirks: the 'descricao' field is truncated at ~2000 characters, 'comentarios' is always null because the page lacks comments, and 'plConvertido' indicates conversion into a bill. This level of detail is excellent for a simple read tool.

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

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

The description is compact and front-loaded: purpose first, return fields second, then the usage prerequisite. Every sentence adds unique value, and the field list is dense but scannable.

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

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

For a one-parameter read-only tool, the description is complete: it identifies the required input, the key returned fields, important edge-case behavior (truncation and null comments), and how to obtain the id. The annotations and output schema handle the remaining 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?

The input schema already documents the only parameter 'id' with 100% coverage, so the baseline is 3. The description reinforces that the id comes from the list endpoint but does not add new semantic information about the parameter's format or constraints 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 begins with a specific verb and resource: 'Obtém o detalhe de uma ideia legislativa do e-Cidadania.' It clearly differentiates this tool from sibling tools like senado_ecidadania_listar_ideias and senado_ecidadania_obter_consulta by naming the exact resource type and level of 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?

The description provides an explicit prerequisite: 'Obtenha o id antes via senado_ecidadania_listar_ideias,' which tells the agent how to acquire the required parameter and when this tool is appropriate. It lacks explicit exclusions or comparisons to related 'obter' tools, so it does not fully reach a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail beyond annotations: it analyzes the complete set of open consultations and ideas, filters by polarization/consensus and minimum participation, returns at most 10 suggestions sorted by participation, and clarifies that count differs from totalQualificados. It also reveals that apenasEmTramitacao considers real status of consultations. No contradiction exists.

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

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

The description is dense but front-loaded: it opens with the tool's core purpose, then details the output contract, criteria defaults, and follow-up actions. Every sentence contributes useful information for selecting and invoking the tool correctly, with no filler or repetition of the title.

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—nested optional criteria, rich output, and many siblings—the description is complete. It explains input semantics, output fields and limits, ordering, the difference between count and totalQualificados, and how to investigate returned suggestions. Annotations cover safety and idempotence, and an output schema exists, so no critical context is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the optional criteria object's defaults and behavior, especially clarifying that apenasEmTramitacao 'considera só consultas abertas, com base no status real' and that minimoParticipacao defaults to 500. This goes beyond the schema's short field descriptions, though the schema already carries most 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 states a specific verb and resource: 'Sugere temas para uma enquete pública mensal' by analyzing e-Cidadania consultations and ideas and electing the most engaging ones. It clearly explains the tool's selection role and distinguishes it from list/obtain siblings by framing this as an analytical suggestion tool with a ranked output.

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 clear usage context: it is for selecting public poll themes and returns suggestions for further investigation. It explicitly routes follow-up behavior with 'Para investigar uma sugestão, use senado_ecidadania_obter_consulta ou senado_ecidadania_obter_ideia conforme o tipo.' However, it does not explicitly state when not to use this tool versus sibling analysis/list tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond the annotations: the exact response envelope `{ count, total, empresas }`, the item fields, the 'até 30 números' contract limit, and the partial-search behavior. This is useful context without contradicting 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 compact: one sentence covers purpose and search modes, the second covers response shape and usage constraints, and the final clause routes to related tools. There is no filler, repetition of the title, or unnecessary fluff. Every sentence earns its place.

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

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

Given the tool's moderate complexity, the description covers all essential aspects: search criteria, minimum length, required-term behavior, result limits, response shape, and follow-up tooling. The output schema and read-only annotations handle the remaining concerns, so nothing important is missing for an agent to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that `nome` or `cnpj` is required, that searches are partial, and how `limite` constrains the result list. It also explains the practical intent of the parameters in the context of a large base, which the schema alone does not convey.

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

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

The description opens with a specific verb and resource: 'Busca empresas que contratam com o Senado por nome (mín. 3 caracteres) ou CNPJ/CPF (busca parcial).' It clearly identifies the subject (companies contracting with the Senate) and the two search modes. It also distinguishes itself from related sibling tools by pointing to senado_contratos and senado_contratacao_detalhe for follow-up 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?

The description explicitly states the precondition: 'Exige nome ou cnpj (a base completa é grande)', explaining why at least one search term is necessary. It also names the downstream tools to use with the returned id/contract number, giving concrete guidance on when this tool is the entry point versus when to switch to another tool.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds key behavioral details: the shape of the response (`{ codigo, secao, encontro }`), that `encontro` may be an array when upstream returns multiple, that it may be empty if no data for that section, and that it errors on invalid `codigo`. These are useful operational facts not expressed in annotations. 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 yet information-dense. It front-loads the primary purpose, then logically presents the return structure, the section options, caveats (empty possible, error case), and finally the prerequisite step. Every sentence adds value; there is no fluff or repetition. The structure aids quick comprehension and correct usage.

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

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

For a two-parameter read-only tool with an output schema (mentioned in context), the description is remarkably complete. It covers the response structure, the meaning of the enum parameter, edge cases (empty result, invalid code), and the recommended way to obtain the required `codigo`. An agent has all necessary information to invoke this tool correctly without further clarification.

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

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

While the schema already provides descriptions for both parameters (100% coverage), the description enriches the meaning significantly. For `secao`, it explains each enum value in detail (e.g., 'detalhes' returns general session data; 'pauta' returns agenda items; 'resultado' returns voted items and outcomes; 'resumo' returns a summary). For `codigo`, it clarifies the source (obtained from other tools) and error behavior. This substantially goes beyond the schema's generic descriptions.

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

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

The description opens with a specific verb and resource: 'Detalhes de um encontro legislativo (sessão de plenário)' – clearly stating it returns details of a specific plenary session. It further distinguishes itself from sibling tools by explaining the return structure and that the `codigo` must come from `senado_agenda_plenario` or `senado_resultado_plenario`, which are list/request tools. This unambiguously separates it from the many other `senado_*` tools.

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

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

The description provides explicit guidance on when to use this tool: after obtaining a `codigo` from `senado_agenda_plenario` or `senado_resultado_plenario`. It also explains the `secao` parameter's valid values and what each returns, enabling the agent to choose the appropriate section. The note about erroring on a non-existent `codigo` further clarifies proper usage.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior, so the description only needs to add context. It adds useful behavior: the return object shape, the meaning of `caminho` and `nivel`, and the data source limitation (portal institucional, since the open-data API does not publish the full tree). It does not contradict annotations, though the prose 'TODAS as unidades' is slightly at odds with the schema's `limite` cap without an explicit truncation note.

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

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

The description is dense but every segment earns its place: definition, input/output behavior, example use cases, the explicit alternative, and the source caveat. It front-loads the core purpose so an agent scanning the first sentence already knows what the tool does. There is no filler or unnecessary repetition of the title.

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

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

For a two-parameter, read-only lookup with a present output schema, the description is nearly complete: it explains input format, output fields, depth semantics, typical use cases, and the alternative tool. It does not clarify behavior for unknown units or what happens when the subtree exceeds `limite` (whether `totalSubordinadas` reflects the true total), which an agent might need for correct interpretation. Overall it is sufficient for selection and basic invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The schema already documents that `unidade` accepts a sigla or name and that `limite` is an integer from 1 to 1000 defaulting to 200. The description mostly mirrors this and adds only the relationship between `unidade` and the resulting subárvore, without extra formats, constraints, or edge-case guidance.

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

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

The description opens with a specific definition—organizational structure/organograma of the Senado Federal down to service level—and states exactly what is returned for a given `unidade`: `caminho`, `totalSubordinadas`, and all `subordinadas`. It also distinguishes itself from `senado_servidores` by clarifying that this tool is for hierarchy, not for counting/listando servidores.

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

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

It gives concrete query intents ('o que está sob a DGER', 'quais secretarias/serviços pertencem a X') and explicitly says when not to use it: 'Para CONTAR ou LISTAR servidores sob uma unidade, use `senado_servidores` com `subordinadasA`.' This explicit when-to-use/when-not-to-use guidance is stronger than most sibling comparisons.

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=false. The description adds extensive behavioral context beyond these: automatic selection of the value column based on tipo, the result envelope { tipo, modo, ano, totalLinhas, ... }, ordering of agregado[], the default limite of 100 with truncation aviso, and how estatisticas changes behavior. 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 long but information-dense, with no filler. It is front-loaded with the core purpose, followed by statistics mode, return structure, and sibling distinction. While slightly dense and could be broken into clearer sections, every sentence earns its place in explaining a complex 8-parameter tool.

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

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

Given the tool's complexity (8 parameters, multiple modes, statistics behavior, output structure) and the presence of a rich output schema, the description covers essentially everything needed: parameter interplay, return shapes, ordering, defaults, truncation behavior, filtering advice, and sibling differentiation. No critical 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, but the description significantly enriches parameter meaning: it clarifies that campo is optional and defaults based on tipo, that modo is ignored when estatisticas=true, how agruparPor ranks groups by descending sum, and the effect of limite truncation. This goes well 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 function: querying the Senate's internal budget execution, covering despesas (expenditures with dotação, empenhado, liquidado, pago since 2013) and receitas próprias (revenues since 2012). It uses a specific verb with resource and explicitly distinguishes itself from the sibling senado_orcamento_parlamentar, 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 guidance on when to use this tool versus the alternative senado_orcamento_parlamentar ('não confundir...'), and details when to set estatisticas=true with and without agruparPor. It also advises filtering by ano before requesting detalhe to reduce data volume, giving clear context on usage.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses detailed runtime behavior: statistics computation, top/bottom defaults, grouping semantics, output structure, and the fact that `limite` is ignored when `estatisticas=true`. This significantly enriches the agent's mental model and does not contradict any annotation.

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

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

The description is dense but well-structured, with bolded mode labels, conditional branches, and clear separators. Every sentence adds operational value, and the alternative tool reference is placed at the end without bloating the core guidance.

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

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

Despite having 7 parameters and two distinct behavioral modes, the description covers all major decision points: when to use statistics, what grouping achieves, output shape in both modes, optional filters, and the relationship to a sibling tool. With annotated safety hints and an output schema present, nothing essential is missing.

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

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

With 100% schema description coverage, the baseline is already 3, and the description adds substantial cross-parameter semantics: how `estatisticas` changes the whole response shape, how `agruparPor` works only within statistics mode, and how `limite` behaves differently in each mode. This goes well beyond repeating 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 starts with a specific verb+resource: 'Horas extras pagas a servidores do Senado em ano/mes de referência' and clearly scopes the tool to overtime payments. It also distinguishes itself from the directly related sibling `senado_remuneracoes_servidores` by stating 'Para a remuneração completa do servidor use senado_remuneracoes_servidores', making its purpose unmistakable.

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 call with `estatisticas=true` versus without it, including concrete example queries like 'quem recebeu mais horas extras'. It also names the alternative tool for full remuneration, and explains the interaction of `agruparPor` with statistics mode, so an agent can route correctly without extra inference.

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

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

Annotations already convey that the tool is read-only, idempotent, and non-destructive. The description adds useful runtime context beyond that: raw administrative API records, the default and maximum 'limite' values, the no-filter error, and the next-step tool. It does not clarify how 'numero' and 'objeto' interact when both are supplied, but the main behavior is well disclosed.

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

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

The description is three compact sentences that front-load the purpose and then cover return shape, limits, error behavior, and a routing hint. Every sentence adds distinct value with 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?

For a read-only search tool with three optional-looking schema parameters, the description covers all invocation-critical details: accepted filters, mandatory-filter rule, result limits, return structure, and the related contract tool. The output schema and annotations supply the remaining detail, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the important cross-parameter constraint that at least one filter is mandatory despite the schema listing zero required fields, plus an example for 'numero' and the default/maximum for 'limite', which goes 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 action ('Busca'), the resource ('licitações do Senado'), and the two search modes: exact 'numero' or 'objeto' text. It also distinguishes itself from the contract-lookup sibling by pointing to senado_contratos, so an agent can tell what this tool is for without opening the schema.

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

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

Explicit usage conditions are provided: at least 'numero' or 'objeto' is required, and omitting both causes an error. It also tells the agent to use senado_contratos for the contract resulting from a licitação, which is a clear when-not-to-use rule.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses a data-quality gotcha: the source never publishes the parliamentarian's UF and it always comes null. It also reveals conditional field population (bloco only when leadership is of a bloc; partido only when of a party) and the default no-filter behavior.

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

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

The description is long but information-dense, with purpose front-loaded and every segment earning its place (return semantics, conditional fields, UF gotcha, filters, sibling routing). It slightly over-duplicates the casa value mapping already present in the schema, which keeps it from a perfect score.

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 covers return structure and annotations cover the safety profile, the description fills all remaining gaps: field semantics, the UF null workaround, default behavior, and sibling tool routing. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents casa, vigente, codigoParlamentar, and siglaTipoLideranca. The description adds only marginal parameter-level value — confirming the filter set and stating that omitting filters returns all houses.

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

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

The description opens with a specific verb+resource+scope — 'Lista as lideranças do Senado, da Câmara e do Congresso Nacional' — making clear it covers leadership positions across all three houses. It differentiates itself from related siblings by explicitly routing bloc composition to senado_listar_blocos and senator data to senado_obter_senador.

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 and alternative routing: 'Para a composição de blocos use senado_listar_blocos' and 'obtenha-a via senado_obter_senador pelo codigo'. The filter guidance ('Filtre por casa..., sem filtros retorna todas as casas') tells the agent exactly how to scope calls.

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 non-destructive behavior. The description adds valuable behavioral context beyond that: the list includes HISTORICAL composition, dataDesligamento marks departed parties, current members have null dataDesligamento, and the same party may appear multiple times with distinct periods—without this filter a party could seem to belong to two blocs simultaneously. This is exactly the kind of nuance an agent needs.

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

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

The description is three dense, front-loaded sentences: purpose, return shape, historical caveat, and routing to siblings. Each sentence earns its place, though the detailed enumeration of return fields may overlap with the output schema and could be slightly trimmed.

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 parameterless, read-only list tool with output schema and annotations, the description is complete: it states purpose, return shape, a critical data-interpretation caveat, and how to proceed to related tools. Nothing an agent needs to call it correctly or interpret its results is missing.

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

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

The tool has zero parameters, so the baseline is 4. There is no parameter semantics to document; the description appropriately focuses on output structure and usage guidance instead.

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

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

The description uses a specific verb and resource ('Lista todos os blocos parlamentares do Senado e seus partidos membros'), making the tool's scope immediately clear. It also differentiates itself from sibling tools by explaining that it is the way to discover a bloc's codigo before calling senado_obter_bloco, and that leadership information belongs to 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?

The description explicitly states when to use this tool ('Use para descobrir o codigo de um bloco e depois detalhá-lo via senado_obter_bloco') and names the alternative for a different need ('para lideranças use senado_liderancas'). It also warns about the historical composition pitfall, giving the agent concrete context for interpreting results correctly.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses the non-obvious behavior that the endpoint only ever returns active commissions and that `ativa=false` returns an empty result. It also specifies the response shape `{ count, comissoes }` and item fields, giving the agent a clear model of what to expect. 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?

Four short sentences deliver the action, filters, return shape, behavioral quirk, and target use case with no filler. The most decision-relevant facts (what it lists and filters) come first, and the downstream use case closes the description.

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

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

The tool is a simple filtered list, and the description covers its purpose, parameter semantics, return shape, edge-case behavior, and relationship to dependent tools. Annotations cover safety/idempotency and an output schema exists for return details, leaving no significant gaps for an agent deciding whether and how to call it.

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

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

Both parameters already have schema descriptions (100% coverage), so the baseline is 3. The description earns an extra point by explicitly stating the consequence of `ativa=false` (empty list) and by restating the `tipo` enum values for convenience, though it adds little beyond the schema for `tipo`.

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

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

The description opens with the specific action 'Lista comissões (colegiados) ativas do Senado' and the available filters `tipo` and `ativa`, making the resource and operation clear. It also differentiates this tool from siblings like `senado_obter_comissao` and `senado_reunioes_comissao` by framing it as the source for the `sigla` those tools require.

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 tells the agent when to use the tool: 'Use para descobrir a sigla exigida por senado_obter_comissao e senado_reunioes_comissao'. It also gives a clear when-not/limitation: the endpoint only returns active commissions, so `ativa=false` yields an empty list.

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

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

As anotações já cobrem readOnlyHint=true, idempotentHint=true e destructiveHint=false, então o bar é mais baixo. A descrição acrescenta contexto útil: correspondência parcial de nome ignorando acentos/maiúsculas, filtragem local de uf/partido, e a proveniência oficial do endpoint. Não contradiz 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 é mais longa que o ideal, mas cada frase carrega informação não redundante: exemplos de uso, filtros, semântica de busca, retorno e roteamento para ferramentas relacionadas. Está bem organizada com a informação mais importante (o que faz) no início.

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?

Com output schema presente e anotações cobrindo segurança, a descrição fornece tudo que um agente precisa: formato de retorno ({ count, senadores } com campos listados), comportamento dos filtros, e roteamento para as ferramentas subsequentes. Nada essencial para invocar corretamente está faltando.

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?

A cobertura do schema é 100%, mas a descrição adiciona significado além dele: explica que nome faz busca parcial sem acento e serve para obter codigo, que partido tolera formas curtas (PODE→PODEMOS), e detalha o comportamento de emExercicio como padrão. Isso é valor real que o schema não oferece.

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?

Descrição começa com exemplos concretos de uso ('liste os senadores em exercício', 'senadores atuais') e define o escopo: listar senadores em exercício ou de uma legislatura, com filtros opcionais. Distingue-se claramente dos irmãos senado_senadores_afastados e senado_senador_historico, e se posiciona como ponto de entrada ao citar senado_obter_senador e senado_votacoes_senador.

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?

Estabelece explicitamente quando usar (filtros por UF/partido, busca por nome) e quando não usar, nomeando a alternativa senado_senadores_afastados para senadores fora de exercício. Também instrui quando usar o filtro nome ('use quando você só tem o nome e precisa do codigo') e como reutilizar o código em outras ferramentas.

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

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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint false, the safety profile is fully covered. The description adds useful behavioral context by stating the exact returned object shape (`{ casa, mesa, count, membros }`) and the fields per member, which goes beyond the bare 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 compact: it states the purpose, explains the parameter, summarizes the return shape, and routes to an alternative in only three sentences. It is front-loaded with the main action and avoids repetitive detail.

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, single-parameter tool with an output schema and strong annotations, the description covers everything an agent needs: purpose, parameter selection, return structure, and the relevant sibling alternative. Nothing important is missing.

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

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

The schema already documents `casa` with an enum and per-value descriptions, so the baseline is 3. The description adds the default value (`padrão senado`) and clarifies the meaning of each choice, reinforcing semantic understanding even though the schema coverage is 100%.

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

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

The description uses a specific verb ('Lista') and names the exact resource ('membros da Mesa Diretora') along with the types of members (presidente, vice-presidentes, secretários). It also distinguishes itself from the sibling tool `senado_liderancas` by explicitly pointing leadership queries there.

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 choose each value of `casa` — `senado` for the Senado Federal and `congresso` for the Congresso Nacional. It also gives a clear 'do not use this for leadership' pointer to `senado_liderancas`, making the alternative explicit.

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

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

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds substantial behavioral context: coverage gaps, the empty-result contract (`totalBlocos` 0 with `aviso`), pagination truncation via `aviso`, the 20-block cap in `texto` mode, and mode-specific payload differences. There is no contradiction with the annotations; rather, the description enriches 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 dense but every sentence earns its place: return shape, empty-result behavior, coverage, mode semantics, pagination, id provenance, and media alternative. It front-loads the most critical information and organizes the rest in a logical decision order for an agent. Nothing is redundant.

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 is fully self-contained for a complex tool: it covers the return object, error/empty case, coverage exclusions, mode-specific behavior, pagination window, how to obtain IDs, and the correct alternative tool for media. With annotations and an output schema already available, nothing essential is missing.

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

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

Although schema coverage is 100%, the description goes far beyond it: it explains that `modo` governs the entire payload shape, that `sequenciaFim` only acts in `texto` mode, that `limite` defaults to 20 with truncation signaled by `aviso`, and that `orador` does partial content matching. These semantics are essential for correct invocation and are not apparent from the raw schema alone.

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

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

The description opens with a specific verb and resource: 'Transcrição oficial (notas taquigráficas) de uma sessão plenária ou reunião de comissão, em blocos sequenciais.' It precisely defines the deliverable and distinguishes itself from siblings like senado_videos_taquigrafia (media) and senado_discursos_* (speech-level content). An agent can immediately tell what this tool does and what it does not do.

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

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

The description gives explicit when-to-use guidance: 'Obtenha o id via senado_agenda_plenario/senado_resultado_plenario (sessão) ou senado_reuniao_comissao (reunião)' and 'Para a mídia (vídeo/áudio) use senado_videos_taquigrafia, não esta.' It also tells when notes are not available, such as joint/cancelled/some solemn sessions, so the agent can predict empty results. This is exemplary routing among alternatives.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds genuinely useful behavioral context: dataExtincao is null for active blocs, partidos is a historical composition where dataDesligamento indicates departure, and nonexistent codes return an error. 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?

Three sentences, all substantive: purpose, return semantics, and usage prerequisite/error behavior. No filler or repetition; the most important scoping information is front-loaded.

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

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

For a single-parameter detail tool with strong annotations and an output schema, this description covers everything needed to call it correctly: input source, return fields, semantic interpretation of nullable fields, and error behavior.

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

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

The schema already documents codigo with 100% coverage, so the baseline is 3. The description adds value by explaining where the code comes from (senado_listar_blocos) and what happens if an invalid code is used, justifying a 4.

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

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

The description states a specific verb and resource: 'Obtém detalhes de um bloco parlamentar específico pelo seu código.' This clearly distinguishes it from listing tools like senado_listar_blocos and from other detail tools like senado_obter_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?

The description explicitly tells the agent to obtain the codigo parameter first via senado_listar_blocos, which is strong workflow guidance. It does not explicitly state when not to use this tool or name direct alternatives beyond the prerequisite, so it stops short of a 5.

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

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

Even with readOnlyHint and idempotentHint already present, the description adds substantial behavioral context: `finalidade` is null with an `aviso` for permanent commissions, the sigla is resolved internally to a numeric code, and the exact output shape per `secao` is disclosed. This goes well beyond what the 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 front-loaded with the main action and then uses dense, structured inline JSON to convey output shapes and caveats. Every sentence contributes; it is a bit long, but the bulk is informative rather than redundant.

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, conditional null fields, an internal sigla resolution—the description is remarkably complete. It explains the presence or absence of `finalidade`, the member object structure, and how to discover valid input, leaving little ambiguity for the agent.

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

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

The schema already covers both parameters at 100%, so baseline is 3. The description adds value by explaining the default `secao` behavior, what each section returns, and how `sigla` gets resolved—plus the explicit pointer to `senado_listar_comissoes` for valid values. That lifts it above mere schema restatement.

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

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

The description opens with a specific verb and resource ('Obtém dados de uma comissão pela sigla') and explicitly distinguishes the two modes (`resumo` vs `membros`). It also ties the discovery of the `sigla` to the sibling `senado_listar_comissoes`, making it easy to tell this tool apart from the many other comissão-related 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 clearly conveys when to use this tool (to fetch details of a single commission by sigla and section) and points the agent to `senado_listar_comissoes` for discovering the sigla. It does not, however, explicitly state when NOT to use it relative to siblings like `senado_reunioes_comissao` or `senado_agenda_comissoes`, so it stops short of full when/when-not coverage.

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=false, and the description reinforces this with 'Somente leitura, sem efeitos colaterais.' It adds extra value by disclosing that the data is a live query to the official open-data base, that missing fields return null, and that nonexistent codes return the exact error 'Norma não encontrada' rather than an empty object.

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

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

The description is front-loaded with the core action and every sentence contributes useful information: read-only guarantee, return shape, null/error behavior, and routing to the sibling search tool. It is somewhat dense as a single paragraph, but there is no wasted material.

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

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

With only one required parameter, an output schema present, and rich annotations, the description still goes further to explain the prerequisite for obtaining `codigo`, the exact not-found behavior, and how missing fields are represented. Nothing an agent needs to call this tool correctly is missing.

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

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

The input schema already covers 100% of the single parameter, including its integer type, exclusiveminimum, and the warning not to confuse `codigo` with the law number. The description repeats this guidance, notably the distinction between `codigo` and the number of the law, so it adds little semantic 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 opens with a specific verb and resource: 'Obtém o detalhe de uma norma federal já promulgada pelo seu codigo interno.' It clearly differentiates itself from senado_buscar_legislacao by stating this tool is only for detail of an already identified norma, so an agent can distinguish the two without opening schemas.

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

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

The description explicitly says to obtain `codigo` first via `senado_buscar_legislacao`, and that norms should be located by tipo/número/ano using that sibling tool. It also states this tool is only for detail of an already identified norma, giving clear when-to-use versus 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 readOnly/idempotent/non-destructive behavior, and the description adds substantial behavioral detail beyond that: chronological ordering, truncation of tramitacao/textos with default limits, inclusion of an aviso when truncating, and count/total fields. This meaningfully informs the agent about response behavior. No contradiction with annotations.

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

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

The description is dense but well-structured, front-loading the core operation and using clear mode-by-mode organization. It is long, but nearly every clause earns its place given the tool's tri-mode behavior; a slight trim of repeated schema-level field names would make it tighter.

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

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

For a tool with three distinct output modes, the description covers all necessary invocation details: defaults, truncation behavior, ordering, the required parameter's source, and the structure returned under each secao. Combined with the output schema and annotations, an agent has everything needed to call this tool correctly.

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

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

Schema coverage is 100%, but the description goes well beyond the schema: it explains how secao changes the entire return shape, clarifies that limite only applies to tramitacao/textos with distinct defaults, and tells the agent where codigoMateria should come from. This adds real semantic value beyond field names and types.

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

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

The description opens with a specific verb and resource: 'Obtém dados de uma matéria pelo codigoMateria'. It then enumerates the three output modes (detalhe, tramitacao, textos), making the tool's scope clear and distinguishing it from search/list 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?

The description gives clear context for when to use each section and instructs the agent to obtain codigoMateria via senado_buscar_materias. It does not explicitly state when not to use this tool versus other matter-related siblings, but the section-level guidance is strong enough to route correct usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description's job is lighter. It adds useful behavioral context by describing the full response shape, including the conditional normaGerada field and the current state fields, and by noting the workflow prerequisite that the id comes from another tool. There is no contradiction with 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 front-loaded with the core purpose and then moves to return content and routing guidance. It is dense rather than bloated, though the long field enumeration could be trimmed if the output schema already documents the response object. Overall, every sentence serves a clear role.

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

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

For a single-parameter, read-only tool with annotations and an output schema available, the description covers the essential invocation context: what the tool returns, where the id comes from, and which sibling should be used for related but different details. It does not discuss error behavior for nonexistent ids, but that is not a critical gap for this simple read operation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by explaining that the parameter is obtained from senado_search_processos or senado_buscar_materias and by clarifying the practical meaning of the id. It does not fully resolve the minor mismatch between the description's 'id' and the schema's idProcesso, but it later uses the correct name.

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

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

The description states a specific verb ('Obtém') and resource ('um processo legislativo específico pelo seu id'), and explicitly distinguishes itself from senado_processo_detalhe by saying that emendas, relatorias, and prazos are handled there. This makes the tool's identity and scope immediately clear.

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

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

It gives explicit prerequisites ('Obtenha o idProcesso antes via senado_search_processos ou senado_buscar_materias') and names the alternative for overlapping concerns ('para emendas, relatorias ou prazos use senado_processo_detalhe'). The agent is told exactly when and how to route around 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 already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context by detailing the exact shape of the returned object, including nested 'mandatos' fields, and by explaining the required input's provenance. It does not discuss error cases or data freshness, but the annotation coverage lowers the burden.

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 with no filler: purpose, return shape, required parameter, and routing to an alternative. The essential information is front-loaded, and the field list is compact and useful rather than redundant.

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

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

For a single-parameter, read-only tool with a rich output schema and strong annotations, the description covers everything an agent needs: what the tool returns, what input it requires, how to obtain that input, and when to choose a different sibling. Nothing material is missing.

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

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

The single parameter is fully described in the schema with a clear meaning. The description adds beyond the schema by stating that codigoSenador is required and by instructing the agent how to obtain it via senado_listar_senadores, which helps 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 opens with a specific verb and resource: 'Obtém o detalhe biográfico de um senador específico.' It then enumerates the returned fields and explicitly differentiates this tool from senado_senador_historico, making its scope unmistakable among many 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 clearly states when to use this tool (for biographical details) and how to obtain the required identifier via senado_listar_senadores with the 'nome' filter. It also explicitly lists which use cases should go to senado_senador_historico instead, providing both inclusion and exclusion 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 the operation read-only and idempotent, and the description adds substantial behavioral context beyond that: it details the returned fields (placar, `resultado`, `resultadoCodigo`, `secreta`, `votos[]`) and the alternate return shape (`{ codigoSessao, count, votacoes }`) when multiple votes exist. It also highlights the non-obvious risk of numeric code collisions with commission votes.

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?

Every sentence earns its place: the function, the return shape, the prerequisite, and the critical warning are all present without filler or repetition. The warning is placed at the end where it is most memorable, and the structure is easy to scan.

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

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

The description covers the complete call path: how to obtain the input ID, what domain the ID must come from, what return shapes to expect, and the safety profile already reinforced by annotations. With an output schema present and the description still explaining the main variations, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already describes `codigoVotacao` as the `codigoSessao` of the plenary session, so the baseline is 3. The description adds value by stating the provenance (obtain it from `senado_search_votacoes`) and the plenary-only boundary condition, which is meaningful beyond the raw 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 a specific action ('Obtém detalhes') on a specific resource ('votação de plenário') keyed by `codigoVotacao` and explicitly scopes it to plenary votes, including nominal votes. It also names the sibling space `senado_votacao_comissao` to prevent confusion, clearly distinguishing it from related tools.

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

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

It explicitly instructs the agent to obtain `codigoSessao` via `senado_search_votacoes` before calling, and explicitly warns that codes from `senado_votacao_comissao` are invalid because they belong to a different numbering space. This provides both a when-to-use condition and an explicit exclusion.

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, open-world, and non-destructive behavior. The description adds important behavioral context: the difference between proposição and execution documents, the fact that the ofício date differs from the budget year, the optional `aviso?` field, and the expansion behavior of `incluirEmendas`. No contradiction with annotations.

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

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

The description is dense and free of fluff, front-loading the `tipo` duality before optional details. It loses one point because it is structured as one long paragraph with nested clauses; bullet points or short labeled sections would make it easier for an agent to scan.

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

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

For a two-mode tool with five parameters, the description covers mode-specific response shapes, the `ano` caveat, pagination, optional emenda details, and the sibling alternative. With annotations covering safety and an output schema present, nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, and the description still adds meaning beyond the schema: it explains why filtering by `ano` is recommended, clarifies that `limite`/`pagina` apply to the `oficios` mode, and describes what `incluirEmendas: true` adds to the response. This is practical invocation knowledge, not just schema restatement.

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 identifies the resource (emendas parlamentares ao orçamento da União) and clearly distinguishes the two modes: `tipo: emendas` (propositions) and `tipo: oficios` (execution). It also explicitly separates this tool from `senado_execucao_orcamentaria`, so the agent can select it correctly.

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

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

The description gives explicit usage guidance: filter by `ano` because the base covers multiple years, use `limite`/`pagina` for pagination, and use `incluirEmendas: true` for detailed emendas. It also names the sibling tool that should be used for internal Senate budget execution, providing a clear when-to-use vs. alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description does not contradict them. The description adds meaningful behavioral context beyond annotations by specifying exactly what each returned item contains, including quorum and per-party orientations, and clarifies this is a safe read-only operation.

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

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

The description is front-loaded with its purpose and uses three dense sentences: what it returns, how to parameterize it, and which sibling to use instead. Every sentence earns its place, with no filler or redundant restatement of the tool name.

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

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

Given an output schema and annotations that already cover safety, the description leaves no critical gap. An agent knows what data will come back, how to supply the date filters, and when to route to senado_resultado_plenario instead.

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

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

Schema coverage is 100%, so the date format and field purpose are already documented. The description adds the key semantic rule that data is for a single day while dataInicio/dataFim define a period, which is not encoded in the schema properties themselves.

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

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

The description states the exact resource: party leadership vote orientations in plenary votes, including the resulting scoreboard. It explicitly positions the tool as essential for party discipline analysis, and the final sentence distinguishes it from senado_resultado_plenario so an agent can tell them apart.

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

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

It gives explicit input guidance: pass a single day via data or a period via dataInicio/dataFim. It also names senado_resultado_plenario as the alternative for session results, providing both a when-to-use and a when-not-to-use signal.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses the exact return shape `{ tabela, count, total, aviso?, registros[] }`, the empty-table behavior (count 0, empty list), the limit default/max, and how filtro matches any field. It also notes the aviso field, adding valuable runtime 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 dense but every sentence earns its place: scope, table categorization, return format, limits, edge cases, filter semantics, and alternative tool routing. It is well-structured with clear punctuation and 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?

Despite the tool's complexity (8 table types, mixed aggregate/nominal behavior, optional filter, output schema), the description covers all necessary information: table enumeration, return structure, empty behavior, pagination limits, filter semantics, and sibling routing. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaningful semantics: it explains each tabela value as either aggregate or nominal, defines what each table contains (e.g., 'cargos-funcoes' = comissão/confiança), and clarifies that filtro matches any record field—beyond the schema's generic 'Filtro textual (nome, curso, setor...)'.

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 a specific verb and resource ('Tabelas de pessoal do Senado conforme o parâmetro tabela') and enumerates all table types with their content. It explicitly distinguishes itself from the sibling senado_servidores, making the tool's scope 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 gives explicit when-to-use context by separating aggregated quantitative tables from nominal lists, and provides a direct when-not/alternative instruction: 'Para o cadastro nominal de servidores efetivos/comissionados use senado_servidores.' This is clear routing guidance.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds substantial behavior beyond the annotations: pagination limit (`limite` default 100/máx 500), the return envelope with optional `aviso`, acceptance of two date formats, and the mandatory-filter constraint.

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

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

Long but information-dense; the core purpose is front-loaded and each `secao` mode is structured compactly with → notation. Every sentence earns its place given the 10-parameter, 3-mode complexity, though the full field enumerations could theoretically be trimmed.

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 10-parameter, 3-mode tool this is unusually complete: it specifies per-section outputs and filter applicability, the shared filter set, pagination behavior, return envelope, prerequisite sibling tools, and examples. Even with an output schema present, the description leaves no gap for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema: cross-parameter relationships (which filters apply to which `secao`), the runtime requirement of at least one filter, and concrete valid combinations via examples like `{ secao: 'emendas', codigoMateria: 137999 }`.

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 a specific verb ('Detalha') with a precise resource ('aspecto de processos legislativos') and disambiguates three sub-modes via the `secao` enum. It is clearly distinguishable from siblings like `senado_obter_processo` (full process detail) and `senado_search_processos` (search), and even routes the agent to the correct sibling for obtaining `idProcesso`.

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

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

Gives concrete workflow guidance: obtain `idProcesso` via `senado_search_processos` and prazo types via `senado_tabelas_processo`, plus valid example payloads per section. It clearly states the 'informe pelo menos um filtro' requirement, but does not explicitly name when-not scenarios against alternatives like `senado_obter_processo`.

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