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

With no annotations, the description must carry the full behavioral burden. It does disclose the key trait — that it bypasses the local cache and forces a network download — which tells the agent results may differ from cached reads. It omits whether this mutates only local state or also hits the remote service, whether it can fail/rate-limit, and how long it may take.

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

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

A single sentence with the operative verb ('Força um novo download') front-loaded and the cache-bypass qualifier trailing it. Nothing is wasted and nothing needs reordering.

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

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

For a zero-parameter tool this is close to sufficient, but there is no output schema and no annotations, so the description should say what happens after the refresh — whether it returns the fresh data, only an acknowledgement, or requires a follow-up call to resumo_geral/listar_posts. That omission leaves the agent guessing about next steps.

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

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

The tool takes zero parameters and the schema has no properties, so there is no parameter semantics to document. The baseline of 4 applies; the description correctly implies no inputs are needed.

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

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

The description states a specific action and target: force a fresh download of the Flaviômetro feed, bypassing the local cache. That is far more concrete than the generic name/title 'Atualizar dados', so the description does the differentiating work. It doesn't name a sibling, which keeps it just short of a 5.

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

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

Using it implicitly means 'I want fresh data rather than cached data', and that condition is conveyed by 'ignorando o cache local'. However, there is no explicit when-to-use/when-not guidance, no mention of cost or latency that would deter an agent from calling it before every read, and no pointer to the sibling read tools that consume the refreshed feed.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Lista' implies a read-only operation and the description explains the semantics of the behavior dimension, but it says nothing about result volume, pagination/limite behavior, or what an empty result means.

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

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

Two sentences, zero waste: capability first, then a concrete example. The example earns its place by tying filters to a realistic query.

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

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

For an 11-parameter, all-optional filter tool with no output schema and no annotations, the description conveys what can be filtered and what the behavior codes mean at a high level. What remains uncovered (result shape, pagination beyond 'limite', behavior with zero matches) is minor but not fully absent.

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 91%, so nearly every parameter's meaning is already documented in the schema. The description repeats the filter list (nome, UF, cargo, partido, situação, município) and the four behavior categories without adding syntax, defaults, or interaction rules beyond what the schema provides.

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

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

States a specific verb and resource ('Lista políticos monitorados') and enumerates the filter dimensions, including the distinctive behavior filter relative to Flávio. The scope is unambiguous and clearly different from a detail or ranking tool, though no sibling is named explicitly.

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 example question ('quais deputados federais do PL de SP não citaram o Flávio?') gives concrete usage context that maps directly onto the filters, so an agent knows when this tool fits. It stops short of stating exclusions or naming alternatives like detalhes_politico or ranking.

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 no annotations, the description carries the load and does well: it discloses the two external data sources, the exact fields returned, the coverage boundary, and the one-at-a-time constraint. It omits failure behavior — what happens when the candidate is not found in TSE or the CNPJ is missing from OpenCNPJ (error vs. partial result) — which matters for a chained lookup.

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 main action is front-loaded in the first sentence, followed by the supplementary payload, scope limits, and cardinality constraint. Efficient overall, though the scope sentence ('não cobre prefeitos nem senadores em mandato') sits slightly at odds with the earlier mention of senadores and could be tightened.

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

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

For a single-parameter, no-output-schema lookup, the description explains both sources and enumerates the returned fields, so an agent knows what it will get. The remaining gap is behavior on missing or ambiguous matches, which is the one thing an agent cannot infer here.

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 explains that 'politico' accepts a name, partial name, or sq code. The description only adds the constraint that only one politician can be queried per call; it adds nothing about matching behavior for partial names or ambiguity resolution.

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 concrete two-step operation: fetch the candidate's 2026 campaign CNPJ from TSE open data, then look that CNPJ up in OpenCNPJ (Receita Federal) for email, phone and address. It also names the extra payload (coligação, resultado, DivulgaCandContas link), which makes it clearly distinct from generic siblings like buscar_politicos or detalhes_politico.

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 applicability and exclusions: works for 2026 governor/senator/deputy candidates, does not cover mayors or sitting senators, and handles one politician per call. It never names an alternative sibling (e.g. detalhes_politico) for the excluded cases, so it stops short of full 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?

