Clarifo

screen_companies

Read-onlyIdempotent

Rank or screen companies by one financial metric ("which S&P 500 companies grew revenue most in 2025?"). For one company use get_company_financials.

Chart: per the server "Charts" guidance; in ChatGPT call render_chart(source_tool="screen_companies", source_args=, output="python").

Args: metric: e.g. revenue, ebit, ebitda, net_income, operating_cash_flow, free_cash_flow, marketcap; IFRS line items (total_assets, ...); Nordic KPIs (order_book, equity_ratio); ratios gross_margin, operating_margin, ebit_margin, net_margin, ebitda_margin, fcf_margin (0.25 = 25 %). US lacks marketcap, free_cash_flow (use fcf_margin) and the Nordic KPIs. US ebitda is operating income + D&A and fcf_margin is (OCF - capex) / revenue; companies without a D&A or capex line are left out, never zeroed. mode: "growth" (default, YoY %) or "value" (alias "level"). year: Anchor fiscal year; omit for the latest with data. compare_years: Growth mode: years back (default 1). country: "US", "FI", "SE" or "Nordic" (all Nordic issuers in one call; do not call per country). Omit for all; value mode then mixes currencies (use value_anchor_eur). industry: Free-text substring. tag_slugs: precise taxonomy filter. top_n: 1-100 (default 20). direction: "desc" (default) / "asc". min_value: Floor on value_anchor (native currency). include_types: "operating", "holding", "reit", "bank", "investment_vehicle"; ["operating"] excludes banks/REITs/holdings. index: "sp500"; forces country="US".

growth_pct is null when a value is negative; use trend and delta_absolute instead.

Returns companies (value_anchor, value_compare, growth_pct, currency) and coverage (total_in_scope, with_data, returned). Surface coverage_warning and data_quality_warning / excluded_data_quality (rows withheld for an implausible scale or currency change).

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	Default
`mode`	No	growth
`year`	No
`index`	No
`top_n`	No
`metric`	No	revenue
`country`	No
`industry`	No
`direction`	No	desc
`min_value`	No
`tag_slugs`	No
`compare_years`	No
`include_types`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: discloses that US lacks marketcap, free_cash_flow and Nordic KPIs, that ebitda/fcf_margin are computed with specific formulas, that companies missing D&A or capex lines are excluded rather than zeroed, that growth_pct is null for negatives, and that coverage/data_quality warnings may withhold rows.

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 purpose, alternative, chart instruction, then a structured Args block and a Returns block. It is long, but nearly every line carries operational detail; the chart/rendering paragraph is the one section slightly tangential to the screening task itself.

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

Completeness5/5

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

For a 12-parameter, zero-schema-documentation tool this is unusually complete: parameter meanings, formula caveats, exclusion behavior, return keys, and warning surfacing are all covered, so no critical calling information is missing.

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 description coverage is 0%, but the Args block documents all 12 parameters with concrete values, units and edge cases (metric catalog, mode aliases, top_n range 1-100, include_types semantics, min_value currency basis). This fully compensates for the empty schema descriptions.

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?

Opens with a specific verb+resource and scope: 'Rank or screen companies by one financial metric', plus a concrete example query. It immediately distinguishes itself from get_company_financials for the single-company case.

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?

Explicitly routes single-company lookups to get_company_financials, tells the agent to use one Nordic call rather than per-country calls, notes that index forces country="US", and points to screen_companies_multi-adjacent behavior via the multi-country note. It also states when value_anchor_eur is needed.

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

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