# Tools

idx-mcp serves these tools. `ownership_sync` is listed only when the server
starts with `--allow-sync`. Results that come from a live provider are wrapped
as `{data, source, fetched_at, stale}`; failures return `{error, code,
message}` with `isError` set.

## `analyze_stock`

Analyze one IDX ticker: technical signals (trend, RSI, MACD, moving averages) and fundamental growth, valuation, and risk ratings. Analyses that fail are listed under `errors`; the call fails only if every analysis fails.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `kinds` | array of `technical` / `growth` / `valuation` / `risk` | no | Analyses to run (default: all). |
| `symbol` | string | yes | IDX ticker, e.g. "BBCA". |

## `compare_stocks`

Compare fundamental reports (growth, valuation, risk) across IDX tickers. Tickers that fail are listed under `failures`.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `symbols` | array of string | yes | IDX tickers, e.g. ["BBCA", "BBRI"]; the `.JK` suffix is optional. At most 20. |

## `get_company`

Company data for one IDX ticker: profile, financial statements, earnings, analyst sentiment, insights, and news. Sections that fail are listed under `errors`; the call fails only if every section fails.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `sections` | array of `profile` / `financials` / `earnings` / `sentiment` / `insights` / `news` | no | Sections to fetch (default: all). |
| `symbol` | string | yes | IDX ticker, e.g. "BBCA". |

## `get_investor_holdings`

Every IDX holding (above 1%) of one investor, matched by name.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `entity` | string | yes | Investor name or part of it, e.g. "DWIMURIA"; the closest match is used. |

## `get_ownership_changes`

Holder changes (new, exit, increase, decrease) between two KSEI release dates, optionally for one ticker.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | yes | Earlier release date, YYYY-MM-DD (see ownership_status). |
| `limit` | integer | no | Maximum rows returned (default 200, at most 2000); `total` reports the full count. |
| `ticker` | string | no | Only this ticker's changes. |
| `to` | string | yes | Later release date, YYYY-MM-DD. |

## `get_price_history`

OHLCV price history for one IDX ticker.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `interval` | `1d` / `1wk` / `1mo` | no | Candle size (default "1d"). |
| `period` | `1d` / `5d` / `1mo` / `3mo` / `6mo` / `1y` / `2y` / `5y` | no | Lookback window (default "3mo"). |
| `symbol` | string | yes | IDX ticker, e.g. "BBCA". |

## `get_quotes`

Latest quotes (price, change, volume, 52-week range, market cap) for one or more IDX tickers.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `symbols` | array of string | yes | IDX tickers, e.g. ["BBCA", "BBRI"]; the `.JK` suffix is optional. At most 20. |

## `get_shareholders`

Shareholders above 1% of an IDX ticker from the latest KSEI release, with concentration metrics (top1, top3, HHI, free float).

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `ticker` | string | yes | IDX ticker, e.g. "BBCA". |

## `ownership_status`

Ownership database status: whether it has data, and the imported KSEI release dates.

No inputs.

## `ownership_sync`

Download or refresh the KSEI ownership snapshot (several MB) into the local database.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `force` | boolean | no | Re-download even when the local snapshot is current. |

## `screen_stocks`

Run a stock screen (top/worst performers, high dividend, low P/E, 52-week highs/lows, high volume, large cap).

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | `top-performers` / `worst-performers` / `high-dividend` / `low-pe` / `52w-high` / `52w-low` / `high-volume` / `large-cap` | no | Screen to run (default "top-performers"). |
| `limit` | integer | no | Maximum results (default 50, at most 200). |
| `region` | `id` / `us` / `sg` / `hk` / `jp` | no | Market region (default "id"). |

## `search_investors`

Search investor names in the KSEI ownership database.

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | Maximum results (default 20, at most 100). |
| `query` | string | yes | Full-text query over investor names. |