Skip to main content
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

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).
FamilyWhat they doExamplesCount
Direct toolsFirst-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_ohlcv13
Skill-backed toolsData-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

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

ToolDescriptionRequired args
session_contextOpen a traced research run and attach the user’s question. Always called first.prompt

​
Data & research

ToolDescriptionRequired args
market_get_ohlcvFetch OHLCV bars with a provenance envelope (points + quote).symbol, range
search_skillsProgressive discovery — find skills matching a natural-language query.query
describe_skillFetch the full manifest for a skill (input/output schema, provider, cost).skill_id
market_screenerScreen equities by technical/fundamental filters.filters
congress_tradesPull congressional trading disclosures.symbol or member
insider_transactionsPull Form 4 insider transactions.symbol
analyst_ratingsPull analyst ratings and price targets.symbol
fear_greed_indexFetch the CNN Fear & Greed index.—
options_flowPull unusual options activity.symbol
short_interestPull short interest and days-to-cover.symbol
The full list of 50+ skill-backed tools lives in the Skills Catalog. The table above is a representative sample — use search_skills to find the rest.

​
Strategy

ToolDescriptionRequired args
propose_strategyValidate a StrategySpec dict against the frozen contract, stamp tenant_id, and store an immutable versioned row.spec

​
Backtest

ToolDescriptionRequired args
backtest_runRun a deterministic backtest over a spec and date range. Returns run_id, equity curve, stats, and a risk attestation.spec, range

​
Run management

ToolDescriptionRequired args
run_skillCreate a durable run for a skill. Returns run_id.skill_id, input
get_runFetch the full run record — status, jobs, artifacts, events.run_id
subscribe_runPoll for new events since a cursor.run_id
cancel_runCancel a queued or running run with a reason.run_id

​
Approvals

ToolDescriptionRequired args
list_approvalsList pending approval requests for the tenant.—
decide_approvalApprove or deny a pending request. Human-only.approval_id, decision

​
Artifacts

ToolDescriptionRequired args
get_artifactFetch artifact metadata + download URI by artifact_id.artifact_id

​
Skills (execution)

Skill-backed tools are invoked through run_skill. See the Skills Catalog for the full list of available skills.

​
The canonical workflow

1

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.
2

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.
3

Propose a strategy

Call propose_strategy with a declarative StrategySpec. The service validates it against the frozen contract and stores an immutable versioned row.
4

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.
5

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.

Session tools

session_context — open a traced research run.

Data tools

market_get_ohlcv, search_skills, describe_skill — fetch data and discover skills.

Strategy tools

propose_strategy — validate and store a declarative spec.

Backtest tools

backtest_run — deterministic backtest with full metrics.

Run management

run_skill, get_run, subscribe_run, cancel_run — durable run lifecycle.

Approval tools

list_approvals, decide_approval — the human’s promotion workflow.

Artifact tools

get_artifact — fetch the 8-file backtest artifact bundle.