> ## Documentation Index > Fetch the complete documentation index at: https://docs.askalchemist.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Tools > Complete reference for all six Alchemist MCP tools. The Alchemist MCP server exposes six tools. All are read-only. **Endpoint:** `https://api.askalchemist.com/mcp/`\ **Auth:** OAuth 2.0, or `Authorization: Bearer alch_YOUR_KEY` — see [Add to Agents](/agents/overview#mcp-endpoint)\ **Transport:** Streamable HTTP (MCP 2025) *** ## `search_insights` The primary research tool. Use this first for any financial question. **Why `search_insights` first?** Insights are embedded with HyDE — each insight stores both its text and a set of hypothetical questions it can answer. This makes keyword-adjacent queries work surprisingly well. It's faster and cheaper than a web search, and every result carries a verbatim source quote. ### Parameters | Name | Type | Required | Description | | ------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | `string` | Yes | Research query. One focused concept: a concise question or 3–8 keyword phrase. | | `source_name` | `string` | No | Partial match filter on the publishing organization (e.g. `"Federal Reserve"`, `"USDA"`, `"BLS"`). Use `list_filter_options` to see all valid values. | | `since` | `date` | No | Only return insights from documents published on or after this date (`YYYY-MM-DD`). | | `limit` | `integer` | No | Max results. Default `20`. | ### Query format | Pattern | Example | | ---------------- | --------------------------------------------------- | | Concise question | `"Did the March 2026 FOMC minutes signal a pause?"` | | Keyword phrase | `"Fed dot plot 2026 rate path"` | | Entity + metric | `"AAPL 2025 revenue guidance"` | | Theme + source | `"corn ending stocks USDA"` | Avoid: conversational wrappers (`"tell me about..."`), question padding (`"Can you explain..."`), multi-theme lists (`"Fed rates inflation energy corn"`). ### Response ```json theme={null} { "insights": [ { "insight_id": "ins_01jwx...", "title": "Fed median dot unchanged at 3.875% for end-2026", "insight": "The March 2026 SEP showed the median federal funds rate projection for year-end 2026 held at 3.875%, unchanged from December 2025.", "excerpts": [ "The median projection for the federal funds rate at the end of 2026 remained at 3.875 percent." ], "doc_id": "doc_01jww...", "doc_title": "FOMC SEP — March 2026", "source_url": "https://federalreserve.gov/monetarypolicy/files/...", "source_name": "Federal Reserve", "published_date": "2026-03-20", "score": 0.92 } ] } ``` *** ## `get_document` Retrieve a full document and all its extracted insights by `doc_id`. Use this for deep research after `search_insights` has surfaced a relevant document — it gives you the complete set of insights extracted from that document, not just the ones that matched your query. ### Parameters | Name | Type | Required | Description | | -------- | -------- | -------- | --------------------------------------------------------------- | | `doc_id` | `string` | Yes | Document ID from `search_insights` or `list_documents` results. | ### Response ```json theme={null} { "document": { "doc_id": "doc_01jww...", "document_url": "https://federalreserve.gov/...", "article_title": "FOMC Minutes — March 18–19, 2026", "summary": "The March 2026 FOMC minutes detail committee deliberations on the pace of rate adjustments...", "source_name": "Federal Reserve", "authors": [], "published_date": "2026-04-09", "extracted_at": "2026-04-09T14:23:00Z", "extraction_status": "complete" }, "insights": [ { "insight_id": "ins_01jwx...", "title": "...", "insight": "...", "excerpts": ["..."] } ] } ``` *** ## `list_documents` Browse available documents with optional filters. ### Parameters | Name | Type | Required | Description | | ------------- | --------- | -------- | -------------------------------------------------------------- | | `source_name` | `string` | No | Partial match on publishing organization name. | | `since` | `date` | No | Only documents published on or after this date (`YYYY-MM-DD`). | | `limit` | `integer` | No | Max results. Default `50`. | ### Response ```json theme={null} { "documents": [ { "doc_id": "doc_01jww...", "document_url": "https://...", "article_title": "FOMC Minutes — March 18–19, 2026", "summary": "...", "source_name": "Federal Reserve", "published_date": "2026-04-09", "extraction_status": "complete" } ] } ``` *** ## `list_filter_options` Return all valid `source_name` values currently in the database. Call this before passing a `source_name` filter to `search_insights` or `list_documents` — source names must match exactly (case-insensitive partial match). ### Parameters None. ### Response ```json theme={null} { "source_names": [ "Federal Reserve", "USDA", "Bureau of Labor Statistics", "Bureau of Economic Analysis", "U.S. Energy Information Administration", "SEC EDGAR" ] } ``` *** ## `deep_search` Agentic deep research in one call. Pass a full natural-language question and Alchemist's own agent runs the multi-step loop for you — semantic search, entity-graph traversal, and full-document reads — then returns a synthesized, cited answer. Use `deep_search` when you want a researched answer. Use `search_insights` when you want to drive the loop yourself or just need a quick lookup. Substantially slower and more expensive than `search_insights` — it runs many model rounds and multiple tool calls per request. Don't put it on a latency-sensitive path, and don't call it for lookups a single `search_insights` would answer. ### Parameters | Name | Type | Required | Description | | ------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `question` | `string` | Yes | A complete natural-language research question. Do **not** compress it into keywords — this is the opposite of `search_insights`'s query format. | | `effort` | `string` | No | Exploration budget. One of `flash`, `standard`, `deep`, `max`. Default `standard`. Unrecognized values fall back to `standard`. | | `source_name` | `string` | No | Partial match to restrict publishing organizations. | | `since` | `date` | No | Only use material published on or after this date (`YYYY-MM-DD`). | ### Effort tiers Each tier up costs proportionally more, in both rounds and tool calls. | Tier | Max rounds | Max tool calls | Use for | | ---------- | ---------- | -------------- | ----------------------------------------------------- | | `flash` | 3 | 3 | Fastest; minimal graph exploration | | `standard` | 10 | 8 | Default — most questions | | `deep` | 16 | 12 | Multi-entity questions needing real traversal | | `max` | 24 | 20 | Genuine multi-hop graph walks across several entities | ### Example ```json theme={null} { "question": "How exposed is TSMC to a Taiwan strait disruption, and which suppliers are single points of failure?", "effort": "max" } ``` ### Response ```json theme={null} { "answer": "TSMC's exposure concentrates in two places...", "citations": [ { "doc_id": "doc_01jww...", "doc_title": "TSMC 2025 Annual Report", "source_url": "https://...", "source_name": "TSMC", "published_date": "2026-02-11", "insights": [ { "insight_id": "ins_01jwx...", "insight": "...", "excerpts": ["..."], "score": 0.88 } ] } ], "run_id": "..." } ``` `run_id` identifies the persisted run, including its full tool trajectory. If the loop fails before producing an answer, the response carries an additional `error` field with `answer` set to `""` and `citations` empty. *** ## `search_web` Live web search via Parallel.ai. **Fallback only** — use after `search_insights` returns zero or only tangentially-relevant results. `search_insights` is always preferred: faster, no per-call variable cost, and every result has citation provenance. ### Parameters | Name | Type | Required | Description | | ---------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | `objective` | `string` | Yes | Self-contained sentence describing the research goal. Must name the key entity or topic. | | `search_queries` | `string[]` | Yes | 2–3 diverse keyword queries (3–6 words each). Vary entities, synonyms, and angles. Never use full sentences or `site:` operators. | ### Example ```json theme={null} { "objective": "Find the latest consensus estimate for US core CPI in June 2026.", "search_queries": [ "US core CPI June 2026 estimate", "CPI consensus forecast June 2026", "inflation expectations June 2026 Bloomberg" ] } ``` ### Response ```json theme={null} { "search_id": "ws_01abc...", "results": [ { "url": "https://...", "title": "...", "publish_date": "2026-06-10", "excerpts": ["..."] } ] } ```