Server Quality Checklist

Tool Scores

• bcb_cambio_cotacaoA
  4.6/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the read-only profile is clear. The description adds substantial behavioral context: the default 7-day window, business-day-only quotes, Refinitiv coverage for non-USD parities, BCB disclaimer passthrough, and the origin of the data. This goes well beyond 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.

  Conciseness4/5

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

  The description is longer than minimal, but it is well structured with clear sections: purpose, when to use, when not to use, return fields, source, and caveats. It is front-loaded and organized enough to scan, although the return field list is partially redundant given the existing output schema.

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

  Completeness5/5

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

  For a 5-parameter read-only query tool with a rich output schema and strong annotations, this description is complete enough. It covers default behavior, business-day limitations, the meaning of the data, the external source of non-USD parities, and when a sibling tool should be used instead.

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

  Parameters3/5

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

  The input schema already has 100% parameter coverage with defaults, constraints, and format examples, so the baseline is 3. The description reinforces the default 7-day window and day-versus-range distinction, but most of that is already expressed in the schema; the description adds only modest contextual color for parameters.

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

  Purpose5/5

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

  The description opens with a precise action ('Consulta a cotação PTAX de uma moeda contra o real') and clearly states the supported scope: a specific day or a date range. It also differentiates from siblings explicitly by naming bcb_serie_valores for long SGS series and bcb_cambio_moedas for currency symbol lookup.

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

  Usage Guidelines5/5

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

  The description contains an explicit 'Quando usar' and 'Quando NÃO usar' section. It tells the agent exactly when to prefer this tool and when to use alternatives, including the specific SGS series codes for dollar—which is unusually clear guidance.

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

• bcb_focus_expectativasA
  4.6/5.0
  Behavior5/5

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

  Beyond the readOnlyHint, the description discloses important behaviors: the Focus is vintage by construction, the count is done server-side because the source ignores $count, the filter is mandatory because unfiltered queries never complete, and microdata are not exposed due to confidentiality. This gives the agent a full understanding of the tool's constraints.

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

  Conciseness4/5

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

  The description is lengthy but well-structured with clear sections (Quando usar, Quando NÃO usar, Regras do contrato, Retorna). It front-loads the core purpose and every paragraph adds useful context; minor redundancy with schema is acceptable given the tool's complexity.

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

  Completeness5/5

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

  The description covers all relevant aspects: return fields, default 30-day window, data source, vintage semantics, server-side count, mandatory filter, and confidentiality limits. With an output schema present, this is more than sufficient for an agent to use the tool correctly.

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

  Parameters3/5

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

  The schema already describes all parameters with 100% coverage, including the rules for referencia and suavizada. The description reinforces these rules but adds little new semantic detail beyond what the schema provides, though it does clarify the relationship between horizons and indicator availability.

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

  Purpose5/5

  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: 'Consulta as expectativas de mercado do boletim Focus para UM indicador' and lists the five horizons. It explicitly distinguishes itself from siblings by naming bcb_focus_selic for Selic expectations and bcb_serie_valores for realized values.

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

  Usage Guidelines5/5

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

  The description contains explicit 'Quando usar' and 'Quando NÃO usar' sections, naming alternative tools. It also advises to call bcb_focus_referencias first if uncertain about indicator text, which is crucial for avoiding empty responses.

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

• bcb_cambio_moedasA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations (readOnlyHint, idempotentHint), the description adds context: the response includes a literal disclaimer from BCB, quotes only exist on business days, and the data source is PTAX via Olinda OData. These are meaningful behavioral details not present in annotations.

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

  Conciseness5/5

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

  The description is well-structured with clear sections (what, when, when-not, returns, source, caveats). Every sentence contributes useful information, and the essential use case is front-loaded.

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

  Completeness5/5

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

  The description covers all necessary context: the tool's purpose, return fields, source, usage caveats, and relationship to sibling tools. It is complete for a simple, single-parameter, read-only tool.

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

  Parameters3/5

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

  The single parameter 'termo' is fully described in the schema (100% coverage), and the description only restates that it filters without adding new semantic meaning. The baseline of 3 applies as the schema carries the burden.

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

  Purpose5/5

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

  The description clearly states the tool lists currencies with quotes from the Central Bank, including symbol, name, and type, and accepts a filter term. It distinguishes itself from the sibling bcb_cambio_cotacao by explicitly positioning it as a precursor to that tool, eliminating ambiguity.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use ('para descobrir o símbolo correto antes de chamar bcb_cambio_cotacao') and when not to use ('para valores de cotação'), naming the alternative tool. This provides direct, actionable guidance.

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

