Eleições 2026: Dados Públicos do TSE

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

The description adds useful behavior beyond the annotations: config header yields a permanent connection, while passing a token yields a session-only login, and no args returns a link. It does not fully spell out side effects or success/failure return values, but annotations already cover idempotency and non-destructiveness.

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

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

The description is dense and front-loaded, with no fluff, but the long single sentence with parenthetical clauses and multiple alternatives could be structured into clearer separate instructions. Still, every part adds necessary information.

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

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

For a one-parameter auth tool with no output schema, it covers the no-arg return (the link), the token-paste path, and the persistent-config alternative. It doesn't state the response on a token success/failure, but the invocation guidance is sufficient for an agent 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?

With 0% schema coverage, the description carries the full burden for the optional `token` parameter. It explains that token is a JWT/access token pasted by the user and how to pass it, compensating well for the bare schema.

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

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

The description clearly identifies the tool as MCP.AI authentication for IDE agents, with a concrete browser-login + access-token flow and two invocation paths (no args for a link, token for login). This specific verb+resource is unambiguous and easily distinguished from the unrelated calculo_* sibling 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 differentiates the persistent config-header approach ('best... permanent, non-expiring') from the session-only paste/login path, and states exactly when to call with no args versus with { token }. This gives the agent clear selection criteria for both setup and invocation.

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

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

Annotations already establish this is read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that by specifying the two main response states: authenticated:true with empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. This helps an agent predict what to expect.

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, front-loads the core purpose, and then adds only the essential conditional details. Every sentence contributes meaningful information, and there is no waste.

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

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

For a zero-parameter read-only status tool with no output schema, the description is complete enough. It tells the agent what information will be returned, what the success condition looks like, and what happens when credentials are missing. The low complexity means no additional guidance is required.

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

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

The tool has zero parameters, so the description does not need to explain any input semantics. The baseline of 4 applies because there is no parameter burden at all.

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

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

The description clearly states the tool's purpose: returning connection status and URLs. It distinguishes connect from its sibling authenticate by framing it as a status/read operation rather than an action, and the conditional output descriptions reinforce this.

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 makes clear that this is the tool to call when checking connection state or getting URLs. It does not explicitly mention alternatives like authenticate, but the context strongly implies connect is for status checking rather than initiating authentication, so usage is clear without being fully 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?

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, and the description adds genuinely new context: aggregation from boletins de urna, official 2nd-round data only for presidente/governador, and the single-match municipality behavior. The privacy statement (no CPF, birth date or e-mail) is a meaningful addition beyond structured fields.

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

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

Front-loaded with purpose and dense with useful detail; the second sentence on privacy earns its place. The first sentence is long and clause-heavy, which slightly hurts scanability but wastes no words.

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

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

With no output schema, the description does the work of describing return contents (party, office, UF, situation, 1st-round votes, top municipalities, 2nd round for executive races). For a read-only lookup tool, an agent has what it needs to call it correctly, with only the 'ano' semantics as a minor 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 0%, so the description must carry the burden. It explains 'termos' (urna name or number) and enumerates the cargo values well, and 'uf' appears implicitly, but the 'ano' parameter is never addressed and the text hardcodes 2026, leaving ambiguity about what that parameter does.

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 (buscar) and resource (candidato) plus the scope: all 2026 offices, looked up by urna name or number. It also enumerates the returned fields (partido, cargo, UF, situação, votos), which clearly separates it from siblings like eleicoes_totais or eleicoes_consultar_secao.

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 how to use it (lookup by name or number) and adds a useful conditional note that municipality detail appears only 'quando a busca acha um só'. However, it never names an alternative tool or an explicit when-not-to-use condition, so routing between it and siblings such as eleicoes_totais is left to 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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context by warning that section-level and time-level data can be incomplete and by reporting a last-sync freshness indicator, which is exactly the caveat an agent needs before acting on such data.

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

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

Two sentences, front-loaded with the core question ("Quanto do acervo existe") followed by the concrete counts and the freshness field. The second sentence is purely the usage caveat and 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?

