Banco Central do Brasil (BCB) — SGS Time Series MCP Server

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

As anotações já declaram readOnlyHint, openWorldHint e idempotentHint, e a descrição expande isso com comportamento relevante: normalização de acentos/caixa, combinação com E, cache de 24h, renovação na primeira busca após expiração, e degradação para o catálogo curado com avisos caso o portal esteja fora. Nada contradiz as anotações.

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

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

A descrição é longa, mas bem organizada em blocos temáticos (comportamento, quando usar, retorno, cobertura, rede) e cada bloco adiciona informação útil. Não há frases vazias, embora alguns detalhes de formato de retorno poderiam ser deixados apenas ao output 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?

Mesmo com output schema presente, a descrição cobre cenários importantes: cobertura parcial do índice, comportamento de cache e rede, degradação em falha do portal, e o significado dos campos de saída. Um agente consegue decidir corretamente quando e como chamar a ferramenta sem ambiguidade.

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

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

O schema já cobre 100% dos parâmetros, e a descrição acrescenta valor ao explicar que o termo aceita código, que múltiplos termos são combinados com E, e que a busca ignora acentos e maiúsculas. O parâmetro `limite` está bem documentado no schema, então a descrição não precisa repeti-lo.

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

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

A descrição afirma com verbo e recurso específicos: 'Busca séries do BCB por palavra-chave (ou pelo código)' em duas camadas distintas. Diferencia-se claramente dos irmãos ao nomear bcb_series_populares e bcb_serie_valores como alternativas para outros propósitos.

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?

Traz seções explícitas 'Quando usar' e 'Quando NÃO usar', indicando que serve para descobrir o código antes de consultar valores e que navegação por categoria ou obtenção de valores devem usar outros tools. Também alerta sobre a cobertura parcial do índice, o que orienta a decisão de uso.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds substantial context beyond that: quotes exist only on business days, non-USD parities come from Refinitiv and are not computed by the BCB, the disclaimer is passed through literally, and the response exposes consultation metadata. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with purpose, followed by usage guidance, return fields, defaults, and source caveats. The return-field enumeration is somewhat redundant with the output schema, but nearly every sentence carries useful decision-making or behavioral information.

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

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

Given the output schema exists, the description does not need to explain return values, yet it still gives a useful field overview. It covers source attribution, business-day limitations, non-USD parity handling, disclaimers, and sibling-tool routing, making the tool callable correctly in nearly any context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some rationale for defaults, like the 7-day window crossing weekends/holidays, but does not meaningfully extend the parameter semantics beyond what the schema already documents, such as date formats, limits, and default values.

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

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

The description states a specific verb and resource: 'Consulta a cotação PTAX de uma moeda contra o real' with date range support. It clearly distinguishes this tool from siblings by naming what it is not (long SGS series) and what it is (primary PTAX bulletin source with compra and venda in the same record).

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

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

The description explicitly gives 'Quando usar' and 'Quando NÃO usar' sections, naming bcb_serie_valores for long historical series and bcb_cambio_moedas for currency symbols. It also explains the default 7-day window as a way to cross weekends and holidays, giving concrete selection 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, and non-destructive behavior. The description adds meaningful context: it forwards the BCB disclaimer verbatim, names the data source (Olinda OData/PTAX), and warns that quotes only exist on business days with FX closing. No contradiction with annotations.

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

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

The description is organized with clear labels ('Quando usar', 'Quando NÃO usar', 'Retorna', 'Fonte') and every sentence contributes useful information. It is somewhat long, but the structure makes it scannable and there is 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 simple tool with one optional parameter, an output schema, and safety annotations, the description provides all needed context: purpose, usage decision, return fields, source, disclaimer handling, and availability caveat. Nothing material is missing.

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

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

