# MCP compatibility

> The legacy MCP tool table served by GET /v1/mcp/tools and POST /v1/mcp/call, with each tool's arguments.

Page: https://docs.aggre.org/agents/mcp · Section: For agents · All pages: https://docs.aggre.org/llms.txt

Aggre serves a **compatibility interface** for clients written against the older Aggre MCP tool table. It is a plain HTTP API, not an MCP server process: your MCP client or agent framework calls it.

| Route | Purpose |
|---|---|
| `GET /v1/mcp/tools` | The frozen tool table: name, description, input schema and permission of each tool. Tools that are not served have `available: false`. |
| `POST /v1/mcp/call` | Call a tool: `{ "name": "<tool>", "arguments": { ... } }` answers `{ "name": "<tool>", "result": { ... } }`. |

Both need an API key like every other `/v1` route. `result` is the same JSON the native route returns as `data`, with the same additive fields.

## What is served {#served}

The table lists 17 tools. The **seven judgment and retrieval tools** are served by the Data Bank: `retrieve`, `retrieve_batch`, `search_judgments`, `get_judgment`, `lookup_judgment`, `search_in_judgment` and `judgment_outline`. The others are listed by `GET /v1/mcp/tools` with `available: false` and answer `501` unless a deployment forwards them to a legacy host. An unknown tool name is `400`. Use the [native routes](https://docs.aggre.org/api/data.md) for everything else: they are the supported interface.

## Errors are flat {#errors}

On `POST /v1/mcp/call`, errors keep the legacy flat shape `{ "error": "message" }`, **not** the structured envelope of the rest of the API, so existing tool clients keep working.

```bash
curl -s https://api.aggre.org/v1/mcp/call \
  -H "Authorization: Bearer $AGGRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"lookup_judgment","arguments":{"citation":"憲法法庭112年憲判字第8號判決"}}'
```

## Tool table {#tools}

The table is frozen: it changes only through a reviewed contract change.

| Tool | What it does | Permission |
|---|---|---|
| `list_datasets` | List datasets visible to the current API key. | `dataset_read` |
| `search_dataset` | Search records inside a dataset with query and limit guards. | `search_read` |
| `get_record` | Fetch a single record by ID with sensitive field masking, or by dataset_id (slug or id) + external_id at the dataset's current version (a 大法官解釋's full record: dataset_id taiwan-constitutional-interpretations, external_id | `dataset_read` |
| `get_dataset_schema` | Return a dataset schema and version metadata. | `dataset_read` |
| `export_sample` | Export a small governed sample from a dataset. | `export_write` |
| `export_dataset` | Page through an entire dataset's records (limit + offset), for building a local mirror rather than a sample. | `export_write` |
| `retrieve` | Semantic retrieval (RAG): two-stage recall (lexical, plus dense on the Taiwan statute corpora) + cross-encoder rerank. Search statutes only (corpus=laws), case law only (corpus=judgments), or both. English statutes: Sing | `search_read` |
| `retrieve_batch` | Run 1-3 independent semantic retrieval queries under one bounded request. Each query keeps its own recall, rerank order, results and diagnostics; failures are isolated. Optional caching is org-scoped and invalidated by c | `search_read` |
| `search_judgments` | Taiwan case law by the court's own reasoning: passages from 理由 and 主文 across the judgment corpus, grouped by judgment, each with a verbatim excerpt, its role (court_reasoning, mixed_facts_and_reasoning, holding) and offs | `search_read` |
| `get_judgment` | Read a judgment, or a 大法官解釋 (doc_id JYIN,…, with changed_by, supplemented_by, changes and standing), from the passage index in pages by doc_id (the JID search_judgments returns), with the parts it is divided into, the st | `search_read` |
| `lookup_judgment` | Find a judgment by its citation — 最高法院49年台上字第1730號, 臺灣高等法院112年度上字第123號, 憲法法庭112年憲判字第8號判決, a 大法官解釋 (釋字第380號, 司法院釋字第380號解釋, 大法官解釋第380號, 釋字第三八〇號), Chinese numerals or a JID (a 大法官解釋 match carries changed_by, supplemented_by | `search_read` |
| `search_in_judgment` | Find where in ONE judgment a question is answered: ranks the passages of the judgment doc_id names (15,000-100,000 characters, of which get_judgment shows 3,000 at a time) for a query, across every part of it -- party cl | `search_read` |
| `judgment_outline` | The map of one judgment by doc_id (for a 大法官解釋: its 解釋爭點 as issue, 解釋文 as holding, 理由書 as reasoning, and their numbered paragraphs): where 主文, the facts, each party's case (party_claim), what the court below held (lower_ | `search_read` |
| `get_politician_trades` | US Congress (Senate + House) STOCK Act trades, filterable by politician name, ticker, and chamber. | `search_read` |
| `get_investor_holdings` | A famous investor's latest 13F holdings (e.g. Buffett, Burry, Ackman, ARK), largest position first. | `search_read` |
| `get_insider_trades` | Famous corporate insiders' SEC Form 4 trades (e.g. Musk, Cook, Zuckerberg), filterable by person and ticker. | `search_read` |
| `who_traded` | Everyone on the watch-lists (politicians + insiders) who traded a given ticker. | `search_read` |

## Arguments {#arguments}

### list_datasets {#tool-list_datasets}

List datasets visible to the current API key.

| Argument | Type | Required | Description |
|---|---|---|---|
| `category` | `legal` \| `healthcare` \| `markets` | no | Canonical domain. legal = statutes/case law/contract templates; healthcare = drug labels, approvals, recalls, biotech company disclosure; markets = quotes, economic indicators, positions & trades. |
| `query` | string | no | Substring match against slug/name/description. |
| `tags` | array of string | no | Namespaced facets, ALL of which must match (AND). Vocabulary: jurisdiction:TW\|CN\|US\|SG\|global, lang:zh-Hant\|zh-Hans\|en, type:statute\|regulation\|case-law\|contract-template\|drug-label\|approval\|recall\|adverse-event\|filing\|filing-index\|filing-passage\|company-profile\|registry\|regulatory-filing\|sanction-list\|quote\|indicator\|holding\|trade, modality:fulltext\|structured, asset:crypto\|equity, derived:<parent slug> for materialised subsets, source:…, sector:…, and rag:retrievable for datasets that `retrieve` can semantically search. This list is the live vocabulary, not a closed set -- read the `facets` map in a response to see what actually survived your filter. Example: ["jurisdiction:TW","lang:zh-Hant","type:case-law"] |

### search_dataset {#tool-search_dataset}

Search records inside a dataset with query and limit guards.

| Argument | Type | Required | Description |
|---|---|---|---|
| `dataset_id` | string | yes | Dataset UUID |
| `limit` | integer, 1–50 | no |  |
| `query` | string | yes |  |

### get_record {#tool-get_record}

Fetch a single record by ID with sensitive field masking, or by dataset_id (slug or id) + external_id at the dataset's current version (a 大法官解釋's full record: dataset_id taiwan-constitutional-interpretations, external_id its doc_id).

| Argument | Type | Required | Description |
|---|---|---|---|
| `dataset_id` | string | no | With external_id instead of id: the dataset's slug or UUID, e.g. "taiwan-constitutional-interpretations". |
| `external_id` | string | no | With dataset_id: the record's external id at the dataset's current version, e.g. a doc_id "JYIN,84,釋字,380,19950526". |
| `id` | string | no | Record UUID |
| `record_id` | string | no | Record UUID alias |

### get_dataset_schema {#tool-get_dataset_schema}

Return a dataset schema and version metadata.

| Argument | Type | Required | Description |
|---|---|---|---|
| `dataset_id` | string | yes | Dataset UUID or slug (e.g. "fund-holdings") |
| `limit` | integer, 1–100 | no |  |

### export_sample {#tool-export_sample}

Export a small governed sample from a dataset.

| Argument | Type | Required | Description |
|---|---|---|---|
| `dataset_id` | string | yes | Dataset UUID or slug (e.g. "fund-holdings") |
| `limit` | integer, 1–100 | no |  |

### export_dataset {#tool-export_dataset}

Page through an entire dataset's records (limit + offset), for building a local mirror rather than a sample.

| Argument | Type | Required | Description |
|---|---|---|---|
| `dataset_id` | string | yes | Dataset UUID or slug (e.g. "china-national-laws") |
| `limit` | integer, 1–2000 | no | Records per page (default 500). |
| `offset` | integer, 0– | no | Row offset to resume from; feed the previous response's next_offset back here to page through the whole dataset, and stop when it comes back null. That is the only stop condition -- total_estimate is an hourly approximation and bounding the walk with it truncates the copy. |

### retrieve {#tool-retrieve}

Semantic retrieval (RAG): two-stage recall (lexical, plus dense on the Taiwan statute corpora) + cross-encoder rerank. Search statutes only (corpus=laws), case law only (corpus=judgments), or both. English statutes: Singapore's Acts (jurisdiction=SG), Canada's federal Acts (jurisdiction=CA) and Taiwan's laws and orders in English (jurisdiction=TW, language=en), one hit per section with law_name, article_no and heading. Japanese statutes (jurisdiction=JP, query in Japanese): one hit per article, article_no as e-Gov labels it (第709条), with the e-Gov credit in attribution. Also covers openFDA: drug labeling full text (corpus=drug-labels -- indications, dosage, warnings, adverse reactions) and recalls/safety actions (corpus=fda-safety). Returns ranked passages with citations for a natural-language query. A Taiwan judgment on the Judicial Yuan's takedown list carries takedown (labelled, not hidden).

| Argument | Type | Required | Description |
|---|---|---|---|
| `agency` | string or array | no | Only with corpus "rulings": search only these ministries' rulings. 勞動部, 經濟部, 法務部, 財政部, 個資會籌備處, 公平會, 金管會 (or an alias: 勞委會, MOL, MOEA, MOJ, MOF, 國發會, FTC, FSC); a list searches each. Absent, all of them. An unknown agency is an error that lists the ones held, not an empty result. |
| `article_no` | string | no | Exact article number, e.g. 184 or 184-1; also as written in a judgment or a statute (第184條之1, 一八四, 第一百八十四條之一). Requires law_name. For the English statute corpora also as written in English: "s 157", "section 5A", "Article 15-1", "Art. 3". For Japan (JP): 第709条, 709, 第3条の2, 3-2 or 附則第1条 (Arabic figures). |
| `as_of` | string, date | no | Return only statute article versions current on this date. Applied to lexical and dense candidate generation before top_k. Datasets without explicit article version windows fail closed with complete:false and as_of_unavailable. |
| `candidates` | integer, 10–32 | no | First-stage recall pool size before reranking. Overrides `depth`. Hard-capped at 32 (the reranker's max batch). |
| `corpus` | `laws` \| `judgments` \| `both` \| `medical` \| `medical-laws` \| `medical-judgments` \| `rulings` \| `drug-labels` \| `fda-safety` \| `sec-filings` \| `510k` \| `device-summaries` \| `device-classification` | no | Which body to search. "laws" = statutes/regulations only, "judgments" = case law only (default), "both" = laws+judgments merged and ranked together. "medical-laws"/"medical-judgments" are the medical slices of those two, and "medical" is both (TW: 醫療法 plus the judgments that applied it; CN and US resolve to regulation alone — US is 21/42/45 CFR). "rulings" = the ministries' administrative rulings (函釋), Taiwan only (ignores `jurisdiction`): 財政部 (the tax acts), 勞動部 (labor acts), 經濟部 (公司法, 商業登記法), 法務部 (legal affairs), 個資會籌備處 (個人資料保護法; the 國家發展委員會 before it), 公平會 (公平交易法) and 金管會 (banking, securities, insurance); `agency` narrows it to some of them. One hit per ruling with `title`, `case_number` (發文字號), `date` (發文日期) and `source_url`, and a `ruling` object: `agency` (發文機關), `doc_number`, `doc_date`, `subject` (主旨), `related_articles` (相關法條: law, article_no, citation; `related_articles_source` says whether the site filed them or they were read off the text), `status` (現行 / 停止適用 / 已廢止) with `status_date` and `status_note`. 財政部 hits also carry `law_name` (稅目) and `article_no` (Arabic, e.g. "14"). A ruling is an agency's reading, not law, and the licence requires citing the source. "drug-labels" = openFDA drug labeling (SPL) full text -- indications, dosage, contraindications, warnings, adverse reactions. "fda-safety" = openFDA recalls/enforcement reports + Complete Response Letters. "510k" (alias "device-summaries") = the narrative text of FDA 510(k) summary documents; "device-classification" = device classes and their regulation definitions. "sec-filings" = SEC EDGAR healthcare/biotech filing PASSAGES (10-K/20-F/S-1/8-K), chunked from Item 1 Business and Item 1A Risk Factors — drug pipelines, clinical programs, regulatory and IP risk, in the company's own words. Hits carry `form`, `section` and `source_url`. The FDA and SEC corpora are US-only and ignore `jurisdiction`. Corpora are separate datasets, so "laws" can never return case law, and neither FDA corpus can return legal text. |
| `dataset` | string | no | Explicit dataset slug; overrides corpus/jurisdiction/language. e.g. "taiwan-moj-laws-ch-law", "taiwan-judgments", "taiwan-moj-laws-en-law", "ca-law", "fda-drug-labels", "fda-safety" |
| `depth` | `fast` \| `standard` \| `thorough` | no | How hard to search, trading latency for recall+precision. "fast" = small pool, strict threshold, short reranked text (interactive paths). "standard" (default) is the balanced setting. "thorough" = biggest pool TEI accepts, looser threshold, longer reranked text, and double the stage-1 time budget — use when the answer matters more than the wait. The individual arguments below override whichever fields you set. |
| `explain` | boolean | no | Attach a `diagnostics` object describing how the answer was reached: the stage-1 probes actually run, per-corpus candidate counts and best lexical score for each probe, and the FULL reranked pool with an `admitted` flag saying which entries reached `top_k`. Use it when a passage you expected is missing from `results` -- it is the only way to tell "never recalled by stage 1" (fix the query, or the corpus has no such provision) from "recalled but out-ranked" (raise `top_k`, `candidates`, or `rerank_chars`). Off by default; the response is unchanged when absent. |
| `jurisdiction` | `TW` \| `CN` \| `US` \| `SG` \| `CA` \| `JP` | no | TW (default), CN, US, SG, CA, or JP. Combines with `corpus` (and `language`) to pick the datasets. SG is Singapore: its current Acts (corpus "laws", one hit per section); every SG hit carries the `attribution` its source requires. CA is Canada: the consolidated federal Acts (corpus "laws", one hit per section, Justice Laws). SG and CA are English: write the query in English. JP is Japan: the statutes in force (corpus "laws", one hit per article, from e-Gov), in Japanese: write the query in Japanese, in the statute's own words (e.g. 不法行為による損害賠償); every JP hit carries the e-Gov credit (`attribution`) its licence requires. US is meaningful only for the medical corpora, where it resolves to 21/42/45 CFR — there is no US case law or statute corpus here, and asking for one returns an explanatory error rather than silently handing you Taiwanese material; so does any other jurisdiction. Ignored entirely by the FDA and SEC corpora, which are US-only already. |
| `language` | `en` \| `zh` | no | Optional; omitted, every corpus is its jurisdiction's own language (TW and CN Chinese, SG and CA English). "en" with jurisdiction TW and corpus "laws" searches the Ministry of Justice's English translations of Taiwan's laws and orders (taiwan-moj-laws-en-law, taiwan-moj-orders-en-order) instead of the Chinese originals: write the query in English; hits carry the English act name in `law_name` and "Article N" in `article_no`. A language a jurisdiction is not held in is an error. |
| `law_name` | string | no | Exact act name; requires article_no. Returns the complete matching article with strategy=exact, without similarity ranking. Taiwanese acts in Chinese, by the name or a short one (勞基法 for 勞動基準法; 中華民國 may be left off; 台 is read as 臺). A query that is nothing but one article of a Taiwanese act (民法第184條, 民法184, 民法第一八四條, 勞基法第11條第5款) is looked up the same way, with matched_from_query: true in the answer, and searched as usual if the lookup finds nothing; for the English statute corpora (TW with language en, SG, CA) the English title, with or without its year ("Companies Act 1967" or "Companies Act"), or the act's code. For Japan (JP) the law's e-Gov title, e.g. 民法 or 会社法. |
| `pcode` | array of string | no | Search ONLY inside these acts, by MOJ pcode (e.g. ["G0380050"] for 票據法). Applied during first-stage recall, not to the results, so `top_k` still means `top_k` hits from inside these acts. Use it when you already know which statutes govern -- writing the act's NAME in `query` does not do this and never has: only article BODIES are matched, so the name contributes nothing to the score and, on the semantic arm, dilutes the query. Every hit carries the `pcode` to pass back here. Taiwanese statute corpora only (taiwan-moj-laws-ch-law, taiwan-moj-orders-ch-order, taiwan-medical-laws); anything else is an error rather than an empty result. |
| `query` | string | yes | Natural-language legal query, e.g. "公務員收賄罪的量刑" or "正当防卫的认定" |
| `rerank_chars` | integer, 64–1024 | no | How many characters of each candidate the cross-encoder reads. The single biggest latency lever (attention is O(n²) in length). Overrides `depth`. |
| `stage1_timeout_secs` | integer, 3–120 | no | Hard cap on first-stage retrieval per corpus. By default each corpus gets its own size-appropriate budget (small statutes vs 22M-row TW judgments) scaled by `depth`; set this to force one flat budget. |
| `threshold` | number, 0.05–0.9 | no | First-stage lexical similarity cutoff (pg_trgm word_similarity, 0-1). Lower = more permissive recall, more candidates for the reranker to sort out. Overrides `depth`. |
| `top_k` | integer, 1–30 | no | Number of passages to return (default 8) |

### retrieve_batch {#tool-retrieve_batch}

Run 1-3 independent semantic retrieval queries under one bounded request. Each query keeps its own recall, rerank order, results and diagnostics; failures are isolated. Optional caching is org-scoped and invalidated by corpus and reranker versions.

| Argument | Type | Required | Description |
|---|---|---|---|
| `agency` | string or array | no |  |
| `article_no` | string | no |  |
| `as_of` | string, date | no |  |
| `cache_control` | object | no |  |
| `candidates` | integer, 10–32 | no |  |
| `corpus` | `laws` \| `judgments` \| `both` \| `medical` \| `medical-laws` \| `medical-judgments` \| `rulings` \| `drug-labels` \| `fda-safety` \| `sec-filings` \| `510k` \| `device-summaries` \| `device-classification` | no |  |
| `dataset` | string | no |  |
| `depth` | `fast` \| `standard` \| `thorough` | no |  |
| `explain` | boolean | no |  |
| `jurisdiction` | `TW` \| `CN` \| `US` \| `SG` \| `CA` \| `JP` | no |  |
| `language` | `en` \| `zh` | no |  |
| `law_name` | string | no |  |
| `pcode` | array of string | no |  |
| `queries` | array of object | yes |  |
| `rerank_chars` | integer, 64–1024 | no |  |
| `stage1_timeout_secs` | integer, 3–120 | no |  |
| `threshold` | number, 0.05–0.9 | no |  |
| `top_k` | integer, 1–30 | no |  |

### search_judgments {#tool-search_judgments}

Taiwan case law by the court's own reasoning: passages from 理由 and 主文 across the judgment corpus, grouped by judgment, each with a verbatim excerpt, its role (court_reasoning, mixed_facts_and_reasoning, holding) and offsets into the full text. Each result also carries case_cause (案由, e.g. 損害賠償, read from the judgment's own record; absent when the record has none) and cited_articles (the statute articles that judgment's own reasoning cites, each with law, article_no and article, at most 30, with cited_articles_total when there are more; the top-level cited_articles is a different thing, the articles most cited across the batch). No 裁判要旨 (headnote) is returned: the Judicial Yuan feed this corpus is built from does not carry one. max_results is 1–20 (default 5). Write the question in Traditional Chinese; filters for court level (court_level: supreme, high, district, constitutional — decided by the court code in the JID; 憲法法庭 is constitutional), case type and decision date. corpus picks what is searched: judgments (the default; no 大法官解釋), interpretations (司法院大法官解釋 釋字第1–813號 only, case_type 釋字, with their 解釋爭點 as role issue, 解釋文 as holding and 理由書 as court_reasoning; opinions are not indexed), constitutional (the interpretations and 憲法法庭's judgments and rulings) or all. A 大法官解釋 result carries changed_by, supplemented_by and changes (from the taiwan-constitutional-interpretations record) and standing (changed, supplemented or none); absent means unknown. cites_article (「民法第184條」, 「勞基法第11條」, 「土地法第34條之1」; one or a list) keeps judgments whose reasoning cites that article. cites_judgment (「最高法院110年度台上字第1432號」 or a doc_id; one or a list) keeps judgments whose reasoning cites that judgment; without a query it lists them, highest court and newest first. One result per case: a case's judgments at other courts and its rulings are grouped, and case.status says where the one shown stands (final, affirmed, reversed, remanded). Administrative rulings (支付命令, 本票裁定, 補費) are not indexed. court_only searches only the court's own reasoning and 主文. Results carry cited_by_count (other cases' judgments citing it, as of cited_by_as_of; see cited_by_note) and order_by cited_by orders by it; lookup_judgment of a 字號 returns cited_by_citation even when no judgment of it is in the index. synonyms (default true) also covers the other spelling of a character (僱/雇, 臺/台, 占/佔) and an article number written any way; query_expansion says what it added. flags keeps the judgments the courts set apart (grand_chamber 大法庭裁定, supreme_reference and high_reference 具參考價值之裁判, former_precedent 原判例) and every result lists its flags; by the 最高法院 own account a 具參考價值 judgment is not its unified view unless it went through 大法庭 or 徵詢程序 (flags_note). A judgment on the Judicial Yuan's takedown list (Delete-Infor) carries takedown (deleted_on, still_published_on_judicial_api, note): labelled, not hidden.

| Argument | Type | Required | Description |
|---|---|---|---|
| `case_type` | array of `民事` \| `刑事` \| `行政` \| `家事` \| `懲戒` \| `其他` | no | Only these case types, written exactly as the Chinese label (民事, 刑事, 行政, 家事, 懲戒, 其他). A list matches any of them; a single string is read as a list of one. 大法官解釋 (case_type 釋字) are chosen with corpus, not here. |
| `cited_by_weight` | number, 0–1 | no | With order_by relevance_and_cited_by: the most the count can add to a result's relevance (relevance is 0 to 1 against the best of the pool). Not tuned against judged results. |
| `cites_article` | string or array | no | Keep judgments whose reasoning cites this article (all of them, when a list): write the act and the article, e.g. "民法第184條", "勞基法第11條", "土地法第34條之1". |
| `cites_judgment` | string or array | no | Keep judgments whose reasoning cites this judgment: a case number with its court ("最高法院110年度台上字第1432號") or a doc_id. With no query, lists the citing judgments, highest court and newest first. |
| `corpus` | `judgments` \| `interpretations` \| `constitutional` \| `all` | no | What is searched: judgments (default; no 大法官解釋), interpretations (司法院大法官解釋 釋字 only), constitutional (釋字 and 憲法法庭) or all. |
| `court_level` | array of `supreme` \| `high` \| `district` \| `constitutional` | no | Only these court levels, decided by the court code in the JID (constitutional: 憲法法庭 and 大法官解釋). A list matches any of them; a single string is read as a list of one. |
| `court_only` | boolean | no | Search only what the court itself wrote: 理由 (court_reasoning) and 主文 (holding), not a 事實及理由 that could not be divided into facts and reasoning (mixed_facts_and_reasoning), which may hold a party's argument. Measured, 24% of judgments (mostly 簡易判決) have no other reasoning than that, and are not found with this set. Default false; roles names passages more exactly. |
| `date_from` | string, date, pattern `^[0-9]{4}-?[0-9]{2}-?[0-9]{2}$` | no | Decision date, Gregorian calendar, written YYYY-MM-DD (YYYYMMDD is read too; a 民國 year is not). Inclusive: decided on or after this day. Either bound may be given alone. |
| `date_to` | string, date, pattern `^[0-9]{4}-?[0-9]{2}-?[0-9]{2}$` | no | Decision date, Gregorian calendar, written YYYY-MM-DD. Inclusive: decided on or before this day. |
| `depth` | `fast` \| `standard` \| `thorough` | no | fast: lexical order, no reranker, quickest. standard (default): the best 150 passages reranked, within about 10 s. thorough: 320 reranked, within about 25 s. When the reranker is unavailable or over its budget the answer goes out in lexical order and says so (reranked: false). |
| `excerpt_chars` | integer, 80–600 | no | Longest excerpt per passage (default 300). |
| `flags` | array of `grand_chamber` \| `supreme_reference` \| `high_reference` \| `former_precedent` | no | Keep only judgments the courts themselves set apart; one flag or a list (any of them). grand_chamber: 大法庭裁定 (最高法院 case word 台上大, 最高行政法院 大). supreme_reference: 最高法院「具有參考價值之裁判」; high_reference: 高等法院暨所屬法院具參考價值／足資討論之裁判; former_precedent: 原判例. A flag whose list is not loaded on this deployment is refused, not answered empty. Every result carries its flags (a list, empty when none) when the lookup is enabled; absent means unknown. flags_note says that, by the 最高法院 own account, a 具參考價值 judgment is not the court's unified view unless it went through 大法庭 or 徵詢程序. |
| `max_results` | integer, 1–20 | no | Cases to return, one result per case (default 5, at most 20); each carries up to three passages. |
| `order_by` | `relevance` \| `cited_by` \| `relevance_and_cited_by` | no | relevance (default): the order of the search. cited_by: gather the most relevant judgments (four times max_results, at least 20, at most 60, one per case), then order them by how many other judgments cite each (cited_by_count), most first, relevance breaking ties. relevance_and_cited_by: relevance plus cited_by_weight times the count (log-scaled against the most cited of the pool). Every result carries cited_by_count and cited_by_levels when the lookup is enabled; absent means unknown. Ordering by the count is refused when it is not enabled. |
| `query` | string | no | The legal question or the proposition a court would write, in Traditional Chinese, e.g. "相當於租金之不當得利 請求權時效" or "承租人請求出租人返還押租金". Required, except that cites_judgment alone (no query) lists the judgments citing it. |
| `roles` | array of `court_reasoning` \| `mixed_facts_and_reasoning` \| `mixed` \| `holding` \| `issue` | no | Passage roles to search (default the first four, and issue — a 大法官解釋's 解釋爭點 — when corpus is not judgments). |
| `synonyms` | boolean | no | Widen the question: statutory words for everyday ones (押金 → 押租金, 加班費 → 延長工作時間之工資); the other spelling of a character courts write both ways (僱/雇, 臺/台, 占/佔, 裡/裏, 啟/啓, 敘/敍, 鑑/鑒, 證/証, 污/汙, 溫/温); and an article number in any of its spellings (民法184, 民法第184條, 民法第一八四條 and 民法第一百八十四條 are one article, found by the articles each judgment cites). What was added is listed in query_expansion. Default true. |

### get_judgment {#tool-get_judgment}

Read a judgment, or a 大法官解釋 (doc_id JYIN,…, with changed_by, supplemented_by, changes and standing), from the passage index in pages by doc_id (the JID search_judgments returns), with the parts it is divided into, the statute articles it cites and the judgments it cites (cited_judgments; search_judgments with cites_judgment finds the judgments citing this one), and case_history: the judgments that reviewed it (upper), that it reviewed (lower), and its case's final judgment. Offsets are Unicode code points; a judgment has been read in full only when next_offset is null. A judgment on the Judicial Yuan's takedown list (Delete-Infor) carries takedown (deleted_on, still_published_on_judicial_api, note): labelled, not hidden.

| Argument | Type | Required | Description |
|---|---|---|---|
| `around` | integer, 0– | no | Start a quarter page before this code-point offset, e.g. a hit's excerpt_start. Not with offset. |
| `doc_id` | string | yes | The JID from search_judgments or lookup_judgment, e.g. "CHDV,98,重訴,24,20090714,1". |
| `max_chars` | integer, 200–20000 | no | Page length in characters (default 3000). |
| `offset` | integer, 0– | no | Code-point offset to start at; pass the previous page's next_offset. |

### lookup_judgment {#tool-lookup_judgment}

Find a judgment by its citation — 最高法院49年台上字第1730號, 臺灣高等法院112年度上字第123號, 憲法法庭112年憲判字第8號判決, a 大法官解釋 (釋字第380號, 司法院釋字第380號解釋, 大法官解釋第380號, 釋字第三八〇號), Chinese numerals or a JID (a 大法官解釋 match carries changed_by, supplemented_by, changes and standing) — to check that a cited case exists in the index before relying on it. The same 年度字號 can be a 民事 and a 刑事 case at one court: say which (…民事判決) or read ambiguous; when the named court has no such case, other_courts lists the courts that do. Each match has total_chars (its length) and, when a court is named, court_exact (臺灣高等法院臺中分院's citation also reaches 臺灣高等法院's own case under the same number, marked false and listed after the court's own). No match does not mean the judgment does not exist. A judgment on the Judicial Yuan's takedown list (Delete-Infor) carries takedown (deleted_on, still_published_on_judicial_api, note): labelled, not hidden.

| Argument | Type | Required | Description |
|---|---|---|---|
| `citation` | string | yes | A case citation or JID, e.g. "最高法院49年台上字第1730號", "憲法法庭112年憲判字第8號" or "釋字第380號". |
| `court` | string | no | Court to match when the citation names none. |

### search_in_judgment {#tool-search_in_judgment}

Find where in ONE judgment a question is answered: ranks the passages of the judgment doc_id names (15,000-100,000 characters, of which get_judgment shows 3,000 at a time) for a query, across every part of it -- party claims and appendices as well as the reasoning. Each passage has its role (holding, facts, mixed_facts_and_reasoning, court_reasoning, party_claim, attachment, tail_boilerplate, unlabelled; a 大法官解釋's issue, holding and court_reasoning are its 解釋爭點, 解釋文 and 理由書), certifiable_as_court, offsets and an excerpt; excerpt_start goes to get_judgment as around. Also returns the 主文 (disposition). A party_claim passage is a party's argument, not the court's view. Write the query in the judgment's words, Traditional Chinese. A judgment on the Judicial Yuan's takedown list carries takedown (labelled, not hidden).

| Argument | Type | Required | Description |
|---|---|---|---|
| `doc_id` | string | yes | The JID of the judgment to search inside, from search_judgments or lookup_judgment, e.g. "CHDV,98,重訴,24,20090714,1". |
| `excerpt_chars` | integer, 80–600 | no | Longest excerpt per passage (default 240). |
| `max_results` | integer, 1–10 | no | Passages to return (default 5). |
| `query` | string | yes | What to find in this judgment, in Traditional Chinese, in the judgment's own words: the issue, the party, the amount, e.g. "抵銷抗辯 債權不存在". |
| `roles` | array of `caption` \| `issue` \| `holding` \| `facts` \| `mixed_facts_and_reasoning` \| `mixed` \| `court_reasoning` \| `party_claim` \| `attachment` \| `tail_boilerplate` \| `unlabelled` | no | Only passages in these parts (default every part). |

### judgment_outline {#tool-judgment_outline}

The map of one judgment by doc_id (for a 大法官解釋: its 解釋爭點 as issue, 解釋文 as holding, 理由書 as reasoning, and their numbered paragraphs): where 主文, the facts, each party's case (party_claim), what the court below held (lower_court), the court's own assessment (court_view), the closing (conclusion), the signature and the first appendix begin, and its numbered headings (item), with code-point offsets get_judgment takes as offset. Cut from the judgment's own headings and numbering, not parsed: a judgment with few headings has a short outline. With a query, also returns the passages that answer it (as search_in_judgment). A judgment on the Judicial Yuan's takedown list carries takedown (labelled, not hidden).

| Argument | Type | Required | Description |
|---|---|---|---|
| `doc_id` | string | yes | The JID of the judgment, from search_judgments or lookup_judgment. |
| `excerpt_chars` | integer, 80–600 | no | Longest excerpt per passage (default 240). |
| `max_results` | integer, 1–5 | no | Passages to return with a query (default 3). |
| `query` | string | no | Optional: also return the passages of this judgment that answer it. |

### get_politician_trades {#tool-get_politician_trades}

US Congress (Senate + House) STOCK Act trades, filterable by politician name, ticker, and chamber.

| Argument | Type | Required | Description |
|---|---|---|---|
| `chamber` | `Senate` \| `House` | no |  |
| `limit` | integer, 1–200 | no |  |
| `politician` | string | no | Politician name substring, e.g. "Pelosi" |
| `ticker` | string | no | Stock ticker, exact, e.g. "NVDA" |

### get_investor_holdings {#tool-get_investor_holdings}

A famous investor's latest 13F holdings (e.g. Buffett, Burry, Ackman, ARK), largest position first.

| Argument | Type | Required | Description |
|---|---|---|---|
| `investor` | string | yes | Investor or fund name substring, e.g. "Buffett" or "ARK" |
| `limit` | integer, 1–500 | no |  |

### get_insider_trades {#tool-get_insider_trades}

Famous corporate insiders' SEC Form 4 trades (e.g. Musk, Cook, Zuckerberg), filterable by person and ticker.

| Argument | Type | Required | Description |
|---|---|---|---|
| `limit` | integer, 1–200 | no |  |
| `person` | string | no | Insider name substring, e.g. "Musk" |
| `ticker` | string | no | Issuer ticker, exact, e.g. "TSLA" |

### who_traded {#tool-who_traded}

Everyone on the watch-lists (politicians + insiders) who traded a given ticker.

| Argument | Type | Required | Description |
|---|---|---|---|
| `limit` | integer, 1–300 | no |  |
| `ticker` | string | yes | Stock ticker, exact, e.g. "AAPL" |