No annotations exist, so the description carries the burden here. It does meaningfully disclose the return payload (which stands in for the missing output schema), but it says nothing about read-only behavior, pagination, error handling for an unmatched 'politico', or the cost of setting a high posts value.

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

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

A single tight sentence with no filler, and the core concept ('Ficha completa de um político') is front-loaded. The trailing enumeration of fields is a dense list, but each item 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?

With no output schema and no annotations, the field enumeration is the main thing that makes this callable, and it covers the payload well; the three input parameters are fully documented in the schema. The remaining gap is edge-case behavior (not found, ambiguous name), which the description leaves unstated.

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

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

Schema description coverage is 100%, so the schema already defines all three parameters, including the posts default/max of 100 and incluir_posts_sem_citacao. The description only hints at the posts parameter via 'os posts mais recentes em que citou o Flávio' and adds nothing about name matching or the sq code.

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?

It clearly says this returns a complete profile ('ficha completa') of a politician and enumerates exactly what the profile contains: cargo, partido, votos, redes monitoradas, janela de cobertura, estatísticas por rede, posts recentes. That makes the purpose readable without the schema, but the description never contrasts it with siblings like buscar_politicos (search), listar_posts or estatisticas_agrupadas, which could partly overlap.

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?

There is no guidance on when to use this tool instead of buscar_politicos, listar_posts or estatisticas_agrupadas. An agent must infer that this is the 'one politician, all details' call, and nothing says what to do if the name is ambiguous or the politician is not found.

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 no annotations, the description carries the full burden. It discloses the aggregation semantics and the two metrics counted per group, but it does not explicitly state that the operation is read-only, nor does it describe permissions, side effects, or output structure.

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

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

The definition is a single front-loaded sentence with no wasted words. It efficiently states the aggregation behavior and the metrics before listing grouping dimensions.

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 9-parameter aggregation tool with no annotations and no output schema, the description is adequate but incomplete. It explains the core aggregation and metrics, but it lacks usage guidance versus siblings and does not describe the return shape beyond raw counts per group.

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 high at 89%, so the schema already documents most parameters. The description maps several grouping choices (state, party, office, social network, day), but it omits the situacao grouping option and does not explain the filter 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 uses a specific verb and resource: it aggregates counts by group and names the metrics (politicians who cited/requested vote and posts citing Flávio). It is clear what the tool computes, but it does not explicitly distinguish itself from siblings such as ranking or resumo_geral.

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?

There is no explicit guidance on when to use this tool versus alternatives like ranking or resumo_geral. The grouping dimensions imply a grouped-statistics use case, but the description provides no exclusions or routing advice.

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 no annotations, the description carries the full behavioral burden. It discloses the content categories covered (cargos, situações, redes, níveis de citação) and methodology, but does not describe the return format or whether the response is text, structured data, or exhaustive.

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

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

A single, front-loaded sentence that lists the relevant code types and methodology without filler. Every element contributes to understanding the tool's scope.

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, zero-parameter explanatory tool with no output schema, the description is nearly complete: it says what codes and methodology are explained. It could be slightly richer by indicating the return format, but the essential scope is clear.

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

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

The tool has zero parameters, so parameter semantics are not a concern. The baseline for zero-parameter tools is 4, and the description appropriately does not need to explain inputs.

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

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

The description states a specific verb ('Explica') and resource ('códigos usados nos dados... e a metodologia'), making clear it is an explanatory/metadata tool. It does not explicitly name or contrast with sibling tools, but its purpose is distinct from data-retrieval siblings like buscar_politicos or ranking.

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

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

The description implies the tool is for understanding codes and methodology, but it gives no explicit guidance on when to use it versus alternatives or prerequisites. No when/when-not conditions or sibling references are provided.

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 no annotations, the description carries the full burden. It does disclose two important behavioral facts beyond the schema: results are silently limited to posts citing Flávio by default, and default ordering is newest-first. That is genuinely useful for a read tool that would otherwise appear to return everything. However, pagination, result-set size limits, and the returned record shape are not mentioned.

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

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