The single parameter 'termo' has 100% schema coverage and is already described with examples ('EUR', 'libra') and optionality. The description only repeats that it accepts a filter term, adding no meaningful semantics beyond the schema, so the baseline score of 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 states a specific action ('Lista') and resource ('moedas com cotação publicada pelo Banco Central'), and specifies the returned fields (símbolo, nome, tipo). It also distinguishes itself from bcb_cambio_cotacao by explicitly saying it is not for cotação values.

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 'Quando usar' guidance: to discover the correct symbol before calling bcb_cambio_cotacao, and explicit 'Quando NÃO usar' guidance: for exchange rates themselves. This clearly routes the agent to the correct sibling tool.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description is fully consistent with these. Beyond the annotations, it discloses substantial behavior: how each series type is computed (level via endpoints, period-variation via chained accumulation with `metodo` in each item), resilience behavior (empty series and 12-month moving IPCA isolated in `erros` without invalidating the comparison), auto-slicing of long daily windows at the BCB's 10-year API limit, retry policy (up to 3 attempts, exponential backoff), the best-effort no-auth nature of the SGS API, and error semantics (isError with Portuguese message, 404 meaning). This is rich, decision-relevant behavioral context that no structured field conveys.

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

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

The description is long but every sentence earns its place given the tool's complexity (5 parameters, mixed series semantics, aggregation conventions, multiple edge cases). It is well-structured and front-loaded: the core purpose and main output shape lead, followed by when-to-use, return structure, resilience, periodicity handling, API behavior, and output format. A small amount of trimming would be possible (e.g., the retry mechanics could be condensed), but it is organized logically and dense with signal rather than padded.

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

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

For a tool with this complexity — comparison logic, two series-semantic families, aggregation enum, periodicity harmonization, API constraints, and error handling — the description is remarkably complete. It covers the full invoke decision surface: required date range, the 2-5 code constraint, the ranking return shape, edge cases (data gaps, moving-average series, mismatched periodicities, long windows), transport behavior (no auth, retries, 404 semantics), and output conventions (JSON in text and structuredContent, dd/MM/yyyy dates). With an output schema present, it need not enumerate return values further; 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, but the description adds genuinely non-obvious semantics beyond the schema. For `agregacao`, it explains the mapping: `ultimo` suits level/price/tax/index series, `soma` suits flows, and `acumulada` is for series that are ALREADY percentage variation — with the critical warning that 'somar 12 variações mensais NÃO dá a inflação do ano' (geometric composition required). For `frequencia`, it clarifies that it only aggregates to larger periods and that finer requests are refused. The description also reinforces that dataInicial/dataFinal are mandatory, matching the schema's required array.

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

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

The description opens with a specific verb and resource: 'Compara de 2 a 5 séries temporais no MESMO período', then states the exact computation (variação percentual) and output shape (ranking ordenado). It explicitly differentiates from a sibling: 'para uma única série use bcb_variacao', and gives a concrete example scenario ('qual índice de preço subiu mais em 2024 é esta tool'). An agent can select this tool and distinguish it from bcb_variacao 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?

The description provides explicit selection criteria with both positive and negative framing: 'Quando usar: para comparar/correlacionar a evolução de vários indicadores lado a lado' and 'Quando NÃO usar: para uma única série use bcb_variacao'. It also gives conditional guidance for the `frequencia` parameter ('Útil para comparar séries de periodicidades diferentes') and warns against requesting a finer frequency than the series. This is model usage-guideline content.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with them. Beyond the annotations, it discloses the external API contract (SGS, no auth or API key, no disclosed rate limit, best-effort), the retry policy (up to 3 attempts with exponential backoff), error semantics (isError: true, Portuguese messages, HTTP 404 meaning), the null-with-motivo convention vs 0, and the refusal of mixed periodicities. This is exactly the behavioral context annotations cannot express.

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

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

The description is long (~350 words) but front-loaded: purpose first, usage guidance second, parameter decision rules third, and behavioral/error details last. The length is justified by 7 parameters, 4 enums, and an output schema, and nearly every sentence carries information. Minor deduction because the metodo/base explanations partially duplicate what the input schema already states.

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?

