Ava Advisor

Stock Impact

stock_impact

Read-only

How news moved a specific company/asset (incl commodities like GOLD.COMM) — per-article impact (direction + aspect + why), most recent first. Near-duplicate stories are MERGED by default (each row = one story + dup_count); collapse=false for the raw feed. limit = how many (default 20, max 50). Ordered by how hard each story hits this entity (relevance, 1.0 = directly about it; a market wrap that touches it ranks lower), then recency; companies_in_story says when it is one of several — heavily-covered assets have HUNDREDS, so keep it small + narrow. TIME-SCOPE with from_/to (ISO) or window ('90d','qtd','1y'); to COMPARE periods, call once per period. ⚠️ News starts 2026-01-01 — older ranges return nothing (no coverage, not 'no news'; price/volatility history goes back decades). 🔵 BONDS/RATES: a specific tenor/rate (US-2Y.GB, SOFR.MM) with no news of its own returns the country's benchmark-10Y macro news tagged scope:'curve_macro' + macro_source — narrate those as curve-wide central-bank context, not tenor-specific. 📏 MAGNITUDE: for a listed, priced asset each story has price_move = close-to-close % of the session it landed in (day_pct) and of the next one (next_day_pct) — the market's reaction next to the direction. It is the WHOLE day's move (other news counts too), not the story's isolated effect; say so. End-of-day prices: a story from today has no session close yet.

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_impact"
  }
}

Input Schema

Name	Required	Description
`to`	No	Upper time bound, ISO date `YYYY-MM-DD`.
`from_`	No	Lower time bound, ISO date `YYYY-MM-DD`. ⚠️ Ava Advisor NEWS coverage starts 2026-01-01 (nothing before).
`limit`	No	Max rows (default 20, hard cap 50). Keep SMALL + narrow the scope; page/refine rather than dump — heavily-covered assets have hundreds of articles.
`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).
`window`	No	News-recency window: `7d`/`30d`/`90d`/`180d`/`1y` or `mtd`/`qtd`/`ytd`. Omit → a sensible default. (Price history is unaffected — this only scopes the NEWS lens.)
`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).
`collapse`	No	Merge near-duplicate stories (same article from many outlets) into one row + `dup_count`. Default ON; pass `false` for the raw un-deduped feed.
`direction`	No	Filter by impact direction: `pos` \| `neg` \| `ambiguous`. Omit → all.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 6, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only carry readOnlyHint, and the description adds far more: dedup/merge behavior with `dup_count`, ranking by relevance then recency, the hard news-coverage start date of 2026-01-01 (with the explicit warning that empty results mean no coverage, not no news), the bond/rate fallback to country benchmark 10Y news tagged `scope:'curve_macro'`, and the fact that `price_move` is the whole session's move rather than the story's isolated effect. It also discloses practical limits (hundreds of articles for heavily covered assets, no session close yet for today's stories).

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

Conciseness4/5

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

Front-loaded: the first sentence defines the tool, and the rest is chunked by concern (dedup, ordering, time scope, coverage floor, bonds, magnitude). It is long and repeats a couple of schema facts (limit default/max, collapse default), but nearly every sentence carries non-obvious information.

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?

For a 9-parameter tool with no output schema, the description names the return fields an agent must narrate (`dup_count`, `price_move`/`day_pct`/`next_day_pct`, `relevance`, `companies_in_story`, `scope`, `macro_source`) and warns about the two big failure modes (pre-2026 ranges, tenor-specific bond queries). There is no meaningful gap left for a caller.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: what `collapse` actually changes in the rows, that ordering by relevance means limit truncates the weakest stories first, and how `from_`/`to`/`window` interact with the 2026-01-01 news floor. Most of the remaining parameter detail (ticker resolution, country disambiguation) is already in the schema.

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?

Opens with a concrete verb+resource: 'How news moved a specific company/asset', and pins down the return shape (per-article direction + aspect + why, most recent first). This is functionally distinct from the sibling feed tools (news_feed, search_news) because it is entity-scoped and ranked by impact on that entity, and it states that ordering explicitly.

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

Usage Guidelines4/5

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

Gives usable operational guidance: keep `limit` small, narrow the time scope, call once per period to compare periods, set `collapse=false` for raw feed. It never names a sibling tool or says 'use X instead of stock_impact', so the when-not-to-use case is left implicit.

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.