Skip to content
PredictefyPredictefy Docs
Get an API key

Build a market research agent

Copy page

The MCP server gives an agent thirteen read tools over the same data the REST API serves. 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:

Cap Applies to
100 rows every list tool
5,000 candles get_ohlcv
~50 KB response byte budget
15 s per-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 deliberately not in the default set

Section titled “Execution is deliberately not in the default set”

exec_quote, exec_prepare and exec_submit ship in the package but are absent from the default thirteen and require an explicitly configured trusted execution origin.

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.

Every tool in the default set is annotated readOnlyHint: true. A research agent should stay there.

Section titled “Related”