> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stockinsights.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# US MCP tools

> Reference for the eight stockinsights.ai US MCP tools: company research, SEC filings, earnings transcripts, announcements, and financial statements.

The US server at `https://api-us.stockinsights.ai/mcp` exposes these eight read-only tools. Ask your assistant a research question to use them, or use this reference when building an MCP client.

## Company research

### `resolve_companies`

Resolve US company names or ticker symbols to ranked company matches. Each match includes `company_id`, `company_name`, a plain `ticker`, and a match score.

| Input | Description |
| - | - |
| `entities` (required) | 1–20 company names or ticker symbols, such as `Apple Inc`, `AAPL`, or `MSFT`. Use plain identifiers without exchange prefixes. |
| `limit_per_entity` | Matches per input: 1–10, default 5. |

Use the returned plain ticker in subsequent tools.

### `filter_companies`

Screen listed US companies and retrieve CIK identifiers, industry classifications, and stored market-cap snapshots. Delisted companies are excluded.

Supply at least one screening criterion:

| Input | Description |
| - | - |
| `tickers` | Up to 50 plain tickers, such as `AAPL` or `BRK.B`. |
| `marketcap_categories` | Any of `mega`, `large`, `mid`, `small`, `micro`, or `nano`. |
| `industry_filters` | Up to 20 exact classification objects using `industry_sector` and `industry`. Fields within an object combine with AND; objects combine with OR. |
| `marketcap` | Numeric filter in **USD, unscaled**. Accepts `eq` alone, or lower and upper bounds using `gt`, `gte`, `lt`, and `lte`. |
| `sort` | `field`: `company_name`, `ticker`, or `marketcap`. `direction`: `asc` or `desc`. Defaults to market cap descending. |
| `limit`, `cursor` | 1–100 companies, default 20. Continue with `meta.next_cursor` using identical filters and sort. |

For example, `marketcap: { "gte": 1000000000 }` selects companies with market cap of at least USD 1 billion. US screening supports market cap; share-price, 52-week high/low, and PE-ratio filters are unavailable.

## Filing research

### `list_filings`

List filing metadata newest first, across the market or for selected companies. Results include filing IDs and citation links.

| Input | Description |
| - | - |
| `filing_type` (required) | One of `earnings-transcript`, `10-K`, `10-Q`, or `20-F`. |
| `filters.tickers` | Up to 100 plain tickers. Omit for a market-wide feed. |
| `filters.fiscal_years` | Years such as `FY25`, for 10-K and 20-F filings only. Matches the stored filing report-end year. |
| `filters.fiscal_quarters` | Quarters such as `FY25Q1`, for 10-Q filings and earnings transcripts only. |
| `limit` | 1–50 filings, default 50. |

Use `get_announcements` for corporate disclosures, `search_filings` to find passages, and `get_filing_content` to read a selected filing.

### `search_filings`

Search earnings transcripts, 10-K, 10-Q, and 20-F filings. Returns matching passages with filing IDs, chunk numbers when available, citation links, and retrieval status.

| Input | Description |
| - | - |
| `search_method` (required) | `keyword` for exact terms, quoted phrases, or named metrics; `semantic` for concepts, guidance, or management commentary. |
| `query` (required) | Search text, 1–500 characters. |
| `filters.tickers` | Up to 100 plain tickers. Required when supplying a filters object; use `null` or an empty array for all companies. |
| `filters.filing_criteria` | Up to four objects. Required when supplying a filters object; use an empty array for all supported types. Each object requires `filing_type` and `period`. |
| `filters.latest` | Defaults to `true` for criteria without an explicit period. Set `false` to search all history for those criteria. |

Each criterion's `period` is either `null` to follow `filters.latest`, or an object with `calendar_years` (such as `"2025"`) or `fiscal_quarters` (such as `"FY25Q1"`). Explicit periods take precedence over `latest`. Omitting filters searches the latest filing of every supported type across all companies.

For example, search the latest NVIDIA earnings transcript with these request fields:

```json theme={null}
{
  "search_method": "semantic",
  "query": "management outlook on data center demand",
  "filters": {
    "tickers": ["NVDA"],
    "filing_criteria": [
      { "filing_type": "earnings-transcript", "period": null }
    ],
    "latest": true
  }
}
```

### `get_filing_content`

Read one US filing by chunk. Select the filing using either its `document_id`, or a ticker together with `time_scope`.

| Input | Description |
| - | - |
| `filing_type` (required) | `earnings-transcript`, `10-K`, `10-Q`, or `20-F`. |
| `document_id` | The `filing_id` returned by `list_filings` or `search_filings`. Selects that exact filing; omit `ticker` and `time_scope`. |
| `ticker` | One plain ticker. Required with `time_scope` when `document_id` is absent. |
| `time_scope` | `{ "mode": "latest" }`, or `mode: "period"` with `fiscal_year` for 10-K/20-F or `fiscal_quarter` for transcripts/10-Q. |
| `chunk_selection` | Up to 10 chunks using `mode: "range"` with `start_chunk` and `end_chunk`, or `mode: "chunks"` with a `chunks` array. Chunk numbers start at 1. |

Use the chunk numbers returned by search results or their `#chunk<n>` citation anchors. Without `chunk_selection`, the response starts at chunk 1 and stops at a size limit. Check `truncated` and `total_chunks` to determine whether you need more content. US filings use chunks rather than page selections.

## Corporate announcements

### `get_announcements`

Fetch AI summaries of US corporate announcements, newest first, with company information and citation links.

| Input | Description |
| - | - |
| `tickers` (required) | 1–50 plain US tickers. Screen companies first and query in batches for a broader universe. |
| `category` | Exact category names, such as `Earnings Reports`. Set to `null` for all categories. |
| `time_period` | `start_date` and `end_date` in `YYYY-MM-DD` format. Omit or set to `null` for the last month. |
| `sentiment` | Any of `positive`, `negative`, or `neutral`. |
| `significance` | `true` for significant announcements only; `false` for non-significant only. |
| `page`, `limit` | Page starts at 1. Page size is 1–50, default 50. |

Results report the searched date window, `meta.total_count`, and `has_more`. Unmatched tickers are reported in `unresolved_tickers`; they do not widen the search to all companies.

## Financial statements

### `describe_structured_financial_tables`

Inspect column names, types, and descriptions before writing a financial query. Pass a required `table_names` array containing one or more of:

| Table | Data |
| - | - |
| `us_companies` | Company details and identifiers. |
| `us_10q_filing` | Quarterly filing records. |
| `us_20f_filing` | Annual filing records for 10-K and 20-F forms. |
| `us_xbrl_income_statements` | Income statement facts. |
| `us_xbrl_balance_sheets` | Balance sheet facts. |
| `us_xbrl_cash_flow_statements` | Cash flow statement facts. |

### `run_structured_financial_query`

Run one read-only PostgreSQL query over the supported US tables to retrieve reported financials, compare companies, or calculate trends and ratios.

| Input | Description |
| - | - |
| `query` (required) | One read-only PostgreSQL query. Bind placeholders are unsupported. |
| `max_rows` | 1–1,000 rows, default 100. |

Returns rows and a `truncated` flag. Inspect columns with `describe_structured_financial_tables` first. Join XBRL facts through `filing_id` to `us_10q_filing.id` for quarterly facts or `us_20f_filing.id` for annual facts, then join filings to `us_companies` through `company_id`. Filter annual filings by `form_type` to distinguish 10-K and 20-F. Facts use `concept_local_name`, `report_start_date`, and `report_end_date`. Use `filter_companies` for ordinary company screening.

## Example questions

* "Find US semiconductor companies with market cap above USD 10 billion."
* "What did NVIDIA management say about data center demand in its latest call?"
* "Read the risk discussion in Apple's latest 10-K and cite the relevant passages."
* "Compare Microsoft's revenue and cash flow over the last three reported fiscal years."


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.