• bcb_serie_metadadosA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses valuable behavioral details: the SGS API has no public metadata endpoint, the catalog is curated for 139 series, periodicity may be inferred and flagged as periodicidadeInferida, no authentication is needed, retries happen up to 3 times with exponential backoff, and errors return isError with Portuguese messages. It also explains HTTP 404 semantics. These details add real transparency beyond what annotations provide.

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

  Conciseness5/5

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

  The description is long but every sentence adds information: use-case, non-use-case, returned fields, source limitations, inference behavior, retry logic, error format, and output format. It is well structured with informative labels (Quando usar, Quando NÃO usar, Retorna, Limite, Comportamento), so even the length feels purposeful and easy to scan.

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

  Completeness5/5

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

  The description covers purpose, usage context, behavioral quirks, retry logic, error handling, output shape, and even caveats about the curated catalog and inferred periodicity. Given the simple schema (one required parameter), the annotations, and the existing output schema, the description is fully complete for tool selection and invocation.

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

  Parameters3/5

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

  The schema already has 100% coverage for the single parameter (codigo) with a clear description: 'Código da série no SGS/BCB.' The tool description references the code indirectly by saying 'UMA série' and how to use it to confirm the series, but it does not add material semantic detail beyond the schema. This aligns with the baseline of 3 for high schema coverage.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Obtém a descrição de UMA série do BCB' and immediately restricts the scope by saying 'sem trazer a série histórica.' It also lists exact returned fields (nome, periodicidade, categoria, fonte, último valor), and the 'Quando NÃO usar' line differentiates it from sibling tools like bcb_serie_valores and bcb_serie_ultimos.

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

  Usage Guidelines5/5

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

  The description provides explicit usage guidance: 'Quando usar: para confirmar o que uma série representa e com que frequência é publicada' and 'Quando NÃO usar: para os valores em si use bcb_serie_valores ou bcb_serie_ultimos.' This gives the agent clear when-to-use and when-not-to-use criteria with named alternatives.

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

• bcb_serie_valoresA
  4.7/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint: true, openWorldHint: true, idempotentHint: true, and destructiveHint: false, so the safety profile is well covered. The description adds substantial behavioral context: daily series capped at 10 years with automatic chunking, open-window refusal handling (HTTP 406), harmonic resampling behavior, public API without auth, automatic retry (3 attempts, exponential backoff), error handling (HTTP 404), and both text and structuredContent output. This adds context beyond annotations, though it doesn't describe the exact response schema (which the output schema covers). 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.

  Conciseness4/5

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

  The description is long but tightly organized with clear sections (Quando usar, Quando NÃO usar, Retorna, Períodos longos, Harmonização, Comportamento). Every section provides unique value; the list of alternatives is essential for tool selection. However, it is quite dense and could potentially be trimmed, though the complexity of the tool (chunking, harmonization, error handling) justifies most length. One point off for being slightly verbose in the chunking section.

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

  Completeness5/5

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

  For a tool with 5 parameters, 2 enums, an output schema, and rich annotations, the description covers all critical operational aspects: input validation (date formats, aggregation conventions), edge cases (open windows, long periods, HTTP 406), error handling (retry, 404), harmonization behavior, and output structure. The output schema handles return value specifics, so the description doesn't need to duplicate that. It is complete for the complexity level.

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

  Parameters5/5

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

  Even though the input schema has 100% description coverage, the description adds significant semantic value: it explains the chunking logic triggered by long date ranges (which is a behavioral consequence of dataInicial/dataFinal), defines the date format (dd/MM/yyyy and yyyy-MM-dd), and elaborates on the `agregacao` parameter by explaining the difference between `soma` and `acumulada` for inflation series — a critical nuance not in the schema. The description clarifies that `frequencia` only aggregates to larger periods and refuses finer frequencies, which complements the schema. It also explains the return structure (serie, totalRegistros, etc.) which helps parameter understanding.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Consulta o histórico de valores de UMA série temporal do BCB pelo código SGS' — clearly stating the action (query), the resource (historical values of a time series), and the key identifier (SGS code). It explicitly distinguishes from siblings by naming five alternative tools and their specific uses, which fully differentiates this tool from its siblings.

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

  Usage Guidelines5/5

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

  The description includes an explicit 'Quando usar' and 'Quando NÃO usar' section that names five specific alternative tools (bcb_serie_ultimos, bcb_variacao, bcb_comparar, bcb_buscar_serie, bcb_series_populares) and the exact scenarios where each is more appropriate, along with a prerequisite (finding the code first). This is explicit, actionable guidance with clear exclusions and alternatives.

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

