How to design read-only tools for a financial AI agent

Most conversations about agent safety in finance start with prompts: tell the model not to trade, tell it to be careful, tell it to ask before acting. Prompts are suggestions. The cheapest and most reliable safety property you can give a finance agent is architectural: the dangerous tools simply do not exist. An agent cannot place an order through a tool surface that only reads.

This post is about how we design that surface. It applies whether you are building on our tools or your own.

Read-only as an architecture decision, not a prompt instruction

A prompt that says “never execute trades” depends on the model following it, every time, under every phrasing of every request. A tool set with no execution path depends on nothing. That is the difference between a policy and a property. Our MCP server and API expose read tools only: signals, filings, news, prices. Anything that places orders or writes data stays out of the public surface entirely. If a capability is not there, no prompt injection, no confused chain of tool calls, and no creative user can reach it.

Small, typed surfaces beat one query-anything tool

It is tempting to expose a single powerful tool, a query_anything that takes free text and returns whatever the backend finds. Resist it. Six narrow tools with typed parameters are easier for a model to use correctly, easier for you to log and rate-limit, and much easier to reason about when something goes wrong. The core of our surface is a handful of narrow tools — list_signals, get_signal, search_entries, sec_current_report_items, sec_insider_trades, get_market_candles — within a set of roughly 50 read-only tools. Each does one thing, returns one shape, and fails in one predictable way.

Every result carries its source

A read-only tool that returns unattributed numbers still produces answers no one can check. So each result should carry a link back to where it came from: the signal to its reasoning and source trail, the insider trade to the filing behind it. That turns the agent’s output from an assertion into a claim with a receipt. We wrote about why this matters in why AI agents keep inventing market numbers; the short version is that a sourced answer can be audited and a hallucinated one cannot.

Filters beat free text

Give the model parameters, not a search box. list_signals filters by type, direction, strength, and asset. That means the model expresses what it wants in a form your system can validate, instead of a string your backend has to interpret. Structured parameters also make the tool call itself readable: when you review a transcript later, “signals, direction bullish, strength above 70, asset X” tells you what the agent asked. A free-text query tells you what it typed.

Failure shape matters

Models reason from what tools return, including when tools return nothing. An empty result should look like an empty result, a typed shape with zero rows, not an error, and not prose the model might misread as data. Errors should say what went wrong in a form the model can act on: bad parameter, rate limit, unknown asset. A tool that fails vaguely invites the model to fill the gap with a guess, which is the exact behavior the tool exists to prevent.

How this shapes the QuantConomy surface

The tools above run over the hosted MCP server at mcp.quantconomy.com/mcp and the same data is reachable over the REST API, with the same key, plan, and rate limits either way, so agent access cannot become a quiet backdoor around your API plan. Per-tool scopes are on our finalizing list for the beta, not shipped yet. And the honest caveat stands: read-only design removes a class of failure, not all of them. A model can still misread good data or answer the wrong question. Read-only means the blast radius of those mistakes is a wrong sentence, not a wrong trade.

Where to start

If you are building your own agent, start narrower than feels necessary. One or two read tools, typed parameters, sources on every result, empty results that look empty. Add capability only when the current loop is trustworthy. An agent can only misuse the capability you gave it, so give it less.