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

Goes well beyond the readOnly/idempotent annotations: fixed urna-number ordering, an explicit refusal to rank, score or recommend, a list of fields never returned (CPF, título, birth date, age, gender, race, marital status, schooling), and a note that names/coalitions/links are candidate-declared data rather than instructions. That is unusually rich behavioral and safety disclosure.

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?

One dense paragraph, front-loaded with the core comparison scope before the ordering rules, exclusions and injection warning. Slight redundancy in the triple negative ("não ordena por valor, não pontua e não recomenda voto"), but every sentence carries substantive information.

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

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

With an output schema present, the description need not explain return values, and it covers everything else: selector resolution, default round behavior, ordering guarantee, and privacy exclusions. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning by explaining that numbers and sq_candidatos are interchangeable selectors, that both must resolve to 2-4 entries, and what happens when both are omitted — semantics the schema only hints at.

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 ("Compara lado a lado de 2 a 4 candidaturas do mesmo cargo, UF e turno") plus the exact fields compared. The scope constraint (2-4 candidacies, same office/UF/round) separates it cleanly from list_candidates and get_candidate without opening any schema.

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

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

Gives clear usage conditions and a default path: with neither sq_candidatos nor numbers it compares all candidacies on the urna when there are 2-4 (the runoff case). It does not explicitly name the sibling tools (list_candidates, get_candidate) as alternatives, so routing is implied 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds provenance context by promising an 'fonte oficial', which is genuinely useful, but says nothing about data freshness, error behavior, or coverage limits beyond what the schema implies.

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 short sentences, front-loaded with the returned content and followed by the user questions it answers. Every clause carries information; 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?

With an output schema present, return-value explanation is not required, and the read-only annotations cover the safety profile. What remains thin is scope: it does not say whether it covers a single election/round or any date passed via 'on', leaving a small inference gap for a zero-required-parameter tool.

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

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

Schema coverage is 100% and the single 'on' parameter is fully documented in the schema (AAAA-MM-DD, default today, Brasília time). The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

The description names a concrete subject (data e horário da votação, turnos, cargos em disputa, fonte oficial), so an agent immediately knows this returns election schedule facts rather than candidate or polling-place data. It never explicitly contrasts itself with siblings like find_polling_place or list_candidates, but the subject matter is distinctive enough that confusion is unlikely.

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 maps two user intents directly onto the tool ('quando é a eleição' and 'até que horas posso votar'), which gives clear context for invocation. It offers no exclusions or explicit alternatives, so it stops short of full when/when-not 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=true, idempotentHint=true and openWorldHint=false, so safety and determinism are covered. The description adds the accepted-input constraint (no name/CPF/título), which is useful scope context, but nothing about the round default behavior or what is returned when no polling place is found.

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

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

Two tight sentences with zero filler, front-loading the resource and the input source before the exclusion. Every clause either defines the lookup or prevents a wrong call.

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

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

An output schema exists, so return values need not be described, and the annotations carry the safety profile. The description covers purpose, inputs, and the main misuse case, though the optional 'round' parameter's behavior is left entirely to the 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 description coverage is 100%, so uf/zone/section/round are already documented in the schema, including zero-padding and the exterior 'ZZ' case. The description only restates that these three come from the título; it adds no meaning beyond the schema, which is the baseline 3 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 ('Encontra o local de votação') and pins the exact inputs (UF, zona, seção) taken from the voter registration card. It also carves out what it does not do (nome, CPF, número do título), which implicitly separates it from the lookup-by-name sibling.

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 a clear negative condition — it does not accept name, CPF, or title number — and routes the user to e-Título to discover their own zone and section. It stops short of naming the sibling tool (search_polling_places) as the alternative for name-based queries, so the routing is external rather than in-catalog.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), yet the description adds substantive context beyond them: what the response contains (running mate/suplentes, declared social networks, official DivulgaCandContas link), explicit privacy exclusions (no CPF, voter ID, birth date, email), and an injection-safety note that names/coalitions/links are data, never instructions.

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

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

