EdgarStack

Screen all SEC filers by a metric or a computed ratio

screen_companies

Read-onlyIdempotent

Find and rank companies across all SEC filers for a calendar-year (optionally quarterly) frame, using SEC's XBRL Frames API. Screen by EITHER:

metric: one reported value (revenue, grossProfit, operatingIncome, netIncome, epsBasic, epsDiluted, totalAssets, currentAssets, totalLiabilities, currentLiabilities, longTermDebt, totalEquity, cashAndEquivalents, operatingCashFlow, capex, rdExpense); or
a ratio: a named preset (grossMargin, operatingMargin, netMargin, rdIntensity, capexIntensity, fcfMargin, currentRatio, debtToEquity, returnOnAssets, returnOnEquity, cashToAssets, assetTurnover) or a custom numerator/denominator from the same metric list. Ratio inputs are joined only when all source metrics share the same periodEnd, denominators must be positive, and unusually large ratios carry a dataQualityFlags warning. Revenue uses the preferred tag and two known US-GAAP synonyms; the response lists tags queried and each result reports the tag selected. SEC calendar-year frames can contain an issuer's closest fiscal period rather than one ending December 31, so compare periodEnd (and sourceAccessionNumbers) across results. Ask for a min/max threshold when one is needed rather than guessing.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "year": "<year>"
    },
    "name": "screen_companies"
  }
}

Input Schema

Name	Required	Description	Default
`max`	No	Maximum value (metric) or ratio filter
`min`	No	Minimum value (metric) or ratio filter
`sort`	No		desc
`year`	Yes	Calendar year for the frame period
`limit`	No
`ratio`	No	A named preset ratio
`metric`	No	Screen by one reported metric. Do not combine with ratio/numerator/denominator.
`quarter`	No	Omit for full fiscal year (duration metrics) or a Q4 year-end snapshot (balance-sheet metrics)
`numerator`	No	Custom ratio numerator metric, if not using a preset
`denominator`	No	Custom ratio denominator metric, if not using a preset

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover read-only/idempotent/open-world, yet the description adds real behavioral depth: ratio joins only occur when source metrics share periodEnd, denominators must be positive, oversized ratios trigger dataQualityFlags, and frame periods may reflect an issuer's closest fiscal period rather than Dec 31. It also discloses tag-selection behavior for revenue and that the response reports tags queried.

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

Conciseness5/5

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

Purpose and mode selection are front-loaded, then caveats (period-end alignment, positive denominators, fiscal-year mismatch) follow. The long metric and ratio enumerations earn their space because they are unavailable in the schema itself.

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?

No output schema exists, so the description carries the burden of describing returns — it does note the tags-queried list and that each result reports the selected tag plus periodEnd/sourceAccessionNumbers. Remaining gaps are minor: response shape beyond tag metadata and how sort/limit interact with ratio mode are unstated.

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 80%, so the baseline is 3, but the description materially raises it: the 'metric' parameter has no enum in the schema, and the description supplies the full 16-metric vocabulary plus the instruction that custom numerator/denominator draw from that same list. The min/max filter semantics are also clarified, though limit/sort/year behavior is left to the schema.

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 concrete verb and resource — 'Find and rank companies across all SEC filers' — plus the data source (XBRL Frames API) and the year/quarter frame. The cross-filer ranking scope implicitly separates it from single-company siblings like company_snapshot or peer_compare.

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?

Explicitly frames the two mutually exclusive modes ('Screen by EITHER metric ... or a ratio') and gives operational guidance ('Ask for a min/max threshold when one is needed rather than guessing'). It stops short of naming when to prefer sibling tools such as compute_ratios or peer_compare instead.

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

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

Resources

Need Help?