Skip to main content
Glama
Val7h

dados-b3-mcp

by Val7h
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

screener

Screen all B3-listed companies by filtering indicator ranges. Define minimum or maximum values for ROIC, ROE, margins, and other fundamentals to shortlist stocks.

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.
  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

TableJSON Schema
NameRequiredDescriptionDefault
anoNo
as_ofNo
limiteNo
filtrosNo
chave_apiNo

Schema Changelog

Changes observed during successful MCP inspections.

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

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure — it does this well. It reveals that only unflagged values participate, suspicious indicators are silently excluded, unknown indicator names cause explicit errors, as_of reflects public data availability with an average lag, and the universe includes a survivorship bias (stated in the response). These are substantive behaviors beyond what a schema would show.

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-structured: an intro line, a parameter block with clear examples, and a final note on error handling. Every sentence carries information; there is little fluff. Given the complexity of the tool (5 parameters, multiple behavioral rules), the length is justified, though it could be slightly tightened without losing meaning.

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

Completeness4/5

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

For a complex tool with no output schema, the description covers the key operational aspects: parameters, defaults, errors, missing-data behavior, and as_of semantics. It mentions that each company brings 'disponivel_em' and that survivorship bias is stated in the response, but it does not fully describe the return shape or sorting/pagination behavior beyond the 'limite' parameter. Still, it is largely complete for an agent to use 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 description coverage is 0%, so the description must fully compensate — and it does. Each parameter (filtros, ano, as_of, limite, chave_api) gets meaning, format, defaults, constraints, and examples. It even explains the filtros key structure with _min/_max suffixes, accepted indicator names, and the fraction-not-percentage convention. This far exceeds the minimum needed.

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 'Filtra o universo inteiro da B3 por faixas de indicadores' — a specific verb (filter), resource (entire B3 universe), and criterion (indicator ranges). This distinguishes it from sibling tools like listar_empresas or indicadores_anuais, which focus on listing or retrieving raw indicators rather than screening by ranges.

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?

Provides strong usage context: explains when to call without filters (to get the menu of valid indicators), when to use as_of (for research to avoid look-ahead bias), and notes that as_of does not combine with ano. However, it does not explicitly name sibling tools or state when to prefer them over this screener, so it lacks explicit exclusions/alternatives.

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