Even though an output schema exists, the description adds the semantic meaning of the return contract: the `pares` structure with `interpretacao` in prose, `alinhamento` types (datas cruzadas, completas e parciais), null with `motivo` never 0, and the dd/MM/yyyy date and decimal-point number formats. It also covers external dependencies, failure modes, retries, the frequency-harmonization workflow, and the causation caveat — nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, establishing a baseline of 3. The description adds value beyond that by explaining the reasoning: why mixing daily with monthly series is refused (~7 coincident dates per year), why `variacao` base is preferred for trending series, and why `spearman` suits plateaued series like Selic between Copom meetings. It does not add syntax-level detail absent from the schema, so a 4 rather than a 5 is warranted.

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 opening sentence states a specific verb and resource ('Calcula a correlação estatística entre 2 a 5 séries temporais do BCB') with a hard constraint (MESMO período, dataInicial e dataFinal obrigatórias). It explicitly names the siblings it is not — bcb_comparar for side-by-side comparison and bcb_variacao for a single series — so an agent can distinguish the 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?

The description has explicit 'Quando usar' and 'Quando NÃO usar' sections with concrete examples (dólar e Selic, IPCA e IGP-M) and named alternatives. It also provides decision rules for parameter choice: prefer `variacao` base when series trend, prefer `spearman` for non-linear or plateaued series, and use `frequencia` to harmonize different periodicities. Nothing 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?

Discloses much more than annotations: public SGS API, no auth requirement, best-effort rate limits, automatic retries, error contract, index reconstruction limitation, and null instead of invented values for uncovered periods. No contradiction with readOnlyHint/idempotentHint/destructiveHint.

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 the core concept and well organized into use cases, return fields, source caveats, and error behavior. It is long and partly repeats schema/output-schema content, but each paragraph serves a real purpose.

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

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

Covers source, authentication, retries, failure semantics, coverage limitations, and how to choose the index/base, which is more than enough even with the rich output schema and annotations. Nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so the description is not responsible for documenting parameters; it mostly restates index choices and mesBase default that already appear in the schema. It adds useful conceptual framing but little parameter-specific meaning beyond structured fields.

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: 'Converte uma série NOMINAL do BCB em valores REAIS (moeda constante), descontando a inflação do período' and illustrates with a concrete salary example. Also distinguishes itself from bcb_serie_valores, so an agent can tell which tool to use.

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

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

Provides explicit 'Quando usar' and 'Quando NÃO usar' sections, including exclusions for percentual/índice/taxa series and a direct pointer to bcb_serie_valores for the raw nominal series. This is unambiguous 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?

As anotações já indicam readOnlyHint=true e idempotentHint=true, e a descrição adiciona contexto comportamental relevante: o Focus é vintage por construção, 'coletadoEm' é a data da coleta e 'referencia' é o alvo, microdados por instituição não são expostos, a contagem é feita do lado do cliente porque a fonte ignora $count, e consulta sem filtro não completa na origem. Não contradiz as anotações.

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

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

O texto é longo, mas denso e organizado por blocos funcionais: o que faz, quando usar, quando não usar, regras do contrato, formato de retorno, fonte e ressalvas técnicas. Repete pouca informação do schema e quase todas as frases carregam instrução útil; pequenas redundâncias e o volume alto impedem nota máxima.

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

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

Para uma ferramenta com 8 parâmetros, schema descritivo completo, output schema presente e anotações de segurança, a descrição ainda cobre lacunas importantes: formato de datas aceitas, comportamento sem datas, motivo da não exposição de microdados e limitação conhecida de $count. O agente tem contexto suficiente para invocar corretamente sem abrir schemas adicionais.

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

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

A cobertura do schema é 100%, então o baseline é 3; a descrição agrega valor além do schema ao explicar regras de contrato: 'referencia' é obrigatória em mensal/trimestral/anual e recusada nos rolantes, 'suavizada' só vale nos rolantes, 'top5' existe nos cinco horizontes, e a janela padrão sem datas é de 30 dias. Também alerta que pedir indicador no horizonte errado é a causa mais comum de resposta vazia.

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

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

A descrição abre com verbo específico ('Consulta'), recurso definido ('expectativas de mercado do boletim Focus') e delimita o escopo ('para UM indicador', com horizontes listados). Diferencia-se explicitamente de irmãos: bcb_focus_selic para Selic por reunião do Copom, bcb_serie_valores para valores realizados e bcb_focus_referencias para descobrir indicadores/referências.

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?