• bcb_buscar_serieA
  4.8/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, establishing safety. The description goes far beyond these with rich behavioral disclosure: accent/case-insensitive matching, AND-combination semantics, 24h cache validity, network behavior (only first search after expiry touches network), degraded mode with fallback to curated catalog, and coverage caveat that the index is not the full SGS. No contradiction with annotations — the openWorldHint aligns perfectly with the 'not finding doesn't prove non-existence' warning.

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

  Conciseness4/5

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

  The description is long but from-loaded with the core purpose and two-layer behavior first. Every sentence carries new information: search semantics, usage guidance, return format, coverage limitation, network behavior, degradation. Given the tool's genuine complexity (dual-source search, caching, fallbacks), the length is justified. Slight structural improvement possible by separating return-schema details (already covered by output schema) from usage guidance, but overall efficient.

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

  Completeness5/5

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

  With an output schema present and rich annotations (readOnly, idempotent, openWorld), the description still adds significant value: coverage limitation explicitly stated, network/caching behavior with timing, degradation path and signal mechanism (`avisos`), and search semantics not derivable from schema. For a dual-layer search tool with external dependency on the BCB portal, this is comprehensive and leaves no critical behavioral gap for the agent.

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

  Parameters4/5

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

  Schema covers both parameters at 100% (termo: min 2 chars, code or term, AND-combination; limite: 1-100, default 20), so baseline is 3. The description adds value by explaining search semantics beyond schema: accent/case insensitivity ('inflacao' finds 'Inflação'), the two-layer interpretation of results, and that `termo` accepts a code. A small gap: the caching/degradation behavior is stated at the tool level but not tied explicitly to how it affects `termo` results — minor, so 4 is appropriate.

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

  Purpose5/5

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

  Description opens with a specific verb+resource: 'Busca séries do BCB por palavra-chave (ou pelo código)' with a clear two-layer model (curated local catalog vs. BCB open data portal index). It actively distinguishes itself from siblings by naming bcb_series_populares and bcb_serie_valores for alternative use cases. This fully clarifies both what the tool does and how it differs from peers.

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

  Usage Guidelines5/5

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

  Explicit guidance is provided: 'Quando usar: para descobrir o código de uma série antes de consultar valores' and 'Quando NÃO usar: para navegar tudo por categoria use bcb_series_populares; para valores use bcb_serie_valores.' This names specific sibling alternatives, giving the agent precise decision criteria for tool selection.

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

