Brasil Data x402

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 two genuinely useful traits: the merged data provenance and the paid model ($0.005 USDC per call via x402), which an agent must know before invoking. It says nothing about return shape, empty/match-miss behavior, or error cases.

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

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

Two tight sentences, front-loaded with the core purpose and identifiers, followed by provenance and cost. No filler or 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 single-param tool with no output schema, the description should indicate what a result contains; it only hints at this via the provenance sentence. Cost and provenance are covered, but the return payload 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?

Only one parameter and schema description coverage is 100%, so the schema already documents 'query' and its accepted formats. The description merely restates those identifier types, adding no format details, precedence rules, or disambiguation 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 (lookup) and resource (Brazilian bank / payment institution) plus the four accepted identifier keys, which is far more specific than a tautology. However, it accepts CNPJ while a sibling cnpj_lookup also exists, and the description never clarifies the boundary between them, so sibling differentiation is only partial.

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

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

There is no explicit when-to-use guidance and no mention of the sibling cnpj_lookup that overlaps on the CNPJ identifier. The provenance sentence ('merged from STR participant list and active Pix participant list') is data-source context, not 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, the description carries the full burden and does disclose important behavioral facts: the holiday scope (national + banking), the DU/(from, to] convention, and a per-call price of $0.005 USDC via x402. It does not cover failure modes or what happens without payment, so it stops short of the top score.

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

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

A single dense sentence with the resource, both modes, and the price front-loaded in that order; every clause carries information and nothing is 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 4-parameter, no-annotation, no-output-schema tool it covers the operational essentials (modes, conventions, holiday basis, cost). The one notable omission is the return shape, which no output schema supplies either.

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 goes slightly beyond by grouping parameters into named modes (count uses from/to, add uses date/add), which the flat schema does not label. The DU convention itself is largely repeated from 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?

The description names a specific resource (Brazilian business-day calculator) and two concrete operations (count between two dates, add N days), plus the holiday basis it uses. An agent can distinguish this immediately from siblings like holidays or 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?

It implicitly separates the two modes via their parameter sets, but never states when to reach for this tool versus the sibling holidays or bank_lookup tools, nor any prerequisites. Usage is inferable from the mode descriptions rather than spelled out.

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?

No annotations are provided, so the description carries the behavioral burden. It does disclose one genuinely useful trait ('Free', i.e. no auth/cost), but says nothing about rate limits, error behavior for malformed CEPs, or whether results are cached. Adequate but thin for a tool with zero annotation coverage.

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?

Single telegraphic line with zero waste and the return fields front-loaded after the arrow. It is a fragment rather than a sentence, which slightly reduces readability but costs nothing in 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 one-parameter, no-output-schema lookup, the description effectively substitutes for an output schema by naming the returned fields (street, district, city, UF, IBGE code, DDD). Only the invalid-CEP behavior is left unspecified, a minor gap at this complexity.

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 there is only one parameter, so the schema already documents the 8-digit format and example. The description adds only the 'Brazilian' qualifier already implied by 'CEP', so baseline 3 applies.

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

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

States a specific verb (lookup) and resource (Brazilian postal code / CEP → address), and enumerates exactly what comes back. The resource is unambiguous against siblings like cnpj_lookup and bank_lookup, so the agent can select it without opening the schema.

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

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

Usage is implied by the input/output framing – an agent can infer it is called when converting a CEP into a Brazil address – but there is no explicit when/when-not statement and no sibling alternative is named. That is the minimum-viable level rather than real 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?

With no annotations, the description carries the full burden and does disclose meaningful behavioral facts: the data provenance (Receita Federal open data), the normalized result fields, support for alphanumeric CNPJ, and the paid access model ($0.01 USDC per call via x402). What is missing is anything about rate limits, errors, or latency for a non-CNPJ input.

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

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

A single dense sentence that front-loads purpose, then enumerates returned fields, then lists two operational caveats (alphanumeric support, price). Nothing is wasted, though the field enumeration in the middle is a long list without structure.

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, so the description usefully compensates by naming the returned data (legal/trade name, status, CNAE, address, Simples/MEI, QSA) and by disclosing the payment mechanism. For a single-parameter lookup this is close to complete, with only error/miss handling unaddressed.

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

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

Only one parameter and schema description coverage is 100%, so the schema fully documents the cnpj string, its 14-char length, punctuation tolerance and alphanumeric support. The description's note about alphanumeric CNPJ merely repeats the schema, adding no new syntax or format detail, so the 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 and resource (Brazilian company/CNPJ registry lookup) plus the authoritative data source (Receita Federal open data). The CNPJ domain is clearly distinct from siblings like bank_lookup and cep_lookup, so an agent can disambiguate immediately.

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 rather than stated: it is evidently the tool for looking up a company by CNPJ. However, it never states when to prefer it over siblings such as bank_lookup or cep_lookup, nor any prerequisites or failure conditions (e.g. invalid/unknown CNPJ).

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?

