Build an equity agent

​

The tool-selection policy

​

Tool functions

import os
import httpx

BASE = "https://api.stockcontext.com"
KEY = os.environ["STOCKCONTEXT_API_KEY"]


async def tool(name: str, **body) -> dict:
    """One agent tool per API tool. Returns parsed JSON."""
    async with httpx.AsyncClient(timeout=15) as client:
        res = await client.post(
            f"{BASE}/v1/tools/{name}",
            json=body,
            headers={"X-API-Key": KEY},
        )
    res.raise_for_status()
    return res.json()


# Expose these to the model:
async def stock_search(q: str) -> dict:
    return await tool("stock_search", q=q)

async def stock_overview(symbol: str) -> dict:
    return await tool("stock_overview", symbol=symbol)

const BASE = "https://api.stockcontext.com";
const KEY = process.env.STOCKCONTEXT_API_KEY!;

async function tool(name: string, body: Record<string, unknown>) {
  const res = await fetch(`${BASE}/v1/tools/${name}`, {
    method: "POST",
    headers: { "X-API-Key": KEY, "Content-Type": "application/json" },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(15_000),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

// Expose these to the model:
export const stockSearch = (query: string) => tool("stock_search", { query });
export const stockOverview = (symbol: string) => tool("stock_overview", { symbol });

​

A worked trace

{
  "data": {
    "matches": [
      { "ticker": "AAPL", "coverage": { "financials": true, "prices": true },
        "entity": { "cik": "0000320193", "name": "Apple Inc.", "shape": "operating_company" } }
    ]
  },
  "meta": { "schema_version": "2" }
}

{
  "data": {
    "growth": {
      "revenue": { "yoy_pct": 6.43 },
      "net_income": { "yoy_pct": 19.5 }
    },
    "valuation": {
      "price_to_earnings": 39.46,
      "fcf_yield_pct": { "value": 2.27, "basis": "FY2025_annual" }
    }
  },
  "meta": { "schema_version": "2", "as_of": { "sec": "2026-06-26", "market": "2026-07-02" } }
}

Apple grew revenue about 6.4% and net income about 19.5% year over year, and it trades at a trailing P/E of roughly 39.5 with a free-cash-flow yield near 2.3%. The growth figures come from SEC-filed financials (as_of.sec 2026-06-26). The P/E and FCF yield are computed_from_prices — a fundamentals input times a market close on 2026-07-01 — so they move with the price, not the filings. Calls used: stock_search, stock_overview. This is context, not advice.

​

Where agents go wrong

• Reading a refusal as a value. A field with unavailable has no value. Never substitute 0 or null; report the token (and look it up in the refusal_tokens catalog if needed).
• Parsing magnitudes as floats. Exact values are decimal strings — use a decimal type so precision survives.
• Blending the two clocks. A computed_from_prices multiple mixes an SEC-filed input with a market close. Do not present it as “the filing says,” and cite the price date.
• Treating 13F as total ownership. stock_ownership is a tracked subset with exhaustive: false. Say “among tracked managers.”
• Retrying non-retryable failures. invalid_api_key (401) and a 422 validation error do not change on retry — fix the cause. See Errors and retries.