TickerFacts

Screen companies

screen_companies

Read-onlyIdempotent

Find US public companies whose latest annual period fundamentals match filters (minimum revenue, margins, ROE, growth; sector; profitable-only), sorted and limited. Returns a ranked list of companies with their key figures. Data traces to SEC EDGAR filings. For research and education only; not financial advice or a recommendation to buy, sell or hold.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	No	Match ticker prefix, company name, industry or sector
`sort`	No	Sort column; prefix with - for descending. e.g. -revenue (default), net_margin, -return_on_equity, revenue_growth
`limit`	No	Max results, 1 to 100 (default 25; larger values return 100)
`offset`	No	Rows to skip, for paging through total (default 0)
`sector`	No	One of: Agriculture, Mining, Construction, Manufacturing, Transportation & Utilities, Wholesale Trade, Retail Trade, Finance & Real Estate, Services, Public Administration
`roe_min`	No	Minimum return on equity, percent
`currency`	No	Reporting currency, default USD; all for name-sorted discovery without monetary filters
`exchange`	No	Exchange name, e.g. Nasdaq or NYSE
`industry`	No	Industry substring, e.g. semiconductors
`profitable`	No	Only companies with positive net income
`revenue_max`	No	Maximum annual revenue in the selected reporting currency
`revenue_min`	No	Minimum annual revenue in the selected reporting currency (default USD)
`include_stale`	No	Include companies whose latest annual report ended more than about 18 months ago (default false: they stopped filing US GAAP annual reports, or are late)
`net_income_min`	No	Minimum annual net income in the selected reporting currency
`net_margin_min`	No	Minimum net margin, percent
`gross_margin_min`	No	Minimum gross margin, percent (e.g. 40)
`total_assets_min`	No	Minimum total assets in the selected reporting currency
`debt_to_equity_max`	No	Deprecated alias for liabilities_to_equity_max. Preserves the old total-liabilities definition and returns a warning; cannot be combined with the canonical parameter.
`revenue_growth_min`	No	Minimum year-over-year revenue growth, percent
`operating_margin_min`	No	Minimum operating margin, percent
`liabilities_to_equity_max`	No	Maximum total liabilities / year-end equity. Includes non-debt liabilities.
`long_term_debt_to_equity_max`	No	Maximum long-term debt including current maturities / year-end equity. Excludes short-term borrowings and leases; not total debt.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 25, 2026

addedInput schema / properties / debt_to_equity_max / deprecated
```
Added value: +true
```

changedInput schema / properties / debt_to_equity_max / description

Previous value: -"Maximum total-liabilities / year-end-equity ratio (legacy parameter name)"New value: +"Deprecated alias for liabilities_to_equity_max. Preserves the old total-liabilities definition and returns a warning; cannot be combined with the canonical parameter."

addedInput schema / properties / liabilities_to_equity_max

Added value: +{
+  "description": "Maximum total liabilities / year-end equity. Includes non-debt liabilities.",
+  "type": "number"
+}

addedInput schema / properties / long_term_debt_to_equity_max

Added value: +{
+  "description": "Maximum long-term debt including current maturities / year-end equity. Excludes short-term borrowings and leases; not total debt.",
+  "type": "number"
+}

Changed2 schema fields changedSep 24, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / revenue_max

Added value: +{
+  "description": "Maximum annual revenue in the selected reporting currency",
+  "type": "number"
+}

Changed3 schema fields changedSep 24, 2026

addedInput schema / properties / include_stale

Added value: +{
+  "description": "Include companies whose latest annual report ended more than about 18 months ago (default false: they stopped filing US GAAP annual reports, or are late)",
+  "type": "boolean"
+}

changedInput schema / properties / limit / description

Previous value: -"Max results, 1-100 (default 25)"New value: +"Max results, 1 to 100 (default 25; larger values return 100)"

addedInput schema / properties / offset

Added value: +{
+  "description": "Rows to skip, for paging through total (default 0)",
+  "type": "integer"
+}

Changed8 schema fields changedSep 7, 2026

addedInput schema / properties / currency

Added value: +{
+  "description": "Reporting currency, default USD; all for name-sorted discovery without monetary filters",
+  "type": "string"
+}

changedInput schema / properties / debt_to_equity_max / description

Previous value: -"Maximum debt-to-equity ratio"New value: +"Maximum total-liabilities / year-end-equity ratio (legacy parameter name)"

addedInput schema / properties / exchange

Added value: +{
+  "description": "Exchange name, e.g. Nasdaq or NYSE",
+  "type": "string"
+}

addedInput schema / properties / industry

Added value: +{
+  "description": "Industry substring, e.g. semiconductors",
+  "type": "string"
+}

changedInput schema / properties / net_income_min / description

Previous value: -"Minimum annual net income, USD"New value: +"Minimum annual net income in the selected reporting currency"

changedInput schema / properties / q / description

Previous value: -"Match ticker prefix or company-name substring"New value: +"Match ticker prefix, company name, industry or sector"

changedInput schema / properties / revenue_min / description

Previous value: -"Minimum annual revenue, USD (e.g. 1000000000 for $1B)"New value: +"Minimum annual revenue in the selected reporting currency (default USD)"

changedInput schema / properties / total_assets_min / description

Previous value: -"Minimum total assets, USD"New value: +"Minimum total assets in the selected reporting currency"

First observedJul 21, 2026

TDQS

B3.3/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context about data provenance ('Data traces to SEC EDGAR filings') and a usage disclaimer, plus the behavioral fact that results are ranked and limited. It does not disclose potential data freshness caveats or how 'latest annual period' is determined beyond the include_stale parameter.

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?

The description is compact and front-loaded: it states the core screening purpose in the first sentence, summarizes the return shape in the second, and adds provenance/disclaimer in the third. Every sentence earns its place with no redundancy.

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

Completeness3/5

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

For a tool with 22 parameters and no output schema, the description gives only a minimal return summary ('ranked list of companies with their key figures'). It does not explain what 'key figures' are, how ranking works, or how pagination interacts with the result set. The schema covers parameters, but the description leaves some operational context unstated.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema fully documents all 22 parameters. The description does not add parameter-level meaning beyond what the schema provides, which is acceptable but not additive. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Find') and resource ('US public companies') and clearly states the screening criteria (fundamentals filters, sector, profitable-only, sorted/limited). It does not explicitly contrast itself with sibling tools like search_companies, so it lacks the sibling differentiation needed for a 5.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives such as search_companies or get_fundamentals. The description implies a screening use case but provides no exclusions, prerequisites, or alternative routing. The disclaimer about research/education is a restriction, not usage guidance.

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

All TickerFacts 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?