No annotations exist, so the description carries the full behavioral burden. It discloses cost ('Free') and scope ('national and banking'), but says nothing about return shape (list of dates? names?), ordering, timezone, or whether Carnival-style movable feasts depend on year. This is thin for a tool with zero annotation coverage.

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

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

One compact sentence, front-loaded with the resource and followed by clarifying examples and a cost note; no wasted clauses. The 'Free.' fragment and a parenthetical example list are slightly informal but still earn their place.

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 trivial one-parameter tool this covers what is fetched and that it is free, and the schema covers the accepted year range. However, with no output schema and no description of the return structure, an agent still does not know what it will receive back, leaving a real gap.

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

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

Schema coverage is 0%, but the single parameter is fully typed with an explicit 1990–2100 range in the schema. The description only implies 'year' via 'for a year' and adds no new semantics (e.g., behavior outside the range, format). Marginal value over the schema, so a middle score fits.

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

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

The description names a specific resource (Brazilian national and banking holidays for a year) and even enumerates the notable entries it covers (Carnival, Good Friday, Corpus Christi, Nov 20), which sets it apart from siblings like business_days and bank_lookup. The verb is only implicit ('returns'), and it never explicitly contrasts itself with business_days, so it falls short of a 5.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives; an agent must infer that this is the holiday-list tool versus business_days (working-day math). 'Free' hints at cost/auth but is not usage routing. Only implied usage is present, not 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the non-obvious cost ($0.005 USDC per call via x402) and implies a read-only data fetch, but says nothing about latency, rate limits, error conditions, or whether the latest month's figure is provisional.

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

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

Two tight clauses with no filler; the subject (what data, from whom) is front-loaded and the pricing caveat follows. Slightly more explicit routing would have justified a 5 but nothing is wasted.

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 data fetch with no output schema, the description covers the source, the three returned figures, and the cost, which is enough to invoke it correctly. Minor gaps remain around freshness/provisionality of the current month's reading.

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%: the single 'months' parameter is fully documented with bounds (1-60) and default (12) in the schema. The phrase 'monthly history' corroborates the schema but adds no syntax or semantic detail beyond it, so the baseline 3 applies.

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

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

States a specific resource and its provenance (IPCA, IBGE via BCB) plus exactly what it returns: latest monthly change, 12-month accumulated, and monthly history. It is clearly distinct from sibling economic indicators like selic_rate and ptax_exchange_rate, though it never names or contrasts those alternatives 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 mention of prerequisites, and no routing between this tool and closely related siblings such as selic_rate or ptax_exchange_rate. Usage can only be inferred from the returned fields.

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 well: it discloses the holiday/weekend fallback behavior, the authoritative source, and a concrete payment requirement ($0.005 USDC per call via x402), which an agent must know before calling. It omits any error or rate-limit behavior and how the value is returned, which keeps 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?

A single dense sentence carries the resource, unit convention, source, and fallback rule, followed by a short cost sentence. Everything is front-loaded and nothing is wasted.

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 two-parameter, zero-required scalar lookup with no output schema, the description covers the essential context: what the rate means, where it comes from, edge-case date behavior, and the per-call cost. The only meaningful gap is the shape of the returned value, which is minor for such a simple tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by defining the quoting convention ('BRL per unit of foreign currency') and by tying the fallback rule to the date parameter's semantics. It does not add format or validation detail beyond what the schema already states.

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

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

States a specific resource (official PTAX exchange rate), its exact semantics ('BRL per unit of foreign currency'), and the publishing authority (Banco Central do Brasil). This is trivially distinguishable from siblings like selic_rate or ipca_inflation, which are different indicators entirely.

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 resource itself (fetch the rate for a given date), and the weekend/holiday fallback hints at acceptable date inputs. But there is no explicit when-to-use/when-not guidance or mention of which sibling to prefer for other Brazilian financial data.

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 burden and does disclose a genuinely useful behavioral trait: the $0.005 USDC-per-call cost via x402, which tells the agent this is a paid invocation. It also characterizes the values fetched, though it does not describe return shape or freshness guarantees.

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

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

Two sentences, front-loaded with the resource and source, then the pricing detail. No filler or 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-param lookup with no output schema, the description identifies the specific quantities returned (Selic target, effective daily Selic, CDI, annualized basis), which is enough for correct invocation. It omits whether values are a single current snapshot versus a series, a minor gap.

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

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

The tool has zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate beyond the resource scope it already states.

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

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

States a specific resource (the Brazilian policy rate, including Copom's Selic target, effective daily Selic and CDI, annualized) and its authoritative source (Banco Central do Brasil). An agent can distinguish this cleanly from siblings like ipca_inflation or ptax_exchange_rate.

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?

No explicit when-to-use guidance or named alternatives, but the tool takes zero parameters and has a single unambiguous data-lookup purpose, so the omission is low-cost. Usage is implied by the resource named rather than stated.

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