Brazil Cvm Financials

Br Financials

br_financials

Read-onlyIdempotent

Annual financial statements (DFP) of a Brazilian listed company from CVM open data: balance sheet, income statement, cash flow and value added, as account lines with CVM account codes and Portuguese labels, in full BRL. Identify the company by cnpj (e.g. "00.000.000/0001-91" or 14 digits) or by name (e.g. "Petrobras"; an ambiguous name returns candidates instead of a guess). year is the fiscal reference year (default: latest loaded). scope is "consolidated" or "individual" (default: consolidated when the company filed one, else individual -- the response says which). Only the latest filing version is kept; the response states it. statement narrows to one of BPA (assets), BPP (liabilities and equity), DRE (income), DFC_MI / DFC_MD (cash flow indirect / direct), DVA (value added). max_depth (default 2) limits account-code depth so a default call returns the headline lines; raise it for sub-accounts. Results page with limit/offset and report truncated/total_matching. A company or year not in the data returns found:false with data_as_of, never an empty success.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cnpj": "33.000.167/0001-01",
      "year": 2024,
      "statement": "DRE"
    },
    "name": "br_financials"
  }
}

Input Schema

Name	Required	Description
`cnpj`	No	Company CNPJ, formatted or 14 digits. Pass cnpj or name.
`name`	No	Company name, e.g. "Petrobras", "Itau Unibanco". Accents optional.
`year`	No	Fiscal reference year, e.g. 2024. Default: latest loaded for that company.
`limit`	No	Lines per page, 1-500 (default 100).
`scope`	No	Default consolidated if filed, else individual.
`offset`	No	Lines to skip (default 0).
`max_depth`	No	Account-code depth, 1-6 (default 2: e.g. "3.01" but not "3.01.01").
`statement`	No	One statement only. Default: all.

Output Schema

Name	Required	Description	Default
`cnpj`	No
`found`	No
`lines`	No
`scope`	No
`units`	No
`source`	No
`company`	No
`licence`	No
`currency`	No
`cvm_code`	No
`returned`	No
`max_depth`	No
`truncated`	No
`data_as_of`	No
`statements`	No
`filed_scale`	No
`fiscal_year`	No
`scopes_filed`	No
`filing_version`	No
`reference_date`	No
`total_matching`	No
`filing_received`	No
`fiscal_years_loaded`	No
`filing_versions_seen`	No
`latest_filing_received`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 25, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: discloses that ambiguous names return candidates, only the latest filing version is kept (and the response states it), the scope fallback logic, pagination truncation reporting, and that a missing company/year returns found:false with data_as_of rather than an empty success. These are exactly the behavioral traits an agent needs before calling.

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?

Front-loads the what-and-source in the first sentence, then layers parameters and edge-case behavior in a single dense paragraph with no filler. It is long, but nearly every clause carries information; only minor tightening is possible.

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, the description needn't explain return shapes, and it still covers pagination (limit/offset, truncated/total_matching), not-found semantics, version selection, and scope resolution. Nothing an agent needs to invoke it correctly is missing.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3; the description adds genuine meaning on top — the full statement code glossary (BPA/BPP/DRE/DFC_MI/DFC_MD/DVA), the effect of max_depth on returned line depth, and the scope default rationale. It stops short of syntax details for name matching beyond 'accents optional', but the extra semantic mapping is real value.

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?

States a specific verb and resource — annual financial statements (DFP) of a Brazilian listed company from CVM open data — and enumerates the four statements included (balance sheet, income statement, cash flow, value added) with units (full BRL) and labels. This clearly separates it from br_financial_series (series) and br_financials_search (discovery) without needing their schemas.

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

Usage Guidelines4/5

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

Gives concrete usage context: identify the company by cnpj OR name, ambiguous names return candidates rather than guessing, defaults for year and scope, and how to raise max_depth for sub-accounts. However, it never explicitly routes the agent to sibling tools like br_financial_series for multi-year trends or br_financials_search to resolve a company, so alternatives are only implied.

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

All Brazil Cvm Financials tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.