Skip to content
PredictefyPredictefy Docs
SupportDashboard

GuidesCookbook

Build a market research agent

Copy page

The MCP server gives an agent forty-eight default tools over the same data the REST API serves — thirty-nine read, intelligence, and platform tools plus nine paper tools — alongside ten execution and collateral tools that stay off until you opt in. This recipe is the chain that answers a research question, and the caps that shape how you write it.

MCP server covers configuration. This page is the workflow.

The chain

Section titled “The chain”

A research question — “what is the market saying about the January rate decision, and who is trading it?” — resolves through four steps:

  1. search_markets — text search on one venue, or all venues when venue is omitted. Omitting it is usually right for research: you want the question wherever it trades.
  2. get_market — the full record for a candidate, including its outcomes. You need an outcome before you can ask for depth or history.
  3. get_orderbook and get_ohlcv — current depth and price history for that outcome.
  4. get_market_traders, get_market_holders, get_smart_money — who is on the other side.

list_venues is free in the sense that matters: it makes no upstream call. Use it to ground the agent in what exists rather than letting it guess venue names.

Design around the caps

Section titled “Design around the caps”

Every cap is enforced server-side at the wire, whatever the model asks for. An agent written as if they do not exist will silently work with partial data:

CapApplies to
100 rowsevery list tool
5,000 candlesget_ohlcv
~50 KBresponse byte budget
15 sper-request timeout

Truncation is never silent: an over-budget payload comes back with "truncated": true and a note. Have the agent check that flag and narrow its query rather than reasoning over a truncated set as though it were complete.

The practical consequence: prefer several narrow calls to one broad one. A get_ohlcv over six months at 1m will hit the candle cap; the same request at 1h will not.

What the tools will not do

Section titled “What the tools will not do”
  • Unknown venues are rejected before any upstream call, and the error carries the full valid venue list — so a wrong venue name costs nothing and self-corrects.
  • Unsupported venue/verb combinations fail honestly. The five trader tools use the capability-qualified Trader Intelligence routes; where a venue does not expose a verb, they say so rather than returning invented empty data. Design the prompt so the agent reports the gap instead of substituting another venue.
  • The API key is redacted from every error path, so an agent that surfaces raw errors to a user cannot leak it.

Reading results honestly

Section titled “Reading results honestly”

Two properties belong in the agent’s system prompt, because a model will otherwise smooth over both:

  • Scores are informational, not advice. Trader Intelligence output ranks what already happened. It is not a recommendation, and an agent should not present it as one.
  • Some venues serve reconstructed books. Those are faithful as price and are not executable depth. An agent comparing “liquidity” across venues without distinguishing them is comparing two different things — see Capability-honest data.

Have the agent carry asOf through to its answer. “62¢ as of 14:22Z” is a claim a user can check; “62¢” is not.

Execution is a separate, removable surface

Section titled “Execution is a separate, removable surface”

exec_quote, exec_prepare and exec_submit are not among the forty-eight default tools — they belong to the ten execution and collateral tools, which are off by default; set MCP_ENABLE_TRADE=true or 1 to enable them against the canonical isolated execution origin. Unset or MCP_ENABLE_TRADE=false removes them entirely.

Even armed, the split holds: exec_quote is read-only, exec_prepare builds an unsigned artifact and never signs, and exec_submit relays a client-signed artifact and defaults to dry-run unless confirm is exactly true. No tool both builds and submits, and no signing endpoint exists at all.

The enabled execution set is not wholly read-only: exec_prepare and exec_submit carry readOnlyHint: false, and exec_submit is also marked destructive. A research-only agent should set MCP_ENABLE_TRADE=false so the ten execution and collateral tools are not registered.

Section titled “Related”