> ## 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.

# India MCP tools

> Reference for the nine stockinsights.ai India MCP tools: company research, filings, announcements, financials, shareholding, and results dates.

The India server at `https://api-in.stockinsights.ai/mcp` exposes these nine 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 company names or ticker mentions 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 tickers. Accepts names such as `Reliance Industries`, plain tickers such as `TCS`, and prefixed identifiers such as `NSE:INFY` or `BSE:500325`. |
| `limit_per_entity` | Matches per input: 1–10, default 5. |

Use the returned plain ticker in subsequent tools.

### `filter_companies`

Screen listed Indian companies and retrieve industry classifications and market snapshots, including market cap, share prices, PE ratio, and `as_of`.

Supply at least one screening criterion:

| Input | Description |
| - | - |
| `tickers` | Up to 50 plain tickers. |
| `marketcap_categories` | Any of `large`, `mid`, `small`, `micro`, or `nano`. |
| `industry_filters` | Up to 20 exact classification objects using `industry_macro`, `industry_sector`, `industry`, or `industry_basic`. Fields within an object combine with AND; objects combine with OR. |
| `marketcap` | Numeric filter in **INR crore**. |
| `current_price`, `high_52w`, `low_52w` | Numeric filters in **INR**. |
| `pe_ratio` | Numeric filter for price-to-earnings ratio. |
| `sort` | `field`: `company_name`, `ticker`, `marketcap`, `current_price`, `high_52w`, `low_52w`, or `pe_ratio`. `direction`: `asc` or `desc`. Defaults to market cap descending. |
| `limit`, `cursor` | 1–50 companies, default 20. Continue with `meta.next_cursor` using the same filters. |

Numeric filters accept `eq` alone or lower and upper bounds using `gt`, `gte`, `lt`, and `lte`. For example, `marketcap: { "gte": 1000, "lte": 10000 }` selects companies with market cap between INR 1,000 crore and INR 10,000 crore.

## 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`, `annual-report`, `investor-presentation`, or `quarterly-result`. |
| `filters.tickers` | Up to 100 plain tickers. Omit for a market-wide feed. |
| `filters.fiscal_years` | Years such as `FY25`, for annual reports only. |
| `filters.fiscal_quarters` | Quarters such as `FY25Q1`, for transcripts, presentations, and quarterly results. |
| `limit` | 1–50 filings, default 50. |

Use `search_filings` to find passages and `get_filing_content` to read a filing or retrieve its artifacts.

### `search_filings`

Search earnings transcripts, annual reports, and investor presentations. Returns matching passages with filing IDs and citation links.

| Input | Description |
| - | - |
| `search_method` (required) | `keyword` for exact terms, quoted phrases, OR, and exclusions; `semantic` for concepts, guidance, strategy, or management commentary. |
| `query` (required) | Search text, 1–500 characters. |
| `filters.tickers` | Up to 100 plain tickers. Omit to search all companies. |
| `filters.filing_criteria` | Up to three objects, one per filing type. Each requires `filing_type` and `time_scope`. |

For each criterion, set `time_scope.mode` to `latest`, `all`, or `periods`. With `periods`, use `fiscal_years` for annual reports or `fiscal_quarters` for transcripts and presentations. Omitting filters searches the latest filing of every supported type across all companies.

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

```json theme={null}
{
  "search_method": "semantic",
  "query": "management outlook on demand and deal wins",
  "filters": {
    "tickers": ["TCS"],
    "filing_criteria": [
      {
        "filing_type": "earnings-transcript",
        "time_scope": { "mode": "latest" }
      }
    ]
  }
}
```

### `get_filing_content`

Retrieve one filing using its ticker, type, and fiscal period.

| Input | Description |
| - | - |
| `ticker` (required) | One plain ticker. |
| `filing_type` (required) | `earnings-transcript`, `annual-report`, `investor-presentation`, or `quarterly-result`. |
| `time_scope` (required) | `{ "mode": "latest" }`, or `mode: "period"` with `fiscal_year` for annual reports or `fiscal_quarter` for other types. |
| `page_selection` | Select up to 10 pages using `mode: "range"` with `start_page` and `end_page`, or `mode: "pages"` with a `pages` array. Page numbers start at 1. |

* **Annual reports:** Require `page_selection`. Search first to identify relevant pages.
* **Transcripts and presentations:** Return full text when `page_selection` is omitted, or selected page text when supplied.
* **Quarterly results:** Return artifact URLs for extracted markdown and financial-statement files. Do not send `page_selection`.

## Corporate announcements

### `get_announcements`

Fetch summaries of corporate announcements and exchange disclosures, newest first. Each result includes the company, publication date, category, summary, and citation link.

| Input | Description |
| - | - |
| `filters.tickers` | Up to 50 plain tickers. Omit for all companies. |
| `filters.company_filters` | Company-universe filters using market-cap categories and industry classifications. Intersects with `tickers` when both are supplied. |
| `filters.categories` | Exact category names, such as `Contract Awards` or `Management Changes`. |
| `filters.time_scope` | `mode: "latest"` for the default recent window; `mode: "last"` with `last.value` (1–3,650) and `last.unit` (`days` or `months`); or `mode: "range"` with `range.from_date` and `range.to_date` in `YYYY-MM-DD` format. |
| `filters.sentiment` | Any of `positive`, `negative`, or `neutral`. |
| `filters.significance` | `true` for significant announcements only; `false` for non-significant only. |
| `limit` | 1–50 announcements, default 50. |

Omit `filters` for announcements across all companies. The date window defaults to the latest month.

## Financial statements and shareholding

### `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 |
| - | - |
| `in_companies` | Company details and identifiers. |
| `in_xbrl_income_statements` | Income statements. |
| `in_xbrl_balance_sheets` | Balance sheets. |
| `in_xbrl_cash_flow_statements` | Cash flow statements. |
| `in_xbrl_segment_revenues` | Segment revenue. |
| `in_shareholding_filings` | Shareholding filing records. |
| `in_shareholding_categories` | Ownership by shareholder category. |
| `in_shareholding_holders` | Named shareholders. |

### `run_structured_financial_query`

Run one read-only PostgreSQL query over the supported tables to retrieve financial statements, compare companies, calculate trends, or analyze shareholding.

| 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 companies to statements and shareholding filings through `company_id`; join shareholding categories and holders to filings through `shareholding_filing_id`. Use `filter_companies` for ordinary company screening.

## Results calendar

### `get_results_calendar`

Get upcoming quarterly results dates from the latest Indian results calendar.

| Input | Description |
| - | - |
| `ticker` | Optional comma-separated string of plain tickers, such as `TCS,INFY`. Omit for the calendar across all companies. |

## Example questions

* "Find mid-cap Indian companies with a PE ratio below 25."
* "What did TCS management say about demand in its latest earnings call?"
* "How has promoter shareholding in Reliance changed over recent quarters?"
* "When are TCS and Infosys expected to report quarterly results?"


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