• bcb_serie_ultimosA
  4.8/5.0
  Behavior5/5

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

  Even with annotations declaring readOnlyHint/idempotentHint/destructiveHint false, the description adds substantial behavioral context: automatic retries with exponential backoff, the N > 20 native API limitation and workaround, HTTP 404 semantics, Portuguese error messages, JSON/structuredContent behavior, and output date/number formats. 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.

  Conciseness4/5

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

  The description is long but well organized into semantic sections: what returns, when to use, when not to use, limits, behavior, errors, and output format. It contains minor redundancy with the schema's parameter descriptions, but no wasted sentences overall, and the most important purpose is front-loaded first.

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

  Completeness5/5

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

  Given the tool's moderate complexity, the description covers all key operational aspects: output shape, no-auth backend API, retry behavior, error semantics, native AGI constraints, and output formatting. With both an output schema and a very complete description, an AI agent has sufficient context to invoke the tool correctal

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

  Parameters4/5

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

  The input schema already covers both parameters at 100%, including the 1-1000 range and default for quantidade. The description adds value by explaining that N > 20 triggers the system's date-window search behavior, which directly informs an agent how the quantidade parameter actually behaves in practice.

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

  Purpose5/5

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

  The description clearly states the tool's function: retrieving the last N observations of a single BCB time series, most recent first. It distinguishes itself from the sibling tool bcb_serie_valores by explicitly positioning this as the choice for recent data without date calculation.

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

  Usage Guidelines5/5

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

  The description includes an explicit 'Quando usar' section with a concrete IPCA example and an explicit 'Quando NÃO usar' section that names bcb_serie_valores as the alternative for date ranges or full history. This gives an agent clear decision criteria.

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

• bcb_focus_selicA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, lowering the bar. The description still adds significant behavioral context: the vintage nature of Focus, the meaning of coletadoEm versus referencia, the fact that $count is ignored (count computed locally), the mandatory filter due to source limitations, and the non-exposure of microdata for confidentiality. No contradictions with annotations.

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

  Conciseness5/5

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

  Although long, every sentence carries operational weight: purpose, return statistics, use exclusions, response fields, default window, source attribution, and the vintage data caveat. It is dense but efficient, with no filler or repetition of schema details.

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

  Completeness5/5

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

  For a tool with five optional parameters, complex temporal semantics, and multiple siblings, the description fully explains the Copom meeting axis, the data collection window, the return structure (including 'base', 'filtro', 'referencia'), and source limitations. An output schema exists, so return values are covered by structured data; no additional enumeration needed.

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

  Parameters4/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the default 30-day collection window, reinforcing the date format expectations, and clarifying that 'referencia' is the Copom meeting rather than the calendar year. This pushes it slightly above baseline.

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

  Purpose5/5

  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: 'Consulta as expectativas de mercado do Focus para a taxa Selic' and clarifies the organizing axis ('organizadas pela REUNIÃO do Copom'). It explicitly distinguishes this tool from siblings by naming bcb_focus_expectativas (annual calendar) and bcb_serie_valores (realized Selic), and states why it is separate.

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

  Usage Guidelines5/5

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

  It provides explicit 'Quando usar' ('o que o mercado espera da Selic na próxima reunião') and 'Quando NÃO usar' with named alternatives and even series codes for bcb_serie_valores (432, 1178, 4390). This is exemplary guidance, exceeding the minimum expected.

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

• bcb_indicadores_atuaisA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (read-only, idempotent), the description discloses valuable behavioral details: each indicator is fetched independently and partial failures do not crash the call, retries happen up to 3 times with exponential backoff, HTTP 404 is explained, and the response format is fully described. This greatly exceeds the annotation baseline.

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

  Conciseness5/5

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

  The description is dense but well-organized, front-loading the core purpose, then moving through when to use, return shape, resilience, API details, and error behavior. Every sentence adds actionable information without padding.

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

  Completeness5/5

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

  For a zero-parameter tool with an output schema, the description is exceptionally complete: it covers use cases, non-use cases, output timing, error semantics, retry behavior, external API dependency, and formatting. The agent has everything needed to select and invoke the tool correctly.

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

  Parameters4/5

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

  The tool accepts no parameters and the input schema already clarifies this completely. The description reinforces this by stating 'Não recebe parâmetros' and adds value by detailing the returned fields, which is enough for a parameterless tool.

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

  Purpose5/5

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

  The description clearly states this is a shortcut that returns the most recent values for key Brazilian economic indicators in a single call, naming each indicator. It also distinguishes itself from sibling tools by explicitly stating when not to use it and which alternatives to use instead.

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

  Usage Guidelines5/5

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

  The description provides explicit 'Quando usar' guidance for a quick economic overview and explicit 'Quando NÃO usar' guidance, directing users to bcb_serie_ultimos or bcb_serie_valores for other series, historical data, or custom periods.

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

