Brasil Data x402

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

With no annotations provided, the description carries the full burden and does meaningful work: it discloses the per-call price and payment rail ($0.005 USDC via x402), a free first call per day, and the provenance of the merged data. It does not cover authentication setup or rate limits beyond the daily free call, keeping it short of a 5.

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

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

Purpose is front-loaded in the first clause, followed by pricing and a concrete example. The example JSON is somewhat long, but since no output schema exists it earns its place by showing the return shape.

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?

There is no output schema, but the embedded example response shows the result structure (ispb, compe_code, short_name, cnpj, pix.participant), and pricing is disclosed, so an agent has enough to call and interpret it. Only minor gaps remain around error behavior and pagination for broad name queries.

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% and the single parameter is already documented, so the baseline is 3. The description restates the same identifier types without adding syntax, formatting, or disambiguation rules beyond the schema.

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

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

States a specific verb and resource (bank/payment institution lookup) plus the exact identifier types accepted (COMPE, ISPB, CNPJ, name). It also names the upstream sources (Banco Central STR and Pix participant lists), which distinguishes it from the similarly named cnpj_lookup sibling that resolves companies rather than banks.

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 accepted query formats imply when the tool applies, and the pricing sentence hints at the cost model, but there is no explicit when-to-use guidance or comparison against siblings like cnpj_lookup. An agent must infer that this is the right tool when the target is a bank rather than a company.

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

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

With zero annotations the description carries the full burden, and it delivers meaningful non-obvious context: exactly which calendar is applied (BR national + banking holidays), the DU day-count convention, and a cost model ($0.005 USDC per call via x402, first call per tool per day free). What it omits is the payment/auth mechanics — what an agent must be prepared to do to satisfy x402, and what happens if payment fails.

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 purpose and operations, then calendar scope, then pricing, then an example. Each sentence earns its place; the inline JSON example is compact and illustrative. Slightly dense but 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?

No output schema exists, and the embedded example response compensates well by showing the exact return shape (mode, from, to, business_days, calendar). The one real gap is mode coverage: the `date` parameter's schema description references a 'check mode' that the description never explains or enumerates, leaving a documented mode undefined.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including their mode assignment (from/to for count, date/add for add). The description adds only the DU convention and interval semantics on top of that, which is marginal beyond what the schema states. 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?

States a specific verb+resource pair: 'Brazilian business-day calculator' with the two concrete operations (count between two dates, add N days to a date) spelled out. An agent can tell what it does at a glance, but nothing distinguishes it from the sibling 'holidays' tool, which plausibly covers overlapping calendar territory.

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 splits behavior by mode ('count business days between two dates … or add N business days to a date') and pins down the DU convention and half-open (from, to] interval, which is useful mode-selection guidance. It never says when to prefer this tool over 'holidays' or any other sibling, and offers no exclusions, so usage is implied rather than directed.

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

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

With no annotations, the description carries the full burden; it does disclose the cost profile ('Free') and the exact shape of a successful response via the example. However, it says nothing about error behavior for invalid/malformed CEPs, rate limits, or whether any auth is needed, leaving real behavioral gaps.

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 purpose in the first clause, followed by the returned fields and a compact example. The example response is somewhat long but earns its place since no output schema exists.

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 one-parameter lookup with no annotations or output schema, the description supplies the full return field list and a concrete example, which is enough to call it correctly. The remaining gap is error/edge-case behavior.

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% and the single 'cep' parameter is already documented as '8 digits, e.g. 01001-000', so the baseline is 3. The description restates the resource but adds no format or validation detail beyond the schema.

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

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

States a specific verb and resource ('Brazilian postal code (CEP) to address') and enumerates exactly what is returned (street, district, city, UF, IBGE code, DDD). This clearly separates it from sibling lookups like cnpj_lookup and bank_lookup.

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

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

Usage is implied by the name and the input framing, and 'Free' signals there is no cost barrier, but the description never states when to use this versus alternatives or any prerequisite. No explicit context or exclusions are given.

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

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

With no annotations, the description carries the full burden and does notable work: it discloses the x402 payment model ($0.01 USDC per call, first call per tool per day free), the data provenance, and a full example response showing the return shape. It omits error behavior for invalid CNPJs and any rate/latency notes, keeping it short of a 5.

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

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

Front-loaded with the core purpose and field list, then pricing, then the example. The example response block is sizable but earns its place since no output schema exists. Slight density cost but no wasted sentences.

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 read tool with no output schema, the inline example response supplies the return shape an agent would otherwise lack, and the pricing model covers cost expectations. Remaining gaps (error handling, invalid CNPJ behavior) are minor.

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 single `cnpj` parameter is already documented as 14 chars with or without punctuation. The description's 'Supports alphanumeric CNPJ' merely restates what the schema already says, adding no meaning beyond structured data.

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 (registry lookup), a specific resource (Brazilian company/CNPJ), the data source (Receita Federal open data), and enumerates the returned fields. It is easily distinguished from siblings like cep_lookup or bank_lookup, which target postal codes and bank codes respectively.

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 scope (CNPJ input only, alphanumeric supported) implies when to use it, and the sibling names make the domain obvious, but there is no explicit when/when-not guidance or named alternative. Usage is inferred rather than stated.

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

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

With no annotations provided, the description carries the full burden and does meaningful work: it discloses the dataset is 'Free' (no auth/key implied), reveals that both national and banking holidays are mixed in via a 'kind' field, and supplies a concrete example response. It stops short of describing error behavior or what happens for out-of-range years, so it is strong but not exhaustive.

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

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

Purpose and scope are front-loaded in the first clause, followed by a short inclusion list, a one-word cost note, and an example. Nothing is padded, although the embedded example makes the single 'sentence' long.

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 read tool with no annotations and no output schema, the definition covers what is needed: what data comes back, the shape of the response (via example), and cost. The main omission is boundary/error behavior for the year range, which is a minor gap given the tool's simplicity.

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?

One parameter at 0% schema coverage, so the description must compensate. The phrase 'for a year' plus the example {"year":2026} makes the parameter's meaning and expected format clear, but the description never states the accepted range (1990–2100 lives only in the schema) or what an invalid year returns.

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 resource and scope: Brazilian national and banking holidays for a given year, and even enumerates notable entries (Carnival, Good Friday, Corpus Christi, Nov 20). It is immediately clear what the tool returns, though it never explicitly contrasts itself with the sibling 'business_days', which is the most likely confusion point.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative. A reasonable agent can infer this is for fetching holiday calendars, but nothing tells it when to prefer this over 'business_days' or how the two differ (holidays vs. computed working days).

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

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

With no annotations present, the description carries the full behavioral burden and does disclose the non-obvious commercial mechanic: $0.005 USDC per call via x402 with a free first daily call. It also shows the response shape. What is missing is data freshness/update lag, error behavior, and any auth/credential requirement beyond payment.

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 resource and its outputs, then pricing, then a concrete example. The embedded JSON example is verbose but justified since there is no output schema. Every sentence earns its place; 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 single-optional-parameter read tool with no output schema, the description supplies the return structure via example, names the data sources, and discloses cost. It stops short of stating refresh cadence or whether history is returned newest-first, which would matter to an agent assembling a report.

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% and the single parameter carries its own description with a default ('Months of history (default 12)'), so the schema does the work. The description never mentions the months parameter at all, adding nothing beyond the schema baseline of 3.

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?

Names a specific resource with source attribution ('Brazilian official inflation (IPCA, IBGE via BCB)') and enumerates exactly what is returned: latest monthly change, 12-month accumulated, and monthly history. This is clearly distinguishable from siblings like selic_rate or ptax_exchange_rate 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?

Usage is implied by the data domain rather than stated; there is no explicit guidance on when to prefer this over selic_rate or ptax_exchange_rate, nor any prerequisites. The pricing note ('first call per tool per day is free') does give a pragmatic reason to call this tool sparingly, which is a mild form of 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?

With no annotations provided, the description carries the full behavioral burden and discloses key traits: the official source, weekend/holiday fallback behavior, and the pricing model ($0.005 USDC per call via x402, first call daily free). It also gives an example response, though it omits error conditions or authentication details beyond the payment mechanism.

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 core purpose, followed by pricing and a compact example response. Every sentence earns its place: the fallback behavior, cost, and example return shape are all necessary for correct invocation and interpretation.

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 that there is no output schema and no annotations, the description is complete enough: it explains the data source, fallback semantics, cost, and provides a representative response example. No critical information needed to call or interpret the 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantic context beyond the schema: the date parameter falls back to the last bulletin before a weekend/holiday, and the currency parameter represents a foreign currency unit quoted in BRL. The example response also clarifies the distinction between requested_date and quote_date.

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 (retrieves) and resource (official PTAX exchange rate published by Banco Central do Brasil), with clear scope (BRL per unit of foreign currency, for a given date). It clearly distinguishes itself from sibling tools like selic_rate and ipca_inflation, which cover different economic indicators.

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

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

The description implies usage by specifying that it returns a rate for a given date and falls back to the last bulletin before weekends/holidays. However, it does not explicitly state when to choose this tool over alternatives such as bank_lookup or selic_rate, leaving usage guidance 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?

With no annotations, the description carries the full burden, and it does add real context: the $0.005 USDC charge via x402, the free first call per tool per day, and the upstream source. However, it omits rate limits, freshness/update cadence, and failure behavior, so a mutation-free read tool is still only partly characterized.

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 what the tool returns, followed by cost and a concrete example. The example JSON is long but earns its place because no output schema exists; the sentences are tight with 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 zero-parameter, no-output-schema read tool, the description supplies the units, annualization basis, source, cost, and an exact sample payload, which is nearly everything needed to call and consume it. Only cadence and error semantics are 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 schema has zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly avoids inventing parameter guidance.

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?

Names a precise resource set — Selic target set by Copom, daily annualized Selic, and CDI — with the issuing authority (Banco Central do Brasil). An agent immediately knows this is the Brazilian policy-rate data source, but the description never references siblings like ipca_inflation or ptax_exchange_rate to route the agent explicitly.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternative rate/inflation tools. The only usage-adjacent content is the pricing model, which tells the agent about cost but not when this tool is the right choice.

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