Ava Advisor

Stock Prices

stock_prices

Read-only

Price context for a tradable ticker (stock / ETF / index-ETF / forex / crypto / commodity), split & dividend-ADJUSTED — a DIGESTED read, NOT a raw bar series: windowed changes (1w/1mo/3mo/ytd/1y), 52-week range + drawdown_from_52w_high_pct (how far below the peak), realized vol + realized_vol_percentile_1y (is today's vol high vs its OWN year), trend vs SMA50/200, volume conviction (up_down_volume_ratio_1mo, rvol). *_read fields are ready plain-language labels — quote them, don't re-derive. Reach for this on "is it cheap/extended / how has it moved / why is it dropping" — the LEVEL that makes a news+options read actionable (or use pulse(kind='asset') to get price + news + options in one). to = as-of date (point-in-time, YYYY-MM-DD, features as of that day); from_ bounds history (narrowing below ~1y nulls the long windows). For a SECTOR/theme (not one ticker) use pulse(kind='theme'), not this. 🔵 BONDS/RATES: if metric_kind == "yield" (a .GB govt-bond yield like US-10Y.GB or a .MM rate like SOFR.MM) the stored value is a LEVEL, not a price — narrate each window's change_bps in BASIS POINTS, NOT change_pct (a % of a yield is sign-inverted + the wrong unit; e.g. US-10Y 1y = "+52 bps", not "+12%"). Bonds also carry per-window price_proxy_pct + top-level mod_duration = an L1 bond-PRICE estimate (≈ −ModDur×Δy) for "the bond fell ~4%" narration (label it an ESTIMATE; for an exact bond return point to a bond ETF like TLT/IEF). Volume fields (rvol, up_down_volume_ratio_1mo, …) are null for a yield — don't present volume conviction; and yield↑ ⇒ bond price↓.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "ticker": "<ticker>"
    },
    "name": "stock_prices"
  }
}

Input Schema

Name	Required	Description
`to`	No	As-of date `YYYY-MM-DD` — features computed as of that day (point-in-time). Omit → latest.
`from_`	No	Lower bound of price history `YYYY-MM-DD`. Narrowing below ~1y nulls the long windows. Price history goes back DECADES (unlike news, 2026+).
`ticker`	Yes	A Ava Advisor ticker OR a company/asset NAME — the SERVER resolves it (no lookup step). A COMPANY/proper NAME passes AS-IS in any language (茅台/トヨタ/삼성 resolve natively — never translate a name); a generic COMMODITY/SECTOR concept must be ENGLISH (黄金→'gold', 原油→'crude oil'). Pass the user's full request in `context` to disambiguate ('apple' company vs fruit); if still ambiguous you get a `needs_confirmation` with candidates — resolve from conversation or ask, then re-call. Exact tickers pass through (Ava Advisor suffixes: Korea .KO, Taiwan .TW, commodity .COMM, crypto .CC, FX .FOREX, bond .GB, rate .MM).
`context`	No	OPTIONAL but RECOMMENDED — paste the user's FULL request VERBATIM (any language: 'ขอราคาผลไม้ apple', 'compare Apple and Microsoft stock'). The server uses it to disambiguate which candidate each `ticker` entity means (the apple COMPANY vs the fruit COMMODITY; which Samsung). One context per call, shared by all tickers here.
`country`	No	OPTIONAL market disambiguator — pass ONLY when `ticker` is a plain NAME that collides across markets (the Thai vs Korean 'KBANK'); omit for a distinctive name or an exact ticker (an unneeded country silently 0-matches). A country NAME or ISO-2 code ('South Korea'/'KR'); the server normalizes, so pass the NAME when unsure — never GUESS a 2-letter code ('CH' = Switzerland, not China).

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 6, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint, and the description earns its credit well beyond that: the digest-vs-raw-bars distinction, the `*_read` fields being ready-to-quote labels, window-nulling when history is narrowed, `needs_confirmation` disambiguation flow, and the detailed bond/yield caveat (bps not pct, null volume fields, mod_duration price proxy as an ESTIMATE). It does not cover pagination or cost/latency, which keeps it off a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core digest definition, which is good, but the block is long and heavily compressed with all-caps emphasis and emoji markers, and the bond section is a dense wall of related-but-tangential caveats. Much of the ticker/context/country disambiguation guidance duplicates the schema and could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries the return-value burden and does it: it names the fields an agent will receive (windowed changes, drawdown_from_52w_high_pct, realized_vol_percentile_1y, up_down_volume_ratio_1mo, rvol) and explains which are null for yields. For a read-only digest tool with 5 params, an agent has enough to call it correctly and narrate the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3 even though the description restates the `to`/`from_` semantics (as-of point-in-time, narrowing below ~1y nulls long windows) that the schema already documents. The genuinely additive parameter content is the ticker resolution guidance and the `metric_kind` == "yield" case, which explains a per-data-type behavior the schema does not expose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: price context for a tradable ticker, split/dividend-adjusted, explicitly "a DIGESTED read, NOT a raw bar series". This distinguishes it from price_series and stock_prices_batch by naming what it is not, and enumerates the digest contents (windowed changes, 52w range, drawdown, realized vol percentile, SMA trend, volume conviction).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit trigger phrases ("is it cheap/extended / how has it moved / why is it dropping") plus named alternatives with selection criteria: pulse(kind='asset') for price+news+options, pulse(kind='theme') for sectors/themes instead of a single ticker. When-not-to-use and prerequisites are both present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Ava Advisor tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.