Two sentences, no filler, and the default-scope caveat is placed prominently. Slightly more could be front-loaded, but it is efficient and readable.

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 14-parameter read tool with no annotations and no output schema, the description covers the most critical surprise (default filtering to Flávio citations) but leaves out what a post record contains and how to page through results. The schema carries most of the parameter burden, so this is adequate without being complete.

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

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

Schema coverage is 86%, so the schema already documents nearly every parameter including enums and defaults; baseline is 3. The description's mention of filter categories (político, rede, nível de citação, período, texto) only restates what the schema shows in more detail, adding no new 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 and resource ('Lista posts captados pelo Flaviômetro') plus the filter axes it supports, which is enough to distinguish it from siblings like ranking or estatisticas_agrupadas that also deal with posts/politicians. It does not explicitly name a sibling, so it falls short of a 5.

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

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

The description implies the use case (browsing individual posts with filters) and clarifies the default scope, but never says when to prefer this over ranking, estatisticas_agrupadas, or detalhes_politico. Usage is inferable rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden and largely fails to. It never confirms this is a read-only operation, never states sort direction, tie-breaking, or pagination behavior, and gives no indication of the response shape despite there being no output schema. The only behavioral hint ('que mais citaram') implies descending order but leaves it unstated.

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

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

Two sentences, front-loaded with what the ranking measures, with the metric list and filter pointer following. No filler. Slightly terse to the point of omitting needed information, but 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?

For a 10-parameter tool with no annotations and no output schema, the description covers the 'what' adequately but not the 'what comes back'. An agent knows it gets a ranking of politicians by a chosen metric, but not the fields per entry (position, metric value, name, party) or ordering guarantees. This is minimum viable rather than complete.

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

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

Schema description coverage is 80%, so most parameters (uf, desde, ate, nome, cargo, partido, situacao, municipio) are already documented in the schema, and metrica's four values are in the schema enum. The description adds no per-parameter meaning beyond repeating the metric names. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource — ranks politicians by how much they cited Flávio — and enumerates the four metrics that define the ranking, so the agent knows exactly what the output orders. It also references the buscar_politicos filter set, which separates it from the plain search sibling. It does not differentiate itself from estatisticas_agrupadas, which is the closest ambiguous alternative.

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

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

"Aceita os mesmos filtros de buscar_politicos" gives useful context about the filter model but is a schema hint, not usage guidance. There is no statement of when to pick ranking over buscar_politicos or estatisticas_agrupadas, nor any exclusion. Usage is only implied by the word 'Ranking'.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the shape of the returned metrics in prose, which is valuable since there is no output schema, but it says nothing about the read-only nature, permission requirements, aggregation basis, or how the silent/cited classifications are determined.

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

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

Two sentences: the first front-loads exactly what the panorama contains, the second gives the usage cue. No filler and nothing 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 zero-required-parameter, read-only aggregate with no output schema, the description successfully conveys what comes back and when to reach for it. The main residual gap is the total silence on the optional date-range filter, which an agent might not realize applies to this tool.

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

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

Schema description coverage is 100% — both 'desde' and 'ate' are documented in the schema with format and timezone (horário de Brasília). The description never mentions the period filter, so it adds nothing beyond the schema. Baseline 3 is appropriate.

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

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

The description enumerates concretely what the tool returns: counts of monitored politicians who cited Flávio, asked for votes, or stayed silent, plus post totals and a breakdown by office. That is a specific, differentiated role versus detail-oriented siblings such as detalhes_politico or listar_posts. It stops short of an explicit verb+resource framing (it is a noun phrase, 'Panorama do Flaviômetro'), so it is clear but not exemplary.

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?

'Use como ponto de partida' gives a clear contextual instruction: call this first, then drill down with the more specific siblings. There are no explicit exclusions or named alternatives, but the positioning as an entry point is unambiguous for an agent orienting itself.

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