• bcb_series_popularesA
  4.9/5.0
  Behavior5/5

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

  Besides the annotations, the description discloses meaningful details: it is a local catalog with no network call, the response shape changes by filtering, the number of series, and the provenance semantics of `fonteNome` ('portal' vs 'medido'). This goes well beyond the annotations and significantly helps the agent reason about data reliability.

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

  Conciseness5/5

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

  Each sentence adds substantive information: purpose, use cases, exclusions, return shape, local nature, and provenance. The item is longer than average, but the complexity of the catalog and its edge cases warrant it; there is no filler or redundancy.

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

  Completeness5/5

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

  For a one-optional-parameter catalog tool, the description covers use cases, output structure, data-source caveats, and important exclusions not discoverable from the schema. Combined with the existing output schema, this gives the agent a complete picture for correct invocation.

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

  Parameters4/5

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

  The single optional `categoria` parameter is already fully described in the schema, so the description doesn't add syntax-level info. However, it does add key semantics: filtering by categoria changes return from a grouped object to a flat array, and it warns that Focus expectations are excluded. That extra context justifies a score above baseline, even with 100% schema coverage.

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

  Purpose5/5

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

  The description opens with a strong verb and resource: 'Lista o catálogo interno curado de 139 séries econômicas do BCB com seus códigos', and further details the grouping by category and optional filter. It also explicitly distinguishes the tool from siblings like bcb_buscar_serie and bcb_focus_expectativas, making its purpose unmistakable.

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

  Usage Guidelines5/5

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

  It provides explicit 'Quando usar' and 'Quando NÃO usar' sections, naming bcb_buscar_serie for keyword searches and bcb_focus_expectativas for Focus expectations. This gives the agent concrete guidance on when to select or avoid this tool compared to its siblings.

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

• bcb_variacaoA
  4.9/5.0
  Behavior5/5

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

  Adds substantial detail beyond annotations: explains no authentication required, best-effort usage, retry logic (3 attempts with exponential backoff), error handling (isError, HTTP 404 semantics), and automatic chunking for long periods. This complements the readOnlyHint and provides practical behavioral context.

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

  Conciseness5/5

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

  The description is long but exceptionally well-structured: it opens with the core purpose, then details the two calculation methods, usage guidance, edge cases, error handling, and return schema in a logical flow. Every sentence contributes unique value, and the use of semicolons and bullet-like lists improves readability.

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

  Completeness5/5

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

  Given the tool's complexity (distinguishing level vs. variation series, handling moving averages, periodos limits, chunking, retries, and a rich output structure), the description covers all relevant aspects. Even though an output schema exists, the description succinctly lists all returned fields and their meaning, making the behavior fully predictable.

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

  Parameters4/5

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

  Schema already covers all parameters (100% coverage), so baseline is 3. The description adds meaning by explaining periodos precedence over dates, the interpretation of variation vs level series, and the behavior when dates are omitted. This is extra value over the schema's basic field descriptions.

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

  Purpose5/5

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

  The description clearly states the tool calculates percentage variation of a single series with descriptive statistics, and explicitly distinguishes between level series and series that are already variations. It also names sibling tools (bcb_comparar, bcb_serie_valores) as alternatives, making its purpose unambiguous.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use ('para medir tendência/variação/acumulado de uma única série') and when-not-to-use ('para comparar várias séries use bcb_comparar; para os valores brutos use bcb_serie_valores'). Also gives special handling for moving-average series and the periodos precedence, leaving no doubt about scope.

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