Há uma seção explícita 'Quando usar' com exemplos concretos (IPCA, IGP-M, PIB, câmbio) e 'Quando NÃO usar' com alternativas nomeadas. Também orienta chamar bcb_focus_referencias primeiro quando não souber o texto exato do indicador, com a justificativa de que o conjunto muda por horizonte.

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 (readOnly, idempotent, non-destructive, open-world), and the description adds substantial behavior beyond that: default all-six-scope behavior when `escopo` is omitted, partial-failure resilience via `falhas`, client-side counting because the source ignores `$count`, the mandatory-filter constraint at the origin, vintage data semantics of `coletadoEm` vs `referencia`, and exclusion of institution-level microdata. No contradiction with annotations.

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

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

Long but densely informative and well front-loaded: purpose, scope semantics, usage conditions, then behavioral details. Nearly every sentence earns its place given the tool's job of disambiguating two consumers; the return-structure recap is partially redundant with the output schema, so some trimming was possible — hence 4 rather than 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 discovery tool with 100% schema coverage, a safety-complete annotation set, and an output schema, the description covers everything an agent needs: scope semantics, default vs scoped invocation, edge-case failure behavior, source provenance, data-model interpretation, and a confidentiality constraint. Return values are already handled by the output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by disclosing the default behavior for an omitted `escopo` (queries all six and returns everything) and mapping each enum value to its consuming tool. However, `indicador` receives no added depth beyond the schema's 'see in which scopes it exists,' so it stops short of a 5.

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

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

The description opens with a specific verb and resource — 'Lista, POR ESCOPO, os indicadores e as referências que o Focus efetivamente publica' — and immediately states the downstream purpose: supplying exact text to bcb_focus_expectativas and bcb_focus_selic. By naming its consumers and explicitly distinguishing 'selic' from the five expectation horizons, it differentiates itself from siblings without needing their schemas.

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

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

Explicit when-to-use ('antes da primeira consulta ao Focus, ou quando uma consulta volta vazia') and when-not-to-use ('para os valores das expectativas em si') guidance, with consumer tools named. It even diagnoses the most common cause of empty queries (indicator not existing in that scope), so an agent knows precisely when to route to this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar is lower; the description still adds substantial behavior beyond that: vintage semantics (coletadoEm vs referencia), the source ignoring $count, the mandatory filter for query completion, and the disabled microdata by confidentiality risk. These are operational constraints and behavioral traits an agent could not infer from annotations or schema. No contradiction with annotations.

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

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

The description is long, but every sentence adds information: purpose, output fields, usage rules, exclusions, defaults, and source quirks are each covered in distinct blocks. It is front-loaded with the core purpose and returns, and the structure makes the density manageable. It is slightly verbose for a mature reader, but there is no fluff or tautology.

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

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

Given the tool has 5 optional parameters, an output schema, and a sibling set with overlapping domains, the description is remarkably complete. It covers selection criteria, exclusions, default behavior, output fields, and source limitations, including the reason for the mandatory filter and the vintage interpretation. An agent has enough context to select, invoke, and interpret results correctly without further research.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantic detail: it explains the reuniao format (R1/2026 = 1ª reunião), clarifies that date parameters refer to the coleta window with a 30-day default, and relates the `base` output to the top5 parameter (consenso vs top5). It also explains `referencia` as the meeting target, connecting the reuniao parameter to the output. This goes beyond the schema's raw descriptions, though the schema already covers the basic syntax.

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 resource (Focus expectations for the Selic rate) and the organizing axis (Copom meeting, format R1/2026). It explicitly differentiates itself from siblings: 'É separada de bcb_focus_expectativas porque o eixo temporal é a reunião do Copom, não o calendário' and points to bcb_serie_valores for realized Selic. The verb 'Consulta' plus the resource and distinguishing format leave no ambiguity.

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

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

The description provides explicit 'Quando usar' and 'Quando NÃO usar' sections, naming bcb_focus_expectativas as the alternative for annual calendar-year expectations and bcb_serie_valores for realized Selic. It also gives concrete example use cases like 'o que o mercado espera da Selic na próxima reunião'. This is the strongest possible usage guidance: when to use, when not to use, and which alternatives to select.

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

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