Two dense sentences, purpose front-loaded, and every clause carries distinct value (lookup keys, return contents, privacy bounds, injection warning). 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?

An output schema exists so return values need not be detailed, and the description nonetheless summarizes them; annotations carry the safety profile. The privacy exclusions and injection note close the remaining gaps for an agent calling 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 description coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it clarifies that sq_candidato and the UF/office/number trio are alternative lookup strategies, an OR relationship the schema never states.

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

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

States a specific verb+resource (retrieve a candidate's profile) and enumerates the exact lookup keys: sq_candidato, or UF+office+number. This distinguishes it from list_candidates (a list) and compare_candidates, so an agent can select it without opening the schema.

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

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

It gives clear context for when this tool applies by spelling out the two alternative lookup paths, which is the key decision an agent must make. It does not explicitly name siblings (e.g. list_candidates) or state when not to use it, 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, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: explicit PII exclusions (no CPF, título de eleitor, birth date or email) and a prompt-injection safety note that names/links are data, not instructions.

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

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

Three sentences, front-loaded with what is listed and how it can be filtered, followed by the privacy and injection-safety caveats. No filler, though the two safety sentences could be tightened into one.

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

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

An output schema exists, so return values need no explanation. For an eight-parameter, read-only list tool the description covers purpose, filters, and privacy/safety guarantees adequately; only sibling routing 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 schema already documents all eight parameters including the uf/office/party/name semantics. The description restates the filter options but adds no format or syntax detail beyond the schema; baseline 3 applies.

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

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

States a specific verb ('Lista') and resource ('os candidatos de um cargo numa UF') with scope clarification ('BR para presidente'), which lets an agent distinguish it from get_candidate or compare_candidates 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?

The description conveys the filter context ('com filtro por partido ou por nome de urna ou nome civil'), implying when the tool is appropriate, but it never names an alternative or states when NOT to use it (e.g., versus get_candidate for a single record). Usage is inferable but not routed.

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 openWorldHint=false, so the safety profile is covered. The description adds the accent-insensitive matching behavior, which is genuinely useful, but it stays silent on ambiguity handling (multiple matches) despite exposing a limit parameter.

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 that front-loads the verb and resource and ends with the downstream-use rationale. 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?

An output schema exists, so return values need not be explained. Still, for a resolver that can plausibly return multiple candidates (hence the limit param), the description omits what happens on ambiguous or unmatched names, leaving a real gap.

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 uf, name and limit are already documented in the schema. The description's note about accents duplicates the name parameter's own schema description rather than adding new 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?

States a specific verb+resource ('Encontra o código de um município a partir do nome') and adds the scope qualifier that accents are optional. It clearly reads as a resolver/lookup, distinguishable from the election-oriented siblings, though it does not name any sibling 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?

'para usar nas outras ferramentas' implies this is a prerequisite resolution step in a larger workflow, which is useful usage context. However it gives no explicit when-to-use/when-not-to-use guidance and names no alternative for looking up municipalities.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context by stating results are ordered by distance when coordinates are supplied, but that ordering is also disclosed in the "near" schema description, and pagination/limit behavior is left entirely to the schema.

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

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

Two sentences with no filler. Scope, filters and ordering come first, and the audience/routing hint is placed last where it is most useful.

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

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

An output schema exists, so return values need not be described, and the description covers scope, filters, ordering and audience. Minor gaps remain around pagination (offset/limit) and how multiple filters combine, which the schema documents but the description does not synthesize.

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 every one of the 8 parameters is already documented (including the round default and limit range). The description restates the filter dimensions (bairro, nome, endereço, coordenadas) but adds no syntax, format or interaction detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb and resource ("Lista os locais de votação de um município") and immediately scopes it with the available filters (bairro, nome, endereço) and the distance-ordering behavior. The closing line ("Para quem não sabe a zona e a seção") implicitly separates it from find_polling_place, which serves users who do know their zone/section.

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?

"Para quem não sabe a zona e a seção" gives a clear condition for choosing this tool over a zone/section-based lookup, so the when-to-use case is explicit. It stops short of naming the alternative tool or stating any when-not-to-use condition, 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.