Skip to main content
Glama

Kaleidoscope MCP (SEC & financial data)

Fundamentals Screen (cross-sectional XBRL screen — revenue/margin/growth/cash-flow filters)

screen_fundamentals
Read-onlyIdempotent

Cross-sectional screen over XBRL fundamentals: 'which companies have X financial profile', not 'show me company X's history' (that's get_fundamentals). Defaults to each company's LATEST quarter within the given scope, then applies every filter to that one quarter — a company whose latest quarter doesn't qualify is excluded even if an earlier quarter would have.

Numeric filters take _min/_max suffixes (e.g. revenue_min=1e9, operating_margin_min=0.15). Boolean filters (revenue_growing, margin_expanding, earnings_positive, cash_generation_positive, diluting, deleveraging) restrict to true when set.

us_only=true excludes Foreign Private Issuers (20-F) and Canadian MJDS filers (40-F) via form_type — no state-of-incorporation lookup needed, form_type is the SEC's own structural distinction.

Revenue filtering/sorting always applies a non-configurable revenue < $1T sanity guard — some non-USD filers (e.g. Telkom Indonesia, Ecopetrol) have nominal nine-figure-trillion nonsense in USD terms purely from unconverted foreign-currency reporting; reporting_currency is returned per row so you can see which currency a number is actually in.

view='full' returns every fundamentals_cooked column; default 'compact' returns identity + the standard margin/growth/flag set. fields adds specific extra columns (ignored if unknown). Every row carries accession_number (the 10-Q/10-K the quarter comes from) and filing_url.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "screen_fundamentals"
  }
}

Input Schema

NameRequiredDescriptionDefault
sicNo
ciksNo
viewNocompact
limitNoDefault 25, max 200.
fieldsNoExtra columns beyond the compact/full default, e.g. ['total_assets','cash'].
sic_maxNo
sic_minNo
sort_byNorevenue
tickersNo
us_onlyNoExclude 20-F/40-F foreign filers.
dilutingNo
sort_dirNodesc
end_date_toNoYYYY-MM-DD, inclusive upper bound. Default: no bound (latest available).
revenue_maxNo
revenue_minNo
accruals_maxNo
accruals_minNo
deleveragingNo
end_date_fromNoYYYY-MM-DD, inclusive lower bound on the qualifying quarter's end_date.
fiscal_periodNoRestrict the 'latest quarter' selection to this fiscal_period (e.g. 'Q4', 'FY').
fcf_margin_maxNo
fcf_margin_minNo
net_margin_maxNo
net_margin_minNo
cash_runway_maxNocash_runway_quarters — low values flag cash-burn risk.
cash_runway_minNo
revenue_growingNo
revenue_yoy_maxNo
revenue_yoy_minNo
margin_expandingNo
earnings_positiveNo
operating_margin_maxNo
operating_margin_minNo
cash_generation_positiveNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already cover read-only, idempotent, closed-world, and non-destructive behavior. Beyond that, the description discloses latest-quarter selection and exclusion, the non-configurable revenue sanity guard, unconverted foreign-currency caveats, compact/full view behavior, and ignored unknown fields.

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 dense but front-loaded, with paragraphs organized around distinct concerns: purpose, filter conventions, foreign-filer handling, and return shape. The examples add useful rationale, though the definition is long enough that some trimming is possible.

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?

Given 34 parameters, low schema description coverage, and no output schema, it provides substantial context: row identity, reporting_currency, accession_number, filing_url, and compact/full return modes. Some details such as sorting and limit behavior rely on the schema, but the core selection and return behavior are adequately covered.

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?

With only 21% schema description coverage, the description supplies important meaning: the _min/_max convention, the set of boolean filters, us_only semantics, view/fields behavior, and the revenue guard. It leaves sorting, limit, and several scope-selector parameters largely to the schema, so it is strong but not fully comprehensive.

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 states a specific verb and resource: a cross-sectional screen over XBRL fundamentals. It explicitly distinguishes the tool's question ('which companies have X financial profile') from get_fundamentals' per-company history.

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?

It gives explicit when-to-use guidance by contrasting cross-sectional screening with company-history lookup and naming get_fundamentals as the alternative. It also clarifies the latest-quarter qualification behavior that determines whether a company appears.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources