Skip to main content
Glama
Sign In
Val7h

dados-b3-mcp

by Val7h
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

screener

Filtra o universo inteiro da B3 por faixas de indicadores.

Instructions

Filtra o universo inteiro da B3 por faixas de indicadores.

Parâmetros:
  filtros — dicionário de faixas. Cada chave é o nome de um indicador
    seguido de `_min` ou `_max`, e o valor é o número da faixa. Frações,
    não porcentagens: ROIC de 15% é 0.15.
    Exemplo: {"roic_min": 0.15, "dl_ebitda_max": 2}
    Indicadores aceitos: roic, roe, margem_bruta, margem_ebit,
    margem_liquida, dl_ebitda, cresc_receita_1a, cresc_receita_5a_cagr,
    piotroski.
    Chame SEM filtros para receber o cardápio: a lista de indicadores
    válidos e exemplos de uso.
  ano — exercício alvo. 0 (padrão) usa, para cada empresa, o último ano
    com dado disponível — que não é o mesmo ano para todas.
  as_of — data "AAAA-MM-DD". Responde outra pergunta: o que estava
    PÚBLICO naquele dia (balanço já recebido pela CVM, em média ~100 dias
    depois do fim do exercício). Use em pesquisa, para não olhar o futuro;
    cada empresa traz `disponivel_em`. Não combina com `ano`. O universo
    continua o das companhias ativas hoje (viés de sobrevivência, dito na
    resposta).
  limite — máximo de empresas na resposta. Padrão 100.
  recibo — True congela a resposta num endereço permanente, com a
    pergunta, a data de corte, a versão do dado e o sha256 do resultado.
    Use quando for CITAR a lista: ela muda quando a base é atualizada, o
    recibo não. Leia depois com a ferramenta `recibo`.
  chave_api — obrigatória aqui, mesmo para WEGE3, porque a consulta
    percorre todo o universo. Deixe "" para usar DADOS_B3_API_KEY.

Só entram valores SEM flag, isto é, números que passaram limpos pela
bateria de invariantes. Um indicador marcado como suspeito não é filtrado
silenciosamente: ele simplesmente não participa. Nome de indicador
desconhecido é recusado com erro, nunca ignorado.

Input Schema

NameRequiredDescriptionDefault
anoNo
as_ofNo
limiteNo
reciboNo
filtrosNo
chave_apiNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.9.0
    • addedInput schema / properties / recibo
      Added value: +{
+  "default": false,
+  "title": "Recibo",
+  "type": "boolean"
+}
  2. Changed1 schema field changedv1.6.0
    • addedInput schema / properties / as_of
      Added value: +{
+  "default": "",
+  "title": "As Of",
+  "type": "string"
+}
  3. Addedv1.1.1

TDQS

A4.9/5.0
Behavior5/5

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

No annotations, so the description carries the full burden and does: unknown indicator names error out rather than being ignored, flagged/suspect values silently drop out of filtering, the universe retains survivorship bias (stated and disclosed in the response), chave_api is mandatory here even for a single ticker because the query sweeps the whole universe, and recibo freezes a sha256-stamped snapshot. This is exactly the behavioral context annotations would otherwise supply.

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?

Purpose is front-loaded and parameters are cleanly sectioned, with the minimum-viable call (no filtros) surfaced early. The block is long, but with 0% schema coverage most sentences carry information that exists nowhere else; 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?

For a 6-param tool with no annotations and no output schema, the description covers invocation, edge semantics, error behavior, auth, and the meaning of key response fields (disponivel_em, survivorship caveat). An agent has everything needed to call it correctly.

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 0% (bare titles only), so the description must compensate and does so for all six parameters: the _min/_max key convention, fractions-not-percentages normalization, the accepted indicator list, default-vs-explicit ano semantics, as_of's ~100-day CVM lag, limite default 100, recibo's freezing behavior, and chave_api's "" fallback to DADOS_B3_API_KEY.

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+resource+scope: filters the entire B3 universe by indicator ranges. The scope phrase 'universo inteiro' distinguishes it from the many per-company siblings (indicadores_anuais, multiplos, scores) that operate on a single ticker.

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 when-to-use rules: call with no filtros to get the valid-indicator menu; use as_of instead of ano for point-in-time research and never combine them; use recibo when the list will be cited, then read it with the `recibo` sibling. Alternatives and exclusions are spelled out rather than inferred.

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

Deploy Server

Other Tools