Bullrun

Screen stocks

screen_stocks

Read-only

Filter global stocks by custom fundamental rules or named presets like value, dividend, and growth screens, with sector, country, and lookback controls, to surface candidates that fit your criteria.

Instructions

Screen the global Bullrun stock universe with the app rule engine using custom fundamental rules or named presets: profitable value, dividend income, growth and cash flow, cash generators, dividend growth. action=list_presets discloses exact thresholds, units, annual lookback and sorting without any backend request. action=run (default) executes one preset or custom rules; running uses the API's metered screening budget. Custom screens support sector/industry/country, listing controls, annual/quarterly lookback, AND/OR rule groups and money units. Presets are mechanical starting points, not recommendations or famous-investor strategies. Read-only.

Input Schema

Name	Required	Description	Default
`mode`	No	Deprecated alias for lookbackMode; kept for compatibility.
`limit`	No	Maximum stocks to return: custom default 25 (1-100), preset default 20 (1-50).
`order`	No	Sort direction. Custom default desc; presets use their disclosed order. Nulls always sort last regardless of direction.
`rules`	No	Fundamental rules. Same groupId means AND; different groupIds mean OR.
`action`	No	list_presets discloses named screens without any backend request; run executes a preset or custom rules and uses the metered screening budget.	run
`preset`	No	Optional named screen. Presets use disclosed fixed rules/sorting, annual lookback (2-10 years), primary active listings and a default limit of 20 (maximum 50). Omit for custom rules; do not combine with rules or minMarketCap.
`sector`	No	Exact sector name to filter by, e.g. "Technology", "Healthcare". Omit for all sectors.
`sortBy`	No	Metric to sort by. Custom default marketCap; presets use their disclosed sorting. revenueGrowth is accepted as an alias for revenueGrowthPct.
`country`	No	Exact country name to filter by, e.g. "United States", "Germany". Omit for all countries.
`periods`	No	Deprecated alias for lookback; kept for compatibility.
`industry`	No	Exact industry name to filter by, e.g. "Software - Infrastructure". Omit for all industries.
`lookback`	No	How many reporting periods to evaluate (default 3). Growth rules need at least 2 comparable periods; presets require 2-10 annual observations.
`countries`	No	Exact country names to include. Use this for multi-country screens; it overrides country when provided.
`lookbackMode`	No	Whether rule evaluation uses annual or quarterly reporting periods. Default annual; presets require annual.
`minMarketCap`	No	Compatibility shortcut: adds marketCap >= this absolute value to every rule group.
`includeInactive`	No	Include delisted/inactive tickers with no recent price bar. Default false.
`includeSecondary`	No	Include secondary cross-listings of the same security. Default false (primary listings only).

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedv0.8.1Oct 22, 2026

addedInput schema / properties / action

Added value: +{
+  "default": "run",
+  "description": "list_presets discloses named screens without any backend request; run executes a preset or custom rules and uses the metered screening budget.",
+  "enum": [
+    "list_presets",
+    "run"
+  ],
+  "type": "string"
+}

removedInput schema / properties / limit / default
```
Removed value: -25
```

changedInput schema / properties / limit / description

Previous value: -"Maximum number of stocks to return (1-100)."New value: +"Maximum stocks to return: custom default 25 (1-100), preset default 20 (1-50)."

removedInput schema / properties / lookback / default
```
Removed value: -3
```

changedInput schema / properties / lookback / description

Previous value: -"How many reporting periods to evaluate. Growth rules need at least 2 comparable periods."New value: +"How many reporting periods to evaluate (default 3). Growth rules need at least 2 comparable periods; presets require 2-10 annual observations."

removedInput schema / properties / lookbackMode / default
```
Removed value: -"annual"
```

changedInput schema / properties / lookbackMode / description

Previous value: -"Whether rule evaluation uses annual or quarterly reporting periods."New value: +"Whether rule evaluation uses annual or quarterly reporting periods. Default annual; presets require annual."

removedInput schema / properties / order / default
```
Removed value: -"desc"
```

changedInput schema / properties / order / description

Previous value: -"Sort direction. Nulls always sort last regardless of direction."New value: +"Sort direction. Custom default desc; presets use their disclosed order. Nulls always sort last regardless of direction."

addedInput schema / properties / preset

Added value: +{
+  "description": "Optional named screen. Presets use disclosed fixed rules/sorting, annual lookback (2-10 years), primary active listings and a default limit of 20 (maximum 50). Omit for custom rules; do not combine with rules or minMarketCap.",
+  "enum": [
+    "profitable_value",
+    "dividend_income",
+    "growth_and_cashflow",
+    "cash_generators",
+    "dividend_growth"
+  ],
+  "type": "string"
+}

removedInput schema / properties / rules / default
```
Removed value: -[]
```
removedInput schema / properties / sortBy / default
```
Removed value: -"marketCap"
```

changedInput schema / properties / sortBy / description

Previous value: -"Metric to sort by. revenueGrowth is accepted as an alias for revenueGrowthPct."New value: +"Metric to sort by. Custom default marketCap; presets use their disclosed sorting. revenueGrowth is accepted as an alias for revenueGrowthPct."

First observedv0.1.0Jun 30, 2026

TDQS

A4/5.0

Behavior4/5

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

Adds context beyond the annotations: list_presets performs no backend request, while run consumes the API's metered screening budget — a genuine cost/rate consideration an agent needs. It also discloses the 'not a recommendation' framing and restates read-only. It does not describe the response shape or what a screened result set looks like.

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?

Front-loaded with the core verb and the preset list, then the mode semantics, then the caveats. Some clauses are dense ('Custom screens support sector/industry/country, listing controls...') and could read as a feature dump, but no sentence is filler.

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 17-parameter, zero-required screening tool with no output schema, the description covers the decision-relevant surface well: mode selection, budget cost, preset semantics, and scope of custom rules. The notable gap is that it says nothing about what a returned result contains or how many rows are ranked, which the agent must infer from the limit schema.

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 100%, so the baseline is 3; the description goes further by naming the capability surface an agent would otherwise have to reconstruct from 17 properties — sector/industry/country filters, listing controls, annual vs quarterly lookback, AND/OR rule groups, and money units. It stops short of explaining parameter interactions (e.g. that presets cannot be combined with rules or minMarketCap, which only appears in the schema).

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?

States a specific verb and resource ('Screen the global Bullrun stock universe with the app rule engine') and enumerates the two operating modes (custom rules vs named presets, with the five preset names). It implicitly separates itself from screen_etfs via 'stock universe' but never names a sibling explicitly to sharpen the boundary.

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?

Clearly explains when to use action=list_presets (discloses thresholds without a backend request) versus action=run (executes and consumes the metered budget), and warns that presets are mechanical starting points, not recommendations. It does not tell the agent when a different sibling tool (e.g. search_stocks, screen_etfs) is the better fit.

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

Deploy Server

Screen stocks

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools