> ## 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. `"SEC"`, `"NOAA Weather Products"`, `"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 | `"What did Freeport say about copper production guidance?"` |
| Keyword phrase | `"Fed dot plot 2026 rate path"` |
| Entity + metric | `"AAPL 2025 revenue guidance"` |
| Theme + source | `"copper production guidance SEC"` |

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": "Grasberg Block Cave ramp-up delayed by ore loading modifications",
      "insight": "PTFI commenced phased ramp-up of Grasberg Block Cave Production Blocks 2 and 3 in March 2026 but encountered a significant increase in wet drawpoints, limiting near-term production to approximately 60% of capacity. 2026 sales estimates were reduced from 3.4 billion to 3.1 billion pounds of copper.",
      "excerpts": [
        "During initial ramp-up activities in Production Blocks 2 and 3, PTFI encountered changes in operating conditions at the Grasberg Block Cave underground mine, resulting in a significant increase in the ratio of wet drawpoints."
      ],
      "doc_id": "doc_01jww...",
      "doc_title": "Freeport Reports First-Quarter 2026 Results",
      "source_url": "https://www.sec.gov/Archives/edgar/data/831259/000083125926000021/a1q2026exhibit991.htm",
      "source_name": "SEC",
      "published_date": "2026-04-23",
      "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://www.sec.gov/Archives/edgar/data/831259/000083125926000021/a1q2026exhibit991.htm",
    "article_title": "Freeport Reports First-Quarter 2026 Results",
    "summary": "Freeport reported Q1 2026 net income of $881 million, driven by higher copper and gold prices...",
    "source_name": "SEC",
    "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": "Freeport Reports First-Quarter 2026 Results",
      "summary": "...",
      "source_name": "SEC",
      "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": [
    "SEC",
    "NOAA Weather Products",
    "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.

<Warning>
  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.
</Warning>

### 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 concentrated is NVIDIA's manufacturing supply chain, and which partners are single points of failure?",
  "effort": "max"
}
```

### Response

```json theme={null}
{
  "answer": "NVIDIA's manufacturing concentration sits in two places...",
  "citations": [
    {
      "doc_id": "doc_01jww...",
      "doc_title": "NVIDIA Corporation Annual Report on Form 10-K",
      "source_url": "https://www.sec.gov/Archives/edgar/data/1045810/...",
      "source_name": "SEC",
      "published_date": "2026-02-26",
      "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": ["..."]
    }
  ]
}
```


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