Annalist Financial Statements

Screen companies

screen_companies

Read-onlyIdempotent

Screen the companies of the coverage as the Screener page of Annalist does, or rank them by one measure. With screen, the conditions of the page joined by commas: roic.gt.12 (latest value above 12; lt below), roic.gt.12.y5 (above 12 in each of the last 5 fiscal years), om.up.3 (higher than the year before in each of the last 3 fiscal years; dn lower), dte.chg.gt.0.5.y1 (change over the last fiscal year above 0.5), roic.top.25 (among the highest 25% of the companies screened; bot the lowest; .s within the sector) and band.in.minimal-modest (credit and quality signals: band, cover, netdebt, fcf, backing, altman, piotroski, beneish). start runs a starting screen such as rising-debt or high-returns. Each company comes with the figures behind each condition and its page, and page links the same screen for a person. Without screen, where and sort filter and rank by the latest value of ratio ids with a frequency, as corp.roic@ttm or corp.current_ratio@quarterly; an amount such as corp.net_debt is ranked within its currency. Call without arguments to list the measures and the starting screens.

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_companies"
  }
}

Input Schema

Name	Required	Description
`sort`	No	the measure to rank by, for example corp.operating_margin@ttm
`basis`	No	with screen: latest (default) for the last 4 quarters where reported, fy for the latest fiscal year of every company
`limit`	No	maximum companies (default 20)
`order`	No	desc (default) for the highest first
`start`	No	a starting screen of the Screener page, for example high-returns, rising-debt or credit-watch
`where`	No	conditions that every company meets, for example [{"measure": "corp.roic@ttm", "min": 15}]
`screen`	No	the conditions of a screen, for example roic.gt.12.y5,nde.lt.2 or band.in.significant-aggressive
`sector`	No	part of a sector name, for example Technology or Health care
`country`	No	ISO 3166 country code, for example US, GB, ID or HK
`markets`	No	with screen: ISO country codes, for example ["SG", "ID"]
`currency`	No	keep the companies that report in one currency, for example USD
`industry`	No	part of an industry name, for example Semiconductors or Banks
`template`	No

Output Schema

Name	Required	Description	Default
`note`	No
`page`	No
`basis`	No
`start`	No
`screen`	No
`filters`	No
`matched`	Yes
`measures`	Yes
`screened`	No
`companies`	Yes
`truncated`	Yes
`conditions`	No
`rules_version`	No
`without_value`	No
`screens_available`	No
`measures_available`	No

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 31, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavior beyond that: each company returns the figures behind every condition plus its page, and a page link reproduces the screen for a human, and the zero-argument call returns the measure/starting-screen catalog.

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

Conciseness3/5

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

Length is defensible for a 13-parameter DSL tool and the alternative modes are stated early, but the middle is a single run-on sentence that packs six condition grammars into one clause chain separated by semicolons, making it hard to scan. Information density is high with little waste, but structure is a wall of text.

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?

An output schema exists, so return values need no exposition (the description still usefully notes figures per condition and page links). It covers both modes, syntax, defaults, and discovery; remaining gaps are how `screen` and `where`/`sort` combine and how sector/industry/country filters interact with the screen.

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 coverage is already 92%, but the description supplies the `screen` mini-language grammar that the schema only gestures at: gt/lt, .y5 for each of the last five fiscal years, up/dn year-over-year, chg, top/bot percentiles, the .s sector-relative modifier, and band.in.<level> signal bands. It also explains that `sort`/`where` take ratio ids with a frequency suffix and that amounts such as corp.net_debt rank within their own currency.

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 companies of the coverage ... or rank them by one measure') and cleanly separates its two operating modes (screen DSL vs where/sort ranking). It never names a sibling such as search_companies or compare_companies, so an agent must infer that name-based lookup belongs elsewhere.

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 contrasts the two modes: with `screen` the conditions of the Screener page apply, without it `where` and `sort` filter and rank by ratio ids with a frequency. It also gives a concrete discovery path ('Call without arguments to list the measures and the starting screens'), but offers no exclusion telling the agent when to prefer search_companies or get_ratios instead.

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

All Annalist Financial Statements 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?