> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools
> Every MCP tool @hitheo/mcp exposes — schemas, examples, and the SDK/REST endpoint behind each one.
`@hitheo/mcp` exposes eight tools to your IDE agent. Each one wraps a method on [`@hitheo/sdk`](/sdk-reference/installation) and ultimately hits a single REST endpoint on `https://www.hitheo.ai/api/v1/*`. The schemas below are reproduced verbatim from `packages/mcp/src/tools.ts`, so what your IDE sees in its tool catalog is what's documented here.
Tools never see your API key — `@hitheo/mcp` loads it once at startup from `THEO_API_KEY` and signs the underlying HTTP request on the agent's behalf. The agent only sees the text/JSON the tool returns.
## Tool catalog
| Tool | Purpose | SDK | REST |
| ------------------------------------------- | --------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------- |
| [`theo_complete`](#theo_complete) | General-purpose orchestrated completion | [`theo.complete()`](/sdk-reference/completions) | [`POST /api/v1/completions`](/api-reference/completions/create) |
| [`theo_code`](#theo_code) | Code generation with long output budget | [`theo.code()`](/sdk-reference/completions) | [`POST /api/v1/code`](/api-reference/code/generate) |
| [`theo_research`](#theo_research) | Deep research with citations (async) | [`theo.research()`](/sdk-reference/completions) | [`POST /api/v1/research`](/api-reference/research/create) |
| [`theo_image`](#theo_image) | Image generation | [`theo.images()`](/sdk-reference/media) | [`POST /api/v1/images`](/api-reference/images/generate) |
| [`theo_document`](#theo_document) | Generate PDF / DOCX / PPTX / XLSX / CSV | [`theo.documents()`](/sdk-reference/media) | [`POST /api/v1/documents`](/api-reference/documents/generate) |
| [`theo_skill_list`](#theo_skill_list) | List installed or marketplace skills | [`theo.skills()`](/sdk-reference/skills) | [`GET /api/v1/skills`](/api-reference/skills/list) |
| [`theo_skill_install`](#theo_skill_install) | Install a skill from the marketplace | [`theo.installSkill()`](/sdk-reference/skills) | [`POST /api/v1/skills`](/api-reference/skills/install) |
| [`theo_status`](#theo_status) | Engine health + latency | [`theo.health()`](/sdk-reference/client) | [`GET /api/v1/health`](/api-reference/health/check) |
***
## `theo_complete`
Run an AI completion through Theo's orchestration engine. Theo automatically classifies intent, selects the best engine across 300+ AI models, injects domain skills, executes tools, and returns the response. Use this for any general AI task: writing, analysis, planning, Q\&A.
### Input schema
| Field | Type | Required | Description |
| ----------------- | ---------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | `string` | ✅ | The prompt or question to send to Theo. |
| `mode` | `"auto" \| "fast" \| "think" \| "code" \| "research" \| "roast"` | — | Execution mode. `auto` lets Theo classify. `fast` uses a lightweight model. `think` uses deep reasoning. `code` optimizes for code. Default: `auto`. |
| `skills` | `string[]` | — | Skill slugs to activate (e.g. `["deep-research", "content-writer"]`). |
| `conversation_id` | `string` | — | Continue an existing conversation by ID. |
When `theo.config.json` defines `persona`, `skills`, `defaultMode`, or `tools`, those values are merged into the request — see [Project Config](/mcp/project-config#merge-semantics).
### Example agent invocation
```text theme={null}
Use theo_complete to draft a release-note summary for the diff in HEAD~3..HEAD.
```
### Example response (truncated)
```text theme={null}
Here's a release-note summary for the last three commits:
- ...
---
Tools used: web_search (ok), summarize_diff (ok)
Model: Theo Reason | Mode: think | Cost: 3¢
```
### Notes
* Output includes a one-line tail with the resolved model, mode, and cost so the agent sees how the request was routed.
* Costs are reconciled after execution and reflect what your account was billed.
***
## `theo_code`
Generate code using Theo. Routes to the Theo Code engine for best-in-class code generation with an extended output budget. Returns generated code and any artifacts (full files, project scaffolds). Use this when the task is primarily about writing, generating, or scaffolding code.
### Input schema
| Field | Type | Required | Description |
| ----------- | -------- | -------- | ---------------------------------------------------------------- |
| `prompt` | `string` | ✅ | Describe the code you want generated. |
| `language` | `string` | — | Target programming language (e.g. `typescript`, `python`, `go`). |
| `framework` | `string` | — | Target framework (e.g. `nextjs`, `express`, `fastapi`, `react`). |
### Example agent invocation
```text theme={null}
Use theo_code to scaffold a FastAPI service with a /health route and a /chat
SSE route. language=python, framework=fastapi.
```
The tool returns the generated content plus an `Artifacts:` block with JSON describing any files created.
***
## `theo_research`
Run deep research on a topic. Theo plans 3–6 focused search queries, runs them in parallel, deduplicates sources, and synthesizes a structured report with citations. **This is an async operation** — the MCP server polls until the underlying job completes (default budget: 120 seconds at a 3-second interval) and returns the final report.
### Input schema
| Field | Type | Required | Description |
| -------- | ----------------------- | -------- | ----------------------------------------------------------------- |
| `prompt` | `string` | ✅ | The research question or topic. |
| `depth` | `"basic" \| "advanced"` | — | `basic` is faster; `advanced` is more thorough. Default: `basic`. |
### Example agent invocation
```text theme={null}
Use theo_research with depth="advanced" to compare PostgreSQL native partitioning
vs Citus for a write-heavy time-series workload.
```
### Failure handling
If the research job fails or times out, the tool returns a single text payload starting with `Research failed:` so the agent can decide whether to retry with a narrower prompt.
***
## `theo_image`
Generate images using Theo. Routes to the Theo Create engine with automatic provider fallback. Returns image URLs. Use for logos, illustrations, mockups, concept art, or any visual content.
### Input schema
| Field | Type | Required | Description |
| -------------- | --------------------------------------------- | -------- | -------------------------------------------------------------------- |
| `prompt` | `string` | ✅ | Describe the image to generate. |
| `style` | `string` | — | Visual style (e.g. `photorealistic`, `illustration`, `3d`, `pixel`). |
| `aspect_ratio` | `"1:1" \| "16:9" \| "9:16" \| "4:3" \| "3:4"` | — | Aspect ratio. Default: `1:1`. |
### Example response
```text theme={null}
Image 1: https://artifacts.hitheo.ai/img/.png [theo-vision]
Cost: 5¢
```
Each line corresponds to one image; if the request asked for multiple, you get one URL per image plus a final cost line.
***
## `theo_document`
Generate a formatted document. Theo creates the document and returns a download URL on `artifacts.hitheo.ai`. Use for reports, presentations, spreadsheets, and data exports.
### Input schema
| Field | Type | Required | Description |
| -------- | ---------------------------------------------- | -------- | ---------------------------------- |
| `prompt` | `string` | ✅ | Describe the document to generate. |
| `format` | `"pdf" \| "docx" \| "pptx" \| "xlsx" \| "csv"` | — | Output format. Default: `pdf`. |
### Example agent invocation
```text theme={null}
Use theo_document with format="pptx" to build a 7-slide pitch deck for an
AI-native EHR called SentryOS.
```
### Example response
```text theme={null}
Document: SentryOS Pitch Deck
Format: pptx
Download: https://artifacts.hitheo.ai/doc/.pptx
Cost: 3¢
```
***
## `theo_skill_list`
List available Theo skills. Skills are packages of domain knowledge and tools that extend Theo's capabilities (like apps for AI). Filter to either `installed` (active on this account) or `marketplace` (available to install).
### Input schema
| Field | Type | Required | Description |
| -------- | ------------------------------ | -------- | ------------------------------------------------------------------------ |
| `filter` | `"installed" \| "marketplace"` | — | Filter to installed skills or marketplace catalog. Default: all visible. |
The tool returns a pretty-printed JSON array of skill records (`id`, `slug`, `name`, `description`, `version`, …). Agents typically pair this with [`theo_skill_install`](#theo_skill_install).
***
## `theo_skill_install`
Install a skill from the Theo marketplace. Once installed, the skill's domain knowledge and tools are available on every completion (and inside every subsequent `theo_complete` MCP call).
### Input schema
| Field | Type | Required | Description |
| ---------- | -------- | -------- | ------------------------ |
| `skill_id` | `string` | ✅ | The skill ID to install. |
### Example response
```text theme={null}
Skill skill_a1b2c3 installed successfully.
```
***
## `theo_status`
Check Theo's health and engine availability. Returns engine status, latency, and infrastructure health. Use to verify the connection works or diagnose issues from inside the IDE.
### Input schema
No parameters.
### Example response
```text theme={null}
Status: healthy
Version: 2026-03-28
Engines:
theo-core: healthy
theo-vision: healthy
theo-search: healthy
```
If the tool returns anything other than `Status: healthy`, run [`theo verify`](/cli-reference/overview#commands) on the host to dig in.
***
## Errors
When any tool throws (network error, API error envelope, polling timeout), the MCP server formats it as:
```text theme={null}
Theo error:
```
The agent sees the text as a normal tool result, not a JSON-RPC error, so it can read and react instead of bailing. The full structured error is also visible in your MCP server logs if your IDE surfaces them.
See [Troubleshooting](/mcp/troubleshooting) for the most common failure modes.