> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doomberg.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Overview

> The full MCP tool catalog at a glance — 13 direct tools plus 50+ skill-backed tools, grouped by category.

Ithaca exposes **60+ MCP tools** that an AI agent can call during a research session. Tools fall into two families: **direct tools** (first-class verbs implemented in the Ithaca service) and **skill-backed tools** (data-fetching capabilities backed by the skills catalog). Every call is traced, tenant-scoped, and replayable from the web UI.

## Direct tools vs. skill-backed tools

<Callout type="info">
  Direct tools are the workflow verbs. Skill-backed tools are the data sources. The agent always starts with a direct tool (`session_context`) and ends with direct tools (`propose_strategy`, `backtest_run`).
</Callout>

| Family                 | What they do                                                                                                                                                 | Examples                                                                                                                                                                                                                 | Count |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **Direct tools**       | First-class workflow verbs implemented in the Ithaca service. They mutate state, create runs, or gate approvals.                                             | `session_context`, `propose_strategy`, `backtest_run`, `run_skill`, `get_run`, `subscribe_run`, `cancel_run`, `list_approvals`, `decide_approval`, `get_artifact`, `search_skills`, `describe_skill`, `market_get_ohlcv` | 13    |
| **Skill-backed tools** | Data-fetching capabilities backed by entries in the skills catalog. Each one resolves to a versioned skill manifest and runs through the durable run system. | `market_screener`, `congress_trades`, `insider_transactions`, `analyst_ratings`, `fear_greed_index`, `options_flow`, `short_interest`, ...                                                                               | 50+   |

### Why the split matters

* **Direct tools have a fixed, small schema.** They are the verbs the agent must use to drive the workflow. Their arguments never change between releases.
* **Skill-backed tools are discovered progressively.** The agent doesn't know all 50+ skill names up front — it uses `search_skills` to find relevant ones, then `describe_skill` to read the manifest, then `run_skill` to execute. This keeps the tool list small while letting the catalog grow without breaking older agents.
* **Both are traced identically.** The human sees every call, argument, and result in the web UI regardless of family.

## Progressive discovery with `search_skills`

<Callout type="warn">
  Agents should never hard-code skill names. The catalog grows over time, and skills can be deprecated or versioned. Always discover skills through `search_skills` → `describe_skill` → `run_skill`.
</Callout>

The agent follows a three-step discovery loop:

1. **`search_skills`** — pass a natural-language `query` (plus optional `asset_class` and `intent`) and get back a ranked list of matching skill IDs with one-line summaries.
2. **`describe_skill`** — pass a `skill_id` (and optional `version`) to fetch the full manifest: input schema, output schema, cost, latency profile, and provider.
3. **`run_skill`** — pass the `skill_id`, `input` dict, and `mode` to create a durable run. Poll with `get_run` or stream with `subscribe_run`.

This means a brand-new skill added to the catalog is immediately usable by any agent without a server upgrade — the agent discovers it at runtime.

## Tool catalog by category

### Session

| Tool              | Description                                                                     | Required args |
| ----------------- | ------------------------------------------------------------------------------- | ------------- |
| `session_context` | Open a traced research run and attach the user's question. Always called first. | `prompt`      |

### Data & research

| Tool                   | Description                                                                | Required args        |
| ---------------------- | -------------------------------------------------------------------------- | -------------------- |
| `market_get_ohlcv`     | Fetch OHLCV bars with a provenance envelope (points + quote).              | `symbol`, `range`    |
| `search_skills`        | Progressive discovery — find skills matching a natural-language query.     | `query`              |
| `describe_skill`       | Fetch the full manifest for a skill (input/output schema, provider, cost). | `skill_id`           |
| `market_screener`      | Screen equities by technical/fundamental filters.                          | `filters`            |
| `congress_trades`      | Pull congressional trading disclosures.                                    | `symbol` or `member` |
| `insider_transactions` | Pull Form 4 insider transactions.                                          | `symbol`             |
| `analyst_ratings`      | Pull analyst ratings and price targets.                                    | `symbol`             |
| `fear_greed_index`     | Fetch the CNN Fear & Greed index.                                          | —                    |
| `options_flow`         | Pull unusual options activity.                                             | `symbol`             |
| `short_interest`       | Pull short interest and days-to-cover.                                     | `symbol`             |

<Tip>
  The full list of 50+ skill-backed tools lives in the [Skills Catalog](/skills/overview). The table above is a representative sample — use `search_skills` to find the rest.
</Tip>

### Strategy

| Tool               | Description                                                                                                          | Required args |
| ------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------- |
| `propose_strategy` | Validate a `StrategySpec` dict against the frozen contract, stamp `tenant_id`, and store an immutable versioned row. | `spec`        |

### Backtest

| Tool           | Description                                                                                                             | Required args   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------- |
| `backtest_run` | Run a deterministic backtest over a spec and date range. Returns `run_id`, equity curve, stats, and a risk attestation. | `spec`, `range` |

### Run management

| Tool            | Description                                                  | Required args       |
| --------------- | ------------------------------------------------------------ | ------------------- |
| `run_skill`     | Create a durable run for a skill. Returns `run_id`.          | `skill_id`, `input` |
| `get_run`       | Fetch the full run record — status, jobs, artifacts, events. | `run_id`            |
| `subscribe_run` | Poll for new events since a cursor.                          | `run_id`            |
| `cancel_run`    | Cancel a queued or running run with a reason.                | `run_id`            |

### Approvals

| Tool              | Description                                        | Required args             |
| ----------------- | -------------------------------------------------- | ------------------------- |
| `list_approvals`  | List pending approval requests for the tenant.     | —                         |
| `decide_approval` | Approve or deny a pending request. **Human-only.** | `approval_id`, `decision` |

### Artifacts

| Tool           | Description                                              | Required args |
| -------------- | -------------------------------------------------------- | ------------- |
| `get_artifact` | Fetch artifact metadata + download URI by `artifact_id`. | `artifact_id` |

### Skills (execution)

Skill-backed tools are invoked through `run_skill`. See the [Skills Catalog](/skills/overview) for the full list of available skills.

## The canonical workflow

<Steps>
  <Step title="Open a session">
    Call `session_context` with the user's prompt. This opens a traced research run and attaches the question. Every subsequent call is scoped to this session.
  </Step>

  <Step title="Discover and run data skills">
    Call `search_skills` to find relevant data sources, `describe_skill` to read each manifest, then `run_skill` to fetch data. Poll `get_run` or stream `subscribe_run` for results.
  </Step>

  <Step title="Propose a strategy">
    Call `propose_strategy` with a declarative `StrategySpec`. The service validates it against the frozen contract and stores an immutable versioned row.
  </Step>

  <Step title="Backtest">
    Call `backtest_run` with the spec and a date range. The engine runs a deterministic backtest and returns metrics, an equity curve, and a risk attestation.
  </Step>

  <Step title="Request promotion (optional)">
    If the backtest looks good, the agent can request paper-trading promotion. A human approves or denies it from the web UI via `list_approvals` / `decide_approval`.
  </Step>
</Steps>

<Card title="Session tools" icon="play" href="/tools/session">
  `session_context` — open a traced research run.
</Card>

<Card title="Data tools" icon="database" href="/tools/data">
  `market_get_ohlcv`, `search_skills`, `describe_skill` — fetch data and discover skills.
</Card>

<Card title="Strategy tools" icon="clipboard-list" href="/tools/strategy">
  `propose_strategy` — validate and store a declarative spec.
</Card>

<Card title="Backtest tools" icon="chart-line" href="/tools/backtest">
  `backtest_run` — deterministic backtest with full metrics.
</Card>

<Card title="Run management" icon="gear" href="/tools/runs">
  `run_skill`, `get_run`, `subscribe_run`, `cancel_run` — durable run lifecycle.
</Card>

<Card title="Approval tools" icon="shield-check" href="/tools/approvals">
  `list_approvals`, `decide_approval` — the human's promotion workflow.
</Card>

<Card title="Artifact tools" icon="box-archive" href="/tools/artifacts">
  `get_artifact` — fetch the 8-file backtest artifact bundle.
</Card>