Agent skill

---
name: StockContext
description: >-
  Structured context for US-listed stocks and ETFs (NYSE/NASDAQ): symbol search,
  snapshot, valuation, fundamentals, earnings, dividends, technicals, price action,
  history, compare, SEC filings, SEC events, facts, and insider/Form 144 activity.
  Use over hosted MCP or REST when a task needs quote, performance, valuation,
  financial, technical, SEC, or insider data for a US ticker. Not for trading,
  options, real-time L2, or non-US equities.
---

# StockContext

## Use it for

US-listed stock and ETF context: resolve a company or fund name to a symbol, then
pull snapshot, valuation, fundamentals, earnings, dividends, technicals, price action,
price history, a 2-12 symbol compare, SEC filings (list, metadata, section text,
filing diff), SEC events, facts, or insider and Form 144 activity. Coverage is NYSE, NASDAQ, and their venues
(including NYSE ARCA and BATS/Cboe BZX): US-listed stocks and ETFs only.

## Don't use it for

Trading or order execution, exchange-grade real-time or L2/order-book data, options,
futures, crypto, FX, non-US local listings, analyst consensus or price targets,
earnings-call transcripts, news, or investment advice. Store-backed SEC families
like `facts` can be route-supported but not yet collected; branch on `/v2/coverage`
`available_now` and report payload reasons. Segments, ownership/13F/13D-G, and
governance are private beta, not default public-agent inputs.

## Setup

Prefer hosted MCP. Set `STOCKCONTEXT_API_KEY` first (create a key at
https://stockcontext.com/dashboard/keys), then add the server:

```json
{
  "mcpServers": {
    "StockContext": {
      "url": "https://api.stockcontext.com/mcp",
      "headers": { "X-API-Key": "$STOCKCONTEXT_API_KEY" }
    }
  }
}
```

Smoke-test: confirm the `stockcontext_*` tools loaded, then call
`stockcontext_snapshot({ "symbol": "AAPL" })`. A success returns `{ "data": ... }` with
`freshness` and `as_of`. MCP tool arguments use native JSON types: lists are arrays
(`["10-K","10-Q"]`), not comma-separated strings.

REST fallback (same key, every request carries the header):

```bash
curl -sS "https://api.stockcontext.com/v2/snapshot?symbol=AAPL" \
  -H "X-API-Key: $STOCKCONTEXT_API_KEY"
```

MCP is read-only and calls REST under the hood. When the two disagree, REST/OpenAPI is
the source of truth.

Self-hosting instead of hosted MCP? Run the server standalone with
`STOCKCONTEXT_API_KEY` and `STOCKCONTEXT_API_BASE_URL` set in the environment:
`python -m noxstock.mcp.server --stdio` for stdio, or
`python -m noxstock.mcp.server --streamable-http --host 127.0.0.1 --port 8001` for HTTP.

## Plans

A Free key calls search, coverage, snapshot, and valuation only; every other route
returns `PLAN_UPGRADE_REQUIRED`. Starter and Builder keys reach all public core routes and tools.
See https://stockcontext.com/docs/reference/plans-and-limits.

## Default call sequence

1. If the user names a company or fund, call search to resolve the symbol.
2. Call coverage before storing, batching, or deeply analyzing a symbol.
3. Call snapshot for most single-symbol questions.
4. Add only what the question needs: valuation, fundamentals, facts, events,
   compare (2-12 tickers), filings list -> filing -> filing section or diff for
   SEC text, insider for Form 4/Form 144 activity, technicals + price-action for
   trend and timing, history only for a time series.

## Output rules

- Answer first, then the few supporting facts, then freshness, then the calls you made.
- Parse the envelope: success is top-level `data`; failure is top-level `error` with
  `code`, `message`, and `retryable`. Retry only when `retryable` is true and honor
  `Retry-After`.
- Preserve every value as returned: units, signs, `_pct`, `_usd`, fiscal periods,
  accessions, filing dates, `as_of`, `freshness`, `market_status`, notices, and
  null/unavailable reasons. Never round away a sign or invent precision.
- Treat `freshness: "unsupported"` and `available: false` reasons as facts. Say "not
  available from StockContext" instead of guessing; do not retry these states.
- Summarize SEC risk/MD&A/business/press-release content only from the returned filing
  section text. Do not blend in news, consensus, the web, or memory.
- Report data; do not advise. No buy/sell/hold verdict, price target, or trade
  instruction. Keep the API key server-side, never in client code, logs, or prompts.

## Go deeper

- Agent recipes (prompt -> calls -> answer): https://stockcontext.com/docs/agents/recipes
- Choose the right endpoint: https://stockcontext.com/docs/guides/choose-endpoints
- Error codes and retry policy: https://stockcontext.com/docs/reference/error-codes
- Plans and limits (why a call returns PLAN_UPGRADE_REQUIRED): https://stockcontext.com/docs/reference/plans-and-limits
- Hosted MCP setup: https://stockcontext.com/docs/mcp/hosted
- API reference: https://stockcontext.com/docs/api-reference/overview