> ## Documentation index
> Fetch the complete documentation index at: https://docs.predictefy.com/llms.txt
> Use it to discover every available page before exploring further.

# Build a market research agent

> Chain the MCP read tools into a research loop, and design around the caps rather than into them.

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](/guides/mcp/) covers configuration. This page is the workflow.

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

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

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

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](/guides/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

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

## Related

- [MCP server](/guides/mcp/) — configuration, the full tool list, guardrails
- [Alert on scored trades](/guides/cookbook/smart-money-alert/) — the same data over REST
- [Capability-honest data](/guides/honest-data/) — what the honesty fields mean