Designing Tool Schemas for Quant Agents

An LLM agent doesn't call a function the way normal code does — it reads a description of what the function does, what arguments it takes, and what it returns, and then decides whether and how to call it, purely from that description plus the conversation so far. If a "get historical price" tool's schema doesn't specify whether the date range is inclusive of the end date, or whether prices are adjusted for splits and dividends, the agent has no way to know, and it will guess — sometimes correctly, sometimes not, and inconsistently across calls. A tool schema is not documentation for a human reading the code; it's the entire interface the agent has to reason about that function, and an ambiguous schema produces an ambiguous — and therefore unreliable — agent.

What a good tool schema specifies

A tool schema (typically JSON Schema) needs, at minimum: a clear function name and description stating exactly what the tool does and, just as important, what it does not do; a parameter list with types, whether each is required or optional, and — critically for quant tools — units and conventions (is a rate 0.05 or 5? is a date range inclusive? are prices split-adjusted?); and a description of the return format, so the agent knows how to parse and use the result in its next step. Ambiguity in any of these tends to surface not as an error, but as a plausible, silently wrong call — the agent requests unadjusted prices when it meant adjusted, or interprets a rate parameter as a percentage when the function expects a decimal.

Worked example: a "get factor exposure" tool

Compare two schema descriptions for the same underlying function. Vague version: get_factor_exposure(ticker, factor) — "returns the exposure of a stock to a factor." Well-specified version: get_factor_exposure(ticker: str, factor: "value"|"momentum"|"quality"|"size", as_of_date: str, lookback_days: int = 252) — "Returns the stock's estimated beta to the given factor, computed via rolling OLS regression of daily returns over lookback_days trading days ending at as_of_date. Beta is unitless; a value of 1.0 means average exposure. Returns {beta: float, r_squared: float, n_obs: int} and raises an error if fewer than 60 observations are available." The vague version leaves the agent to guess which factors are even valid strings, what window is used, and whether the returned number is a beta, a percentile, or a z-score — three very different things that could all reasonably be called "exposure." The well-specified version removes every one of those guesses, and the n_obs field in the response even lets the agent itself check whether the estimate was based on enough data before trusting it in a downstream decision.

What this means in practice

Time spent tightening tool schemas is usually the highest-leverage debugging work on a quant agent, because most agent failures that look like "the model made a bad decision" are actually the model making a reasonable decision given an underspecified interface. Every quantity that could have more than one convention — units, sign, inclusivity of ranges, adjustment methodology — should be pinned down explicitly in the description, not left to be inferred, and errors from the tool itself (like too few observations) should be surfaced in the schema so the agent can react to them rather than silently trusting a low-quality result.