Even though annotations already declare readOnlyHint, idempotentHint, and openWorldHint, the description adds substantial behavioral context: independent fetching per indicator, automatic retries with exponential backoff up to 3 attempts, Portuguese error messages, HTTP 404 semantics, no authentication or rate-limit disclosure, and JSON/structuredContent output behavior. This goes far beyond what the annotations convey.

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

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

The description is dense but well-organized, front-loads the core purpose, and uses labeled sections such as 'Quando usar,' 'Quando NÃO usar,' 'Retorna,' 'Resiliente,' and 'Comportamento.' Every sentence adds operationally useful information without redundancy.

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

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

For a zero-parameter read-only tool with a rich output schema and annotations, the description fully covers use cases, exclusions, return shape, error handling, retry behavior, authentication requirements, and response format. An agent has everything needed to select and invoke this tool correctly.

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

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

There are zero parameters, and the schema already represents this with an empty object. The description reinforces 'Não recebe parâmetros,' and with no parameters there is little additional semantic value to add. Baseline 4 is appropriate for a zero-parameter tool.

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 ('retorna') and precisely enumerates the indicators returned in one call: Selic meta, IPCA mensal, IPCA acumulado 12 meses, dólar comercial de venda, and IBC-Br. It also distinguishes itself from siblings by naming bcb_serie_ultimos and bcb_serie_valores as the tools for historical or period-selected data.

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

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

The description explicitly states 'Quando usar: para um panorama econômico rápido' and 'Quando NÃO usar' for other series, historical data, or period selection, pointing to specific sibling tools. This is exemplary when-to-use versus when-not-to-use guidance.

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

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

Beyond annotations, the description discloses authentication-free access, best-effort rate behavior, automatic retries with exponential backoff, error response shape (isError), HTTP 404 meaning, date/number formatting, and the missing unit-of-measure limitation. It also explains inferred periodicity via periodicidadeInferida. No contradiction with annotations exists.

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

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

The description is organized into labeled sections (Quando usar, NÃO usar, Retorna, Limite, Comportamento), front-loads the purpose, and contains no filler. Although lengthy, the detail earns its place because it conveys concrete operational behavior rather than repetition.

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

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

For a single-parameter metadata tool with an output schema, the description is complete: it covers input semantics, return fields, API limits, error handling, authentication requirements, and data formatting. Nothing needed for correct invocation is left to inference.

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

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

The schema already provides 100% coverage by describing codigo as 'Código da série no SGS/BCB'. The description adds the context of a single series but does not need to compensate for schema gaps, so the baseline score is appropriate.

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

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

The description states a specific action ('Obtém a descrição de UMA série do BCB') and precisely scopes the resource as metadata, explicitly excluding historical series. This distinguishes it clearly from siblings like bcb_serie_valores and bcb_serie_ultimos without requiring schema inspection.

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

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

It includes explicit 'Quando usar' and 'Quando NÃO usar' guidance, naming bcb_serie_valores and bcb_serie_ultimos as the alternatives for value lookups. It also frames the tool as a confirmation step before consulting data, leaving no ambiguity about when to choose 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the catalog is local and makes no network call, provenance is explained through 'fonteNome' with 'portal' vs 'medido', and the return shape changes based on whether a filter is applied. This goes well beyond what annotations provide and contains no contradiction with 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 the main purpose and use guidance, and every sentence contributes substantive information. However, it is a single dense paragraph combining purpose, return shape, provenance, and exclusions; more visual structure would improve scanability without losing 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?

The description covers the catalog size, grouping behavior, filter behavior, return fields, local-network behavior, provenance semantics, and exclusions. The main gap is the inconsistent treatment of 'Expectativas': the schema lists it as a valid category, while the description says Focus expectations are not here. This ambiguity could confuse an agent choosing a filter value.

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

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

Schema description coverage is 100%, so the parameter is already documented well. The description adds little beyond what the schema says: it mentions the category filter and lists some categories, but that information essentially repeats the schema. The category list in the description also diverges from the schema by omitting 'Índices de Mercado' and 'Expectativas', so it does not reliably enhance parameter understanding.

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

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