• bcb_compararA
  5/5.0
  Behavior5/5

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

  Beyond readOnly/idempotent annotations, the description discloses automatic retries (3 attempts with exponential backoff), persistent error handling (isError with Portuguese message), HTTP 404 handling, JSON response format (both text and structuredContent), and special behavior for series that are already percentage changes (acumulada aggregation).

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

  Conciseness5/5

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

  The description is long but every sentence serves a purpose, with clear separation of sections (comparison logic, usage, error handling, return fields). No redundancy or filler; structure mirrors the tool's behavior logically.

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

  Completeness5/5

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

  It explicitly lists all output fields (periodo, totalSeries, seriesComDados, seriesComErro, ranking) and ranking item properties (posicao, codigo, nome, metodo, etc.), includes data format (dd/MM/yyyy, decimal point), and explains edge cases like series without data in the period.

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

  Parameters5/5

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

  Schema descriptions are already detailed, but the description adds critical context: for 'acumulada' it warns that summing monthly variations does not yield annual inflation; for 'frequencia' it states only coarser periods are allowed; and it clarifies each agregacao option's applicability (price vs flow vs percentage). This exceeds schema coverage.

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

  Purpose5/5

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

  The description explicitly states it compares 2-5 time series over the same period, calculates percentage variation, and orders them in a ranking. It also contrasts with bcb_variacao for single-series use, making its purpose unmistakable.

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

  Usage Guidelines5/5

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

  It provides clear when-to-use ('compare/correlate multiple indicators side by side') and when-not-to-use ('for a single series use bcb_variacao'). It also explains when to use frequencia and agregacao parameters, including limitations on frequency resampling.

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

• bcb_correlacaoA
  5/5.0
  Behavior5/5

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

  No contradiction with annotations (readOnlyHint=true, idempotentHint=true, openWorldHint=true). The description adds substantial behavioral context beyond annotations: uses the public SGS API with no auth, no disclosed rate limits, best-effort; retries up to 3 times with exponential backoff on transient failures; returns isError: true with error messaging in Portuguese; HTTP 404 semantics; and critically explains that different periodicities are RECUSADAS rather than naively joined—before warning about the ~7 matched days/year data-snooping pitfall.

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

  Conciseness5/5

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

  The description is long but every clause earns its place—it packs statistical warnings, API contract details, and edge-case behaviors into a scan-friendly structure that uses bold, uppercase emphasis, and colons effectively (e.g., 'nunca 0', 'RECUSADAS, não avisadas'). No fluff; the causational disclaimer 'Correlação não estabelece causalidade' is a single purposeful sentence.

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

  Completeness5/5

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

  For a complex statistical tool, the description is fully complete: it covers the mathematical methods, the output contract (`periodo`, `metodo`, `base`, `series`, `alinhamento`, `pares` with `codigoA/B` and `coeficiente`), error semantics, retry behavior, date formats, and the important distinction between null-with-reason and 0. The outputSchema covers the return structure, so the description needn't duplicate it—yet it still explains what `descartados` and `derivacao` mean contextually.

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

  Parameters5/5

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

  Even though schema description coverage is 100%, the description adds meaningful semantics beyond what the schema provides. It explains WHY `spearman` is appropriate for plateau series (e.g., Selic), why `acumulada` uses geometric composition (because summing monthly IPCA variations is incorrect), and how `frequencia` harmonizes different periodicities. These are non-obvious statistical implications that the raw parameter docs alone cannot convey.

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

  Purpose5/5

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

  The description opens with a specific verb+resource+scope construction: 'Calcula a correlação estatística entre ional 2 a 5 séries temporais do BCB no MESMO período... par a par.' This immediately differentiates it from siblings by naming the statistical operation, the 2-5 series constraint, the pairwise behavior, and the mandatory same-period requirement. It also explicitly names alternatives (bcb_comparar, bcb_variacao).

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

  Usage Guidelines5/5

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

  Goes beyond vague guidance with a dedicated 'Quando usar' section (with concrete indicator examples like 'dólar e Selic, IPCA e IGP-M') and a 'Quando NÃO usar' section naming specific sibling tools. It even makes a methodological prescription—prefer `variacao` when series have trends because level-based correlation is spuriously high—which actively prevents misuse.

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