Simple read-only tool with no output schema; the description still conveys what is reported (BU coverage, log coverage per UF, denominator, last sync) and the caveat about official totals. It could go further in describing the response shape or what happens when ano/turno are omitted, but it is sufficient to call 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 0% and the description never mentions 'ano' or 'turno', so nothing compensates for the bare schema. Both parameters are optional (required: 0) and the description gives no hint about defaults or about how 'turno' narrowing affects the coverage figures reported.

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 resource and metric: fraction of the TSE section universe that has a boletim de urna and a log de urna per UF, plus the last synchronization timestamp. It implicitly separates itself from the official-totals sibling by noting those totals do not depend on this coverage, but 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?

"Use antes de tirar conclusão de dado por seção ou por horário" gives an explicit precondition for use, and the closing clause tells the agent one case where this tool is unnecessary (official disclosure totals). No named alternative tool is offered, so it stops short of a full routing instruction.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the content is 'curto e neutro' (a static explanatory reference), but says nothing about the shape of the response or whether the coverage section is conditional on data availability.

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 front-loaded sentence with a dense but scannable topic list; every item is substantive rather than filler. The closing clause about coverage is the only piece that arguably does not earn its place given the dedicated sibling.

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?

No output schema exists, so the description must carry the burden of explaining what is returned and what the optional 'ano' does; it does neither. For a read-only reference tool the gaps are moderate rather than fatal, but the unexplained parameter and the unaddressed overlap with eleicoes_cobertura leave real ambiguity.

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

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

Schema description coverage is 0% for the single optional parameter 'ano', and the description never mentions it. An agent cannot tell whether 'ano' filters the glossary, scopes the coverage section, or is ignored — the description fails to compensate for the schema gap.

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 the topics it explains (boletim de urna, log de urna, código de carga, fuso, biometria, SHA-256), which conveys that it is a reference/glossary resource. However, it never states the action plainly (e.g. 'returns definitions for') and its closing claim that it 'mostra também a cobertura do acervo' blurs the line with the sibling eleicoes_cobertura without acknowledging the 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 statement of when to call this versus eleicoes_cobertura, eleicoes_verificar_hash, or eleicoes_totais, all of which touch the same vocabulary/coverage area. No prerequisites or exclusions are given; the agent must infer usage from the topic list alone.

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, so the description is free to add real behavioral content: it computes per-field subtractions and cross-checks that the variations sum to the electorate variation, and it explicitly refuses interpretation. That tells the agent what the output will contain and that no narrative analysis is produced.

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 dense sentence that front-loads the operation and then the scope options and the arithmetic guarantee. Every clause carries information; only the paragraph-length density keeps it short of a 5.

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

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

For a 6-parameter tool with no output schema and zero schema descriptions, the definition conveys the concept and output shape but not the parameter contract or how required/optional fields interact. It is enough to understand the tool, not quite enough to call it correctly on the first try.

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 0% across 6 parameters, and the description only alludes to geography levels without mapping them to parameter names, formats, or value types. It never mentions 'ano', 'zona', or 'cargo' (the only enum), and it advertises Brazil-level totals even though 'uf' is required — leaving real ambiguity about how to scope a national comparison.

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 operation (compare 1st and 2nd round side by side) plus the aggregation levels it supports (Brazil, UF, municipality, section) and the derived fields (2nd − 1st per field). This clearly separates it from listing tools like eleicoes_totais, 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?

Usage is implied by the enumerated scopes ('do Brasil, de uma UF ou de um município ... ou de uma seção') and by the closing 'Sem interpretação', which signals a raw-numbers tool. There is no explicit when-to-use/when-not or pointer to eleicoes_totais or eleicoes_consultar_secao as alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds useful non-obvious behavior: it returns raw fields rather than a verdict, and does not perform OCR on photos. It says nothing about what happens when both lookup paths are supplied, or about the batch `itens` path.

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 short sentences, front-loaded with purpose, then lookup methods, then the key caveat. No filler and nothing repeated from 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?

For an 8-parameter, zero-coverage, no-output-schema tool with a nested `itens` array, the description is too thin. An agent cannot tell from it that `itens` batches multiple sections, what `ano`/`turno` mean, or what the returned field-by-field structure looks like.

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 0% across 8 parameters, so the description must compensate and largely does not. It covers uf, municipio, zona, secao and codigo_carga only by naming the lookup route; `ano`, `turno` (1/2 enum) and especially the nested `itens` array are never explained, leaving the batch capability invisible.

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: returns the official ballot (boletim de urna) for a section, field by field, for comparison against a printed copy. The comparison framing distinguishes it from generic lookup siblings like eleicoes_consultar_secao, though it never names an alternative 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?