The description opens with a specific verb and resource: it lists a curated internal catalog of 135 BCB economic series with codes, grouped by category, and accepts a category filter. It explicitly contrasts itself with bcb_buscar_serie and bcb_focus_expectativas, making sibling differentiation clear. The category list is slightly inconsistent with the input schema, but the core purpose 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 provides explicit 'Quando usar' and 'Quando NÃO usar' guidance, names the alternative for keyword search (bcb_buscar_serie), and warns that this tool does not fetch values. It also tells users that Focus expectations are not included and routes them to bcb_focus_expectativas. This is strong, actionable 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 the description adds substantial behavior beyond that: no authentication needed, best-effort API usage, automatic retries with backoff, error payload shape, HTTP 404 semantics, the N>20 workaround, and date/value formatting. There is no contradiction with the annotations.

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

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

Long but well-structured with labeled sections and a front-loaded purpose. Every sentence is substantive, though some parameter constraints and the N>20 detail repeat the input schema, and the output schema already covers return structure, so it is slightly less tight than ideal.

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 retrieval tool, it covers purpose, when to use and not use it, return shape, date format, error handling, retry/backoff behavior, authentication requirements, and the N>20 edge case. No critical operational detail an agent would need is missing.

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

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

The input schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaning by framing 'quantidade' in terms of 'mais recentes primeiro a partir do fim da série' and reinforcing the N>20 workaround and default of 10, which helps an agent choose the correct quantity.

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: 'Obtém as últimas N observações de UMA série temporal do BCB' and clarifies ordering ('mais recentes primeiro'). The 'Quando NÃO usar' section distinguishes it from bcb_serie_valores by scope, preventing confusion with 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?

Explicit 'Quando usar' section with a concrete example (últimos 12 meses do IPCA) and a 'Quando NÃO usar' section naming bcb_serie_valores for date ranges or full history. This gives the agent a clear routing rule with no need to infer.

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

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

As annotations já cobrem readOnly/idempotent/openWorld/destructive, e a descrição adiciona contexto comportamental rico além delas: limite de 10 anos da API do BCB para séries diárias com HTTP 406, fatiamento automático em janelas de 3 anos com campos 'chunking' e 'janelaAplicada', retry com backoff exponencial (3 tentativas), semântica de erros (isError, 404), ausência de autenticação e natureza best-effort. Não há contradição com as annotations — pelo contrário, reforça readOnlyHint e openWorldHint.

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

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

Descrição longa, porém estruturada em blocos rotulados (Quando usar, Quando NÃO usar, Retorna, Períodos longos, Harmonização, Comportamento) e com o propósito central na primeira frase. O tamanho é justificado pela complexidade real da ferramenta — limitações da API, chunking e retries precisam ser explicados — mas há pequena redundância com o outputSchema no trecho sobre formato do retorno.

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

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

Para um tool com comportamento intrincado, nada material falta: requisitos de autenticação (nenhum), limites de requisição (nenhum divulgado, best-effort), limitações da API e tratamento automático, política de retry, semântica de erros, formato de datas e estrutura do retorno (com outputSchema cobrindo os campos). O agente consegue invocar e interpretar o resultado corretamente em todos os cenários descritos.

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

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

A cobertura do schema é 100%, então a linha de base é 3, mas a descrição agrega significado real: explica o fatiamento das janelas de data (dataInicial/dataFinal), a convenção de `agregacao` com aviso prático ('somar 12 variações mensais NÃO dá a inflação do ano') e a restrição de `frequencia` (só agrega para períodos maiores, recusa mais fina). Isso vai além do que o schema descreve.

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

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

A descrição abre com verbo+recurso+escopo precisos: 'Consulta o histórico de valores de UMA série temporal do BCB pelo código SGS, opcionalmente limitado por um intervalo de datas'. Diferencia-se dos irmãos explicitamente, nomeando bcb_serie_ultimos, bcb_variacao, bcb_comparar e bcb_buscar_serie com seus papéis distintos. Um agente consegue selecionar esta ferramenta sem ambiguidade.

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?

Há seções explícitas 'Quando usar' e 'Quando NÃO usar' com alternativas nomeadas e condições concretas: pontos recentes → bcb_serie_ultimos; variação percentual → bcb_variacao; múltiplas séries → bcb_comparar; código desconhecido → bcb_buscar_serie/bcb_series_populares. O roteamento é completo e não deixa nada à inferência.

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

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

The description goes far beyond the annotations by detailing calculation methods (level vs. chained accumulation), the `analise.metodo` field, long-period chunking behavior with `chunking`/`janelaAplicada`, the retry policy (up to 3 attempts, exponential backoff), error semantics (isError with Portuguese message, 404 meaning), and the public API's no-auth/no-rate-limit characteristics. This complements readOnlyHint and idempotentHint without contradicting them.

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

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

The description is long but every sentence carries operational value: calculation rules, period precedence, response fields, chunking, error behavior, and formatting. It is front-loaded with the core purpose and then systematically covers edge cases, earning its length.

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 4-parameter tool with an output schema and rich annotations, the description covers all invocation-relevant aspects: period options, defaults, return structure, error handling, special-case refusals, and output formatting. Nothing an agent needs to correctly select and call this tool 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?

Input schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explicitly stating that `periodos` has precedence and ignores dates if provided, and by explaining why values above 20 trigger the date-window path ('o endpoint nativo do BCB tem esse teto'). This contextual value justifies a 4, though the schema already documents parameter basics.

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

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

The description opens with a specific verb and resource: 'Calcula a variação percentual de UMA série no período, mais estatísticas descritivas.' It explicitly distinguishes itself from bcb_comparar (multi-series comparison), bcb_serie_valores (raw values), and the special case of already-accumulated series, so an agent can clearly tell what this tool does.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Quando usar: para medir tendência/variação/acumulado de uma única série. Quando NÃO usar: para comparar várias séries use bcb_comparar; para os valores brutos use bcb_serie_valores.' It also flags that accumulated-mobile series like IPCA 12 months are refused with orientation, preventing misuse.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful behavioral context beyond these: it performs a live GET against the public source when needed and errors on unknown ids. This is valuable but partly redundant with the annotations.

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

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

The description is well-structured: it leads with the return shape, then clarifies the tool's role and boundary, and ends with behavioral notes. The parenthetical catalog enumeration is a bit long but helps define the datasource; overall there is little 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 single-parameter fetch tool with a rich output schema and annotations covering safety and idempotency, the description is complete. It explains where ids come from, what the document contains at a high level, the source behavior, and the error condition, leaving no critical 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?

The schema already covers the only parameter fully: `id` is described as an identifier returned by `search`. The description repeats this constraint and adds that unknown ids are invalid, but does not materially extend the meaning beyond what the schema provides. With 100% schema coverage, a 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 states a specific verb and resource: 'Returns the full document for an id obtained from `search`', with the exact response shape. It also distinguishes itself from siblings by identifying as the companion of `search` in the Deep Research contract and explicitly noting that `bcb_*` tools remain for data queries.

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

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

Usage guidance is explicit: this tool is for ids returned by `search`, and unknown ids produce an error. It also names the alternative category (`bcb_*` tools) for data queries, so an agent knows when not to use this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description only needs to add context. It adds useful behavioral details: query accent/case handling, relevance ordering, empty-list semantics, and in-memory caching of a public catalog. It avoids contradicting annotations.

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

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

The description is organized in short, labeled chunks (core behavior, contract context, exclusion, query guidance, safety). Every sentence contributes either to selection, invocation, or routing, and the most important information is front-loaded in the first sentence.

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 search tool, the description is complete: it defines the return type and count, explains the empty-list case, shows how to use results with `fetch`, and warns against using it for data queries. An agent has everything needed to call it correctly without further inference.

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

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

Schema coverage is 100%, so the schema already documents the `query` parameter. The description still adds one meaningful fact beyond the schema — that queries may be in Portuguese or English — while restating that natural language/keywords and accent/case insensitivity are acceptable. This is enough to move above the coverage baseline.

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

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

The description opens with a specific verb and resource: it searches the Banco Central do Brasil SGS catalog and returns up to 10 matching documents with a concrete shape. It also distinguishes itself from siblings by stating it is a catalog index, not a data query tool.

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

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

It explicitly says when to use this tool (Deep Research workflows via Responses API), names the downstream `fetch` step, and tells the agent to prefer `bcb_*` tools for actual data. This is clear routing guidance with exclusions, not just an implied context.

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