• bcb_deflacionarA
  5/5.0
  Behavior5/5

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

  Even with annotations describing readOnlyHint, openWorldHint, and idempotentHint as true, the description adds substantial value: it discloses the API endpoint (SGS), authentication-free usage, rate limits as 'best-effort', retry logic (3 attempts, exponential backoff), error semantics, and the reconstruction limitation with a quantified accuracy (0.0052 pp). This goes far beyond the annotations 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.

  Conciseness5/5

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

  Despite its length, the description is densely informative with no fluff. Each sentence adds essential context: the nominal-vs-real distinction, parameter explanations, error handling, and limitations are all covered without repetition. The structure flows logically from what → when → how → edge cases.

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

  Completeness5/5

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

  Given the complexity of the tool (deflating series, handling frequency aggregation, dealing with index publication lags), the description thoroughly covers all necessary context: what the tool does, how to use it correctly, what the output fields mean, and what to expect in terms of failures and limitations. It also clearly separates the tool from its siblings, making it a complete guide.

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

  Parameters5/5

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

  Although schema description coverage is 100%, the description enriches parameter understanding: it clarifies that `indice` maps to specific index codes (IPCA=433), the meaning of `mesBase` default, and the semantics of `agregacao` with a crucial caution about not summing monthly variations. This guidance directly prevents misuse even though the schema already lists descriptions.

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

  Purpose5/5

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

  The description starts with a clear, specific verb+resource: 'Converte uma série NOMINAL do BCB em valores REAIS (moeda constante)'. It distinguishes itself from siblings by explicitly naming alternatives like bcb_serie_valores for the raw nominal series, and provides a concrete real-world example. The distinction from sibling tools (including the when NOT to use case for percentage/index/rate series) is explicit and actionable.

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

  Usage Guidelines5/5

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

  Offers explicit 'Quando usar:' and 'Quando NÃO usar' sections, referencing the sibling bcb_serie_valores for the nominal case. It clearly explains the purpose of each parameter (índice, base, etc.) and provides behavioral nuances like the reconstruction limitation and how dates/out-of-coverage are handled, which directly informs when this tool is appropriate.

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

• bcb_focus_referenciasA
  5/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: partial results with 'falhas' if some scope fails, the origin ignores '$count', unfiltered queries do not complete, and microdata by institution is intentionally not exposed. No contradictions.

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

  Conciseness5/5

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

  The description is long but tightly structured and front-loaded. Each section earns its place: exact output purpose, usage timing, negative usage, parameter behavior, failure semantics, source context, and data-vintage explanation. It avoids fluff and uses formatting emphasis and clear transitions.

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

  Completeness5/5

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

  Given the presence of an output schema and annotations, the description still covers necessary non-schema context: when to call, scope semantics, failure resilience, counting/filtering constraints, source attribution, and the conceptual model of 'coletado' versus 'referencia'. It is complete for a discovery tool feeding bcb_focus_expectativas and bcb_focus_selic.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds real meaning beyond the enum: it explains that 'selic' is not a horizon but the Copom meeting axis, that the other scopes map to the horizons of bcb_focus_expectativas, and that omitting 'escopo' returns everything while providing it restricts the query. It also explains the optional 'indicador' use case in the context of discovering which scopes contain it.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Lista, POR ESCOPO, os indicadores e as referências que o Focus efetivamente publica' and immediately ties it to exact use in sibling tools. It clearly distinguishes this discovery tool from bcb_focus_expectativas and bcb_focus_selic.

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

  Usage Guidelines5/5

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

  It explicitly says when to use ('antes da primeira consulta ao Focus, ou quando uma consulta volta vazia'), when not to use ('Quando NÃO usar: para os valores das expectativas em si'), and names the alternatives that consume the result. This is exemplary usage guidance.

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