Clarifo

search_filings

Read-onlyIdempotent

Search company filings (SEC 10-K / 10-Q / 8-K, annual and interim reports, stock exchange releases), or with mode the report calendar and the earnings season. To read a filing's text use search_filing_content.

Modes:

"filings" (default): documents with fiscal_year, quarter, document_type, docid, period_end (safe for cross-company timelines) and filed_date; year_from / year_to filter on fiscal year. market="us" with no company lists all US filings.
"calendar": scheduled report dates in from_date..to_date (default today .. +14 days, max 120), optionally one company or market; published: true once the report is in Clarifo. Never extend the calendar with guessed dates.
"season": a calendar quarter's earnings season (year_from + quarter, default the latest ended): breadth and medians of revenue / margin / EPS change, sectors, outliers, largest still to report. Shares and medians are over coverage.with_revenue_growth (companies with figures so far), not all coverage.reported; name that base. company = comma-separated watchlist, to_date = as-of date.
"reported": one row per company and period with released_at (US: the earnings 8-K), filed_at (10-Q / 10-K), status (released | filed), US figures and growth (figures_source = xbrl | release_table). Default window the last 30 days. Any "share that grew" is over counts.with_revenue_growth ("12 of the 15 with figures so far"); counts.sp500_universe gives "x of 500".
"risk_factors": a US filer's Risk Factors section as individual risk factors (heading, category), latest 10-K / 20-F / S-1 / F-1 or docid; query (words that must appear) returns the matching factors' text.
"risk_changes": risk factors added, removed and modified between two filings (default: docid or the latest vs the previous 10-K, 20-F or registration-statement version; compare_to = the older docid), with the sentences added, removed and edited.

Args: company: Name or ticker, fuzzy-matched ("DHI", "D.R. Horton"). document_type: "annual_report", "interim_report", "stock_exchange_release", "10-K", "10-Q", "8-K". market: "nordic" (HEL, STO, OMXH) or "us" (NYSE, NASDAQ); omit for both. Season also takes "fi"/"HEL", "se"/"STO", "all" (default us). quarter: 1-4 with year_from = the calendar quarter the period ended in. index ("sp500"), status, min_revenue_growth_pct, sort: reported mode; sort = reported_at (default), revenue, revenue_growth_pct, net_income_growth_pct, eps_growth_pct, company. sector: Season and reported, GICS sector(s), comma-separated. from_date / to_date: YYYY-MM-DD. docid / compare_to: SEC accession numbers (risk modes). limit: Default 20, max 100. offset: max 1000, with has_more.

Returns filings (calendar: events; reported: rows), total (this page), total_available, has_more, resolution.

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": "search_filings"
  }
}

Input Schema

Name	Required	Default
`mode`	No	filings
`sort`	No
`docid`	No
`index`	No
`limit`	No
`query`	No
`market`	No
`offset`	No
`sector`	No
`status`	No
`company`	No
`quarter`	No
`to_date`	No
`year_to`	No
`from_date`	No
`year_from`	No
`compare_to`	No
`document_type`	No
`min_revenue_growth_pct`	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?

Annotations already declare readOnly/idempotent/non-destructive, so this description adds the operational detail that matters: default windows (calendar today..+14 days, max 120; reported last 30 days), pagination ceilings (limit max 100, offset max 1000, has_more), and the important denominator caveat that shares/medians are over coverage.with_revenue_growth rather than all coverage.reported, with instructions to name that base.

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?

Well front-loaded: one-line purpose plus a sibling pointer, then a mode list, then an Args block — a structure that matches how an agent reads. It is long and dense with backtick-formatted field names, and some mode bullets pack several distinct rules into one sentence, but nearly every clause carries information an agent would otherwise have to guess.

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 19-parameter, five-mode tool this is complete: modes, defaults, filter scope per mode, parameter meanings, pagination ceilings, and the return envelope (filings/events/rows, total, total_available, has_more, resolution) are all covered. With an output schema present, no further return-value detail is required.

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%, so the description carries the full burden — and it does: company fuzzy matching with examples, document_type values, market values including season aliases ('fi'/'HEL', 'se'/'STO', 'all'), quarter semantics tied to year_from, sort enumerations, sector as comma-separated GICS, date format YYYY-MM-DD, and docid/compare_to as SEC accession numbers. Even mode-scoped params (query, index, status) are defined in their mode bullets.

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 and resource ('Search company filings') and enumerates what is searchable (10-K/10-Q/8-K, annual and interim reports, exchange releases), plus the mode switch. It explicitly routes text-reading to the sibling: 'To read a filing's text use search_filing_content.' An agent can distinguish this from search_filing_content and get_filing_snapshot without opening any schema.

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?

Each of the five modes carries its own when-to-use context and defaults (filings = default, calendar for scheduled dates, season for earnings-season aggregates, reported for per-company release/filing status, risk modes for SEC risk factors). It also states negative guidance — 'Never extend the calendar with guessed dates' — and clarifies which mode takes which filter scoping ('market="us" with no company lists all US filings').

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.