Ava Advisor

Portfolio Context

portfolio_context

Read-only

An LLM-ready snapshot of ONE of the user's OWN portfolios (owner-scoped) — analyze it directly. NO window → default: meta · summary · a lifetime(all-time) + recent(~12mo) block, EACH with performance (return/cagr/sharpe/sortino/calmar/drawdown/vol/win_rate) + attribution · positions · closed_positions (realized_pnl) · composition (point-in-time holdings) · allocation · concentration (HHI) · inferred_behavior · flags. portfolio_id from list_portfolios; 404 if not the user's.

TIME WINDOW — `from_`/`to` (ISO) or `window` (`7d|30d|90d|180d|1y|mtd|qtd|ytd`): REPLACES lifetime+
recent with ONE `window` block (that span's `performance` + `attribution` + `nav_trend`) and scopes
`composition` to match. So ANY period's return + drivers is answerable. `snapshots` = composition
granularity only (`year|quarter|month|week|day|off`).
🔴 MANDATORY for period questions: the default / `lifetime` / `recent` blocks DO NOT contain the
performance or attribution of an arbitrary period (e.g. Q1-2025, "H1 2024"). To answer ANY specific
period — or to COMPARE periods (Q1/25 vs Q1/26, 2023 vs 2025) — you MUST call this tool AGAIN with
`from_`/`to` (or `window`) for EACH period, then compare the returned `window` blocks. NEVER derive a
period's return/sharpe/drawdown/attribution from the default view — those numbers aren't in it; making
them up is a hard error. If you haven't fetched a period's window, say you need to fetch it, don't guess.

HOW TO ANALYZE (research-analyst framing — see avaadvisor://policy):
• Lead with the sharpest thing: a non-empty `flag`, or the biggest concentration / drawdown / tilt.
• "What drove the return / drawdown / strengths & weaknesses" (for the default OR a window) → read
  `attribution.contributors[]` (per-holding `pnl_contribution` + `pct_of_nav_change` + `held` window;
  reconciles to `nav_change` to the cent, INCLUDES since-sold names). Don't estimate it yourself.
• "What did I hold on date X / how did the book evolve" → `composition` (set `snapshots` + a window).
• ⚠️ TRUST THE EDGE NOTES, never fabricate: a window before the portfolio's `inception_date` returns
  `window.empty=true` + a note (or clamped) — say "the portfolio didn't exist then". If
  `composition.coarsened` is true, the step was widened to stay bounded — for finer, narrow the window.
• NEWS-AWARE: fuse `stock_impact` / `news_feed`/`search_news` on the holdings' `theme` paths for the
  WHY (⚠️ news only covers 2026+; portfolio history goes back to inception, further than news).
• Facts, not advice. Observe; do NOT tell them to buy/sell/rebalance/time — hand the judgment back.

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": {
      "portfolio_id": "<portfolio_id>"
    },
    "name": "portfolio_context"
  }
}

Input Schema

Name	Required	Description
`to`	No	Window end YYYY-MM-DD.
`from_`	No	Window start YYYY-MM-DD — re-scopes performance/attribution/composition together.
`window`	No	Re-scope perf+attribution+composition to a period: `7d`/…/`ytd`. Omit → lifetime + recent(12mo).
`snapshots`	No	Point-in-time composition cadence: `year\|quarter\|month\|week\|day\|off` (default quarter); auto-coarsens over long spans.
`portfolio_id`	Yes	The portfolio's id (call list_portfolios first if the user says 'my portfolio' without a number).

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 6, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only declare readOnlyHint=true, and the description goes well beyond that: ownership scoping with a 404 for other users' portfolios, window.empty=true plus a note before inception_date, composition.coarsened being widened to stay bounded, and that attribution reconciles to nav_change and includes since-sold names. These are exactly the edge cases an agent would otherwise mis-handle.

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?

Purpose and the mandatory-window rule are front-loaded, which is good, but the text is very long and repetitive, restating the don't-derive-the-period warning several times and embedding analyst-style framing and emoji emphasis. The content largely earns its place, but tightening would improve scanability without losing 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?

With five parameters, no output schema, and a rich nested return payload, the description fully documents the default block structure, what changes under a window, and the failure/edge behaviors. An agent has enough to call it correctly and interpret the response without guessing.

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 real meaning: window/from_/to REPLACE the lifetime+recent blocks with a single window block, and snapshots controls composition granularity only, not performance. That interaction between parameters is not conveyed by the schema; minor deduction for not specifying date-format precedence when both window and from_/to are supplied.

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?

The opening sentence states a specific resource and scope: an LLM-ready snapshot of ONE of the user's OWN portfolios, owner-scoped. It distinguishes itself from list_portfolios by noting portfolio_id comes from that sibling, and the enumerated payload keys make the returned resource concrete.

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?

Explicit routing rules are given: use list_portfolios for the id, call AGAIN with from_/to per period for period or comparison questions, use composition with snapshots for point-in-time holdings, and fuse news_feed/search_news for the 'why'. It also states what NOT to do (never derive period metrics from the default view, no buy/sell advice).

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.