Gives two concrete lookup routes (código de carga on the paper, or UF + município + zona + seção), which tells the agent how to invoke it. It also supplies an explicit exclusion — 'Não lê foto' — clarifying the caller must perform the comparison. No sibling alternative is named, keeping it 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, non-destructive and closed-world, so safety is covered. The description adds genuine value beyond that by disclosing the exact return payload, including timings in both local and Brasília time, aggregated biometrics, the internal ballot-box type, and the SHA-256 plus official TSE file link.

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?

It is a single dense sentence, front-loaded with the resource identity before the field inventory, so the agent sees the core purpose immediately. The long enumeration of returned fields is informative rather than redundant, though it reads somewhat as a laundry list.

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, the description compensates well by detailing the return contents. However, for a 7-parameter tool with zero schema coverage, the complete omission of how to supply the section identifiers (and the ano-versus-2026 ambiguity) leaves a real gap 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 description coverage is 0% across 7 parameters, so the description must carry the meaning and it does not: uf, ano, zona, secao, turno, municipio and the nested secoes array are never explained. Worse, the description frames the tool as 'eleições 2026' while an 'ano' parameter exists, and it never clarifies that 'secoes' enables a batch mode distinct from the single uf/zona/secao path.

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 resource, the official Boletim de Urna (BU) for a single electoral section, and enumerates the contained data (votes per candidate, blanks, nulls, turnout, timings, biometrics, hash, TSE link). An agent can tell this is a per-section BU retrieval rather than an aggregate or hash-check tool, though it never explicitly distinguishes itself from siblings like eleicoes_conferir_bu_impresso or eleicoes_verificar_hash.

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 versus the many related siblings (eleicoes_totais, eleicoes_filtrar_secoes, eleicoes_conferir_bu_impresso). The phrase 'de uma seção eleitoral' hints at single-section scope, but the schema's batch 'secoes' array is never acknowledged, so the agent gets no routing or mode-selection help.

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, yet the description adds substantive behavior the agent could not otherwise know: a SQLite plan pre-flight that estimates rows read and rejects over 5M without executing, a 5 s timeout, a 1,000-row cap with default 100, and what is returned (executed SQL, elapsed time, rows read). This is exactly the kind of context that matters for a query-execution 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?

A single dense paragraph that front-loads the core operation and then adds the cost/timeout/row-limit constraints in order of operational importance. Every clause carries information, though the final clause about return fields is slightly compressed.

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?

No output schema exists, and the description does cover the return payload (SQL executed, time, rows read) as well as failure conditions. The gaps are the unexplained 'ano' parameter and the absence of any note on how errors or rejections are surfaced, which keeps it short of fully complete.

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

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

Schema coverage is 0%, so the description must compensate, and it partly does: the row cap and its default of 100 clearly map to 'limite', and the accepted SQL form is specified for 'sql'. However, the 'ano' parameter is never mentioned in the description or the schema, leaving one of three parameters fully undefined.

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: 'Executa UM SELECT (ou WITH … SELECT) somente leitura nas tabelas públicas da eleição', including the scope limit (single read-only statement, public election tables). It also points to the sibling eleicoes_esquema as a prerequisite, which lets an agent distinguish this from the schema-introspection tool without opening either 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 a clear precondition ('veja eleicoes_esquema antes') and explains the refusal path above 5 million estimated rows with suggestions to narrow the query. It stops short of naming eleicoes_estimar_sql as the cheap way to preview cost, so the alternative-routing guidance is implied rather than 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds substantive context beyond that: the payload contains column semantics, worked example queries, and sha256 provenance of source files, which tells an agent why calling it first pays off.

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 compact sentence that front-loads the resource and ends with the routing instruction. Dense and waste-free, though the parenthetical table list is heavy relative to the rest.

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, the description does the work of describing the return payload (table/column meanings, example queries, source hashes). Only the unexplained 'ano' parameter leaves an unresolved question for an otherwise simple, annotation-covered read tool.

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

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

The single optional parameter 'ano' has 0% schema description coverage and is never mentioned in the description. An agent cannot tell whether it filters the returned schema metadata, selects a specific election year's dataset, or is ignored — this is the definition's clearest gap.

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 resource (public tables and columns of the MCP's SQL database) and enumerates the tables by name (secoes, municipios, totais_municipio, candidatos, votos_por_minuto, fontes), plus what else is returned: column meanings, 5 example queries, and TSE source file hashes. This is clearly distinguishable from the query-execution 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 'Chame antes de eleicoes_consulta_sql', giving a clear prerequisite ordering against the main alternative. No mention of when NOT to use it (e.g., for coverage questions or printed-ballot checks), so it stops short of 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 readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: it reports the plan, per-table row estimates, and the concrete 5-million-row rejection threshold. It doesn't detail output shape, but the safety and limit profile is well covered.

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 front-loaded sentence that leads with the relationship to the sibling, then enumerates the three outputs. 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 read-only validation tool with no output schema, the description explains what is returned (validation result, plan, row estimates, rejection verdict) and the governing limit. The only gap is the unexplained 'ano' parameter.

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 0% for both parameters. The description implicitly maps to 'sql' ('valida o SELECT'), but the 'ano' parameter is never mentioned, so half the inputs remain undocumented in both schema 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?

States a specific action (dry-run/estimate of a SQL query) and explicitly frames itself as the non-executing variant of eleicoes_consulta_sql. An agent can immediately distinguish it from the executing 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?

The phrase 'Só o pré-voo da eleicoes_consulta_sql, sem executar' names the alternative and the condition that selects it (validation without execution). It stops short of an explicit 'use this before running any query' imperative, but the routing is clear.

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

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

Adds real behavior beyond the annotations: a link that expires in 24 h, a sha256 checksum, and a hard cap of 200k rows per export — useful for planning and for verifying the file. It does not say what happens when the cap is exceeded (error vs. truncation) or whether the export is synchronous, which matters for a large CSV job.

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 tight sentence establishes scope and geography, a second enumerates return values and the row cap, a third names the use case. Nothing redundant, and the scoping constraint leads.

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?

Return values, expiry and volume limit are covered without needing an output schema, but a 5-parameter export tool with zero parameter documentation leaves the agent to infer filtros/ano/turno semantics from another tool. The cap behavior and export timing are also unaddressed.

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 0% and only 'uf' and 'municipio' get any treatment (the latter usefully flagged as optional). The 'filtros' array, 'ano' and 'turno' are undocumented in both schema and description; 'mesmo recorte de filtrar_secoes' is a pointer, not an explanation of what the filter objects accept.

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+resource (export as complete CSV) and anchors scope by reference to the sibling eleicoes_filtrar_secoes ('mesmo recorte'), with the geographic unit (UF, optionally município) called out. An agent can tell instantly that this is the bulk-export counterpart of the interactive filter tool.

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

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

The reference to filtrar_secoes implicitly routes interactive queries there and bulk exports here, and 'Para abrir no Excel ou no Python' names the intended consuming context. It stops short of explicitly stating when not to use it or what to do with the returned link beyond opening it.

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 it as a safe, idempotent read. The description adds real context beyond that: it always returns total_encontrado, pagination defaults to 50 with max 500, and each 2nd-round section carries the BU sha256. It doesn't cover error or rate-limit behavior, but the additions are substantive.

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 dense paragraph that front-loads the core purpose, then examples, then output/pagination behavior. Every clause adds information relevant to a 10-param tool; no obvious 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 10-param tool with 0% schema coverage and no output schema, the description covers aggregation semantics, output totals, and pagination well. But key controlling params like ano, turno, and cursor remain unexplained, leaving real gaps an agent must guess at.

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 0%, so the description carries the burden. It does an excellent job on the hardest nested params (filtros {campo,op,valor}, agrupar_por values, metricas syntax like soma:<campo>), but leaves ano, turno, cursor, and ordenar undocumented, so it only partially compensates.

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: filters and aggregates sections (president) server-side without SQL. The scope and output (total_encontrado) are clear. It doesn't explicitly differentiate itself from the sibling eleicoes_consultar_secao, so it stops 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?

'Sem uf nem municipio só agrega' gives a behavioral rule, and the filter examples show intended usage patterns. However, there is no explicit when-to-use versus alternatives like eleicoes_consultar_secao or eleicoes_totais, leaving the routing choice implied.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description's added value is real: it discloses the two output modes (per file version vs. per hour with votes gained in that hour), the row contents, and the earliest-time boundary of the dataset. It stops short of explaining that max_pontos implies downsampling or how large a timeline can be, which keeps it off a 5.

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

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

Two dense sentences with the core subject front-loaded and no filler. The parenthetical mode switch is efficient, though the list of returned fields plus the SHA-256 detail runs long against the missing parameter explanation.

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 7-parameter, optional-only, read-only query with no output schema, the description conveys the domain semantics well but leaves half the parameters and the downsampling implied by max_pontos unexplained. An agent could call it plausibly but would have to guess at date-range syntax and sampling behaviour.

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 0% schema coverage across 7 parameters, the description carries the full burden and only partly delivers: 'no Brasil ou numa UF' maps to uf, '(ou uma linha por hora)' maps to agrupar=versao|hora, and 'a partir de que horário' hints at de. It says nothing about ate, ano, cargo, or the sampling behaviour of max_pontos, so a third of the schema remains opaque.

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 names a specific artefact (the TSE result-file disclosure timeline for the 2nd round, national or per UF) and enumerates what each row carries (% sections counted, votes per candidate, version number, SHA-256). That is far more informative than a restated title. However, it never names or distinguishes itself from siblings such as eleicoes_votos_por_horario, whose purpose overlaps with the 'one line per hour' mode described here.

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

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

There is no explicit when-to-use, when-not, or named alternative, even though the hour-grouped mode clearly overlaps eleicoes_votos_por_horario and eleicoes_totais. The only indirect hint is that the tool reports from which time the dataset has data, which is a coverage note rather than usage guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: results come from the 'última versão coletada do arquivo de resultado do TSE', disclosing that freshness is bounded by collection time — a real trait for an election-results tool. It stops short of explaining partial-count semantics (e.g. when 'seções totalizadas' is less than the total).

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, front-loaded with the metric list and ending with scope and provenance. Dense but nothing is wasted; the parenthetical enumeration earns its place by doubling as a return-value preview.

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, the metric list usefully substitutes for a return-value description, and the provenance clause covers freshness. But with 7 fully optional, 0%-documented parameters, the description leaves major ambiguities: what happens when nothing is supplied (country-wide default?), what turno selects, what codigo identifies, and which offices are supported. That is short of complete for a tool of this parameter surface.

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 0%, so the description must compensate, and it partially does: 'numa UF', 'num município' and the 'Brasil/UF/município' scope map onto uf, municipio and nivel. But ano, turno and codigo are entirely unaddressed, and critically the cargo restriction (only presidente/governador) is invisible — an agent could reasonably try 'senador' or 'prefeito' and fail.

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 the resource precisely (official per-candidate election totals) and enumerates the returned metrics (votes, % of valid votes, blank/null, turnout, abstentions, totalized sections), plus the geographic scope (Brazil / UF / municipality) and source (latest collected TSE results file). It does not, however, explicitly distinguish itself from siblings like eleicoes_consultar_secao or eleicoes_comparar_turnos, leaving the agent to infer the boundary.

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 the aggregation scope but gives no when-to-use or when-not guidance, and never names an alternative tool. With siblings such as eleicoes_consultar_secao (section-level) and eleicoes_comparar_turnos (turn comparison) present, an explicit routing sentence was needed.

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 real value beyond that by naming the data source (official TSE acervo) and the two possible return shapes (the matching file, or the registered hash). It does not disclose what happens on a mismatch, what a match result looks like, or the semantics of the batch 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 well-formed sentence that front-loads the primary operation and then the inverse case, with no filler. The inline filename examples earn their space by disambiguating the 'arquivo' input.

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 zero schema descriptions on 4 parameters, the description should explain both the batch 'itens' path and the 'ano' scoping, plus mismatch behavior. It describes only the single-hash/single-file case, so an agent could easily miss that the tool accepts arrays and year filters — a material gap for a tool whose only structured documentation is bare property names.

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 0% across 4 parameters, so the description carries the full burden — and it only covers two of them. The filename format examples (o03221pr7691000660045-bu.dat, br-c0001-e006258-u.json) are genuinely useful added semantics for 'arquivo', but 'ano' and 'itens' are never mentioned, leaving the agent unaware that batch verification and year scoping exist at all.

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 operation (check whether a SHA-256 matches a hash registered for an official TSE file in the acervo, and identify which file) and covers the inverse lookup (filename → registered SHA-256). No sibling tool (eleicoes_totais, eleicoes_conferir_bu_impresso, etc.) performs hash verification, so the tool is unambiguously distinguishable. The concrete filename examples make the resource being operated on 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 two clauses effectively describe two usage modes (verify a given hash, or look up a hash by filename), so intended usage is inferable. However there is no guidance on when to prefer this over the related document-checking siblings, no prerequisites, and no exclusions or mention of which mode applies when both inputs are supplied.

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 and non-destructive, so the description correctly focuses on substance: the counts are limited to sections whose logs exist in the archive, so totals are partial, and the response enumerates source logs with SHA-256 for verification. That coverage caveat is exactly the kind of non-obvious behavior an agent needs; the only gap is not stating whether turno=1 is actually supported.

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, front-loaded with what is counted and at what grain, followed by the coverage caveat and output note. Dense with information and free of filler, though the 'turno' claim at the front is the one wasteful/incorrect clause.

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 7-parameter, zero-coverage, output-schema-less tool, the description omits the date-range semantics (de/ate), the year parameter, and the permitted interval values, and it never describes the shape of the returned data beyond 'lists source logs with SHA-256'. The partial-coverage warning is a strong addition, but the parameter documentation gap is too large to call this 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 0% across 7 parameters, so the description carries the full burden and largely fails: 'de', 'ate', 'ano' and 'intervalo_minutos' (which has a constrained set of 1/5/10/15/30/60) are never explained, and the allowed values are not even hinted at. It does explain the 'BR' sentinel for uf and the município option, but the '2º turno' phrasing actively misdirects on the turno enum.

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: votes counted per time band (Brasília time) in the 2nd round, derived from ballot-box logs, aggregated by UF or município. The scope is unambiguous, but nothing in the text distinguishes it from adjacent siblings such as eleicoes_totais or eleicoes_timeline_divulgacao, which an agent could plausibly pick instead.

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 only routing guidance is the special value 'uf="BR"' to get all UFs side by side, which is useful but is a parameter trick rather than a when-to-use statement. There is no mention of when this tool is preferable to eleicoes_totais or eleicoes_timeline_divulgacao, and the text asserts '2º turno' even though the schema accepts turno=1, leaving the agent unsure which call is valid.

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

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

Beyond the annotations, the description discloses important behaviors: invoke runs an MCP even when it is not installed, does a one-off run without adding the MCP to the toolkit, returns a connect link when credentials are needed, returns a checkout/top-up link when payment is needed, and requires workspace owner/admin for write operations. The description enriches the annotations and does not contradict them.

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

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

The description is front-loaded with identity and the core flow, and nearly every sentence carries useful guidance. However, it is one dense, wall-of-text paragraph with mixed language ("pontualmente") and heavy inline emphasis, which makes the many action alternatives hard to scan and parse.

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

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

For a complex 23-parameter, 14-action facade with no output schema, the description is remarkably complete: it covers the core flow, one-off invoke semantics, auth/credential/payment behavior, permission requirements, installed flags, the prompt library, and most action outcomes. The main gaps are the resume action and return-shape details for a few actions, but the overall guidance is sufficient for correct invocation in most cases.

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 0% schema description coverage, the description does a lot of compensating work: it maps action values such as search, describe, invoke, install, list_tools, publish_prompt, and explains tool_id, arguments, and prompt-related intent. However, several parameters and enum actions remain unexplained, including resume, limit, immediate, tier_slug, cancel_reason, report_context, conversation, request_name, and request_details, leaving agents under-specified for those paths.

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 the official mcp.ai marketplace: the in-platform catalog of MCPs/tools and the way to run them. It states the core discovery→describe→invoke flow, distinguishes the prompt-library subdomain from the MCP flow, and makes it clear this is a marketplace orchestrator rather than one of the sibling calculator/authenticate tools.

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

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

The description gives explicit when-to-use guidance: use install only to make an MCP permanent, prefer invoke for one-off use, use list_tools to see what is callable now, use subscribe/cancel for billing, and use request_mcp when nothing fits. It also explains what to do when invoke returns a connect link or checkout link, including retry behavior.

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

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

Annotations already carry the safety profile with idempotentHint=true and destructiveHint=false. The description adds that conversation data is needed for reproduction, which is useful context. However, it does not disclose what happens after submission, such as whether a ticket is created or whether the report is asynchronous, though the annotations 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 consists of two tight sentences: the first states the purpose, the second gives the key usage instruction. There is no filler, repetition, or irrelevant 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 three-parameter reporting tool with annotations already covering idempotency and destructiveness, the description is mostly sufficient. The main gaps are the unexplained `context` parameter and the absence of any indication of what the response or outcome will be, though no output schema is expected.

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 0%, so the description must compensate for undocumented parameters. It only clarifies the `conversation` parameter via 'conversation array with recent messages,' leaving the required `message` and optional `context` undefined. The agent must guess at their intended content.

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 verb 'Report' and explicitly enumerates three targets: 'bug, missing feature, or send feedback'. This makes the tool's purpose unmistakable and easily distinguishable from the sibling calculo_* and authentication tools, which serve entirely different functions.

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 establishes a clear context: use when a user reports a problem or wants to provide feedback. It also adds practical guidance to 'Include the conversation array with recent messages for reproduction.' It does not name alternatives, but none of the sibling tools overlap with bug reporting, so exclusions are unnecessary.

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=true and idempotentHint=true, so the agent knows this is a safe, non-mutating call. The description adds little beyond that—it names the output as versions but doesn't specify the format (e.g., semver strings, JSON object) or whether the output is human-readable. Since the annotations carry the safety profile, a 3 is appropriate.

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 sentence of 9 words, front-loading the action ('Show') and the object ('version'). There is zero waste, and it fully conveys the tool's purpose within its scope. This is a model of conciseness.

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, read-only, idempotent tool with no output schema, the description is nearly complete. An agent can confidently invoke it without additional context. The only minor gap is that the return format is unspecified, but since there is no output schema, a brief note on the output structure (e.g., 'returns a plain-text summary') would elevate completeness. Still, the description is sufficient 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?

The tool has zero parameters, and the schema coverage is 100% (no properties). The description doesn't need to explain parameters. The baseline for zero-parameter tools is 4, and the description is consistent with that—it correctly implies that no input is required.

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

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

The description clearly states the tool's purpose: 'Show the current MCP platform and adapter versions.' This is a specific verb-resource pair that distinguishes it from sibling tools, which are all calculation or authentication tools. It could be slightly more explicit about what 'show' returns (e.g., a text summary vs. structured data), but the resource is 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 implies that this tool is for checking version information, which makes sense in contexts where an agent needs to confirm platform/adapter versions before proceeding. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention whether version information is needed for authentication or compatibility checks. Given the sibling tools are all calculations, the usage context is reasonably clear, but not explicitly delineated.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds value by detailing what kind of state is returned, including connection status and account bindings, which helps the agent understand the tool's informational scope.

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 tightly packed sentence with the main action front-loaded, followed by a colon-delimited list of return contents. Every phrase earns its place with no repetition or filler.

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

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

For a zero-parameter, read-only introspection tool, the description fully covers what the agent needs to know before calling: what information it will receive. No output schema exists, but the description essentially provides a light output contract by enumerating the returned components.

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 is empty with zero parameters, and schema description coverage is 100%, so the description has no parameter burden. Per calibration, zero-parameter tools receive a baseline of 4; the description's output-focused content is more than sufficient.

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 ('Returns') and resource ('current toolkit state'), then enumerates exactly what is included: installed MCPs, connection status, connected accounts, and catalog tool counts. This is specific enough to distinguish it from computational siblings like calculo_* and action tools like authenticate or connect.

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 that this is the tool to call when an agent needs an overview or snapshot of the toolkit's current state. It does not explicitly list exclusion criteria or name alternatives such as show_version, but the context is clear enough for routine selection.

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