Skip to main content
Glama

List My Portfolio Holdings

list_portfolio
Read-onlyIdempotent

List the user's stock portfolio holdings.

Returns each position (shares, average cost, current price, market value, profit/loss, weight) from brokerage-linked and manually entered trades, plus totals. Use this when the user asks what they own or how their positions are doing. Don't use it for a public ticker the user doesn't own (use stock_analysis).

Limits: requires sign-in. Prices are cached snapshots that can be up to 7 days old; positions without a price are labeled, never guessed. Users with no holdings yet see a demo portfolio, clearly labeled.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_portfolio"
  }
}

Input Schema

NameRequiredDescriptionDefault

No arguments

Output Schema

NameRequiredDescriptionDefault
is_emptyYes
demo_modeNo
positionsNo
total_pnlNo
total_costNo
total_valueNo
manual_countNo
sign_in_hintNoA sign-in or setup tip. Never a paid offer.
total_pnl_pctNo
brokerage_countNo
price_freshness_noteYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedOutput schema / $defs / Position / description
      Previous value: -"One holding in the caller's portfolio (manual entry OR\nPlaid-synced brokerage position). Merged view — matches the web\n/portfolio page shape.\n\n`price_source` documents where `current_price` came from:\n  - `broker_derived`: computed as `market_value / shares` where\n    `market_value` is Plaid-reported (fresh as of last brokerage\n    sync). Plaid doesn't send `current_price` directly — we\n    derive it, and this label says so honestly.\n  - `cached_snapshot`: read from stock_snapshot_cache (up to\n    7 days old; cache-refresh worker keeps it warm hourly).\n  - `cache_miss`: no price available; `current_price` is None\n    and `market_value` falls back to shares × avg_cost so\n    totals still make sense.\n  - `demo_snapshot`: BUG-57 (2026-08-25) — position belongs to\n    the shared demo portfolio (signed-in-empty tenant funneled\n    to anon pool) and price came from the reference-price map\n    baked into `_DEMO_PORTFOLIO_POSITIONS`. Honest label so\n    callers know this isn't a live market snapshot. Only appears\n    on PortfolioResult rows where `demo_mode=True`.\n\nAnti-BUG-24 discipline: no hardcoded fallback values. Empty is\nhonest; unknown price is honest. Never fake data."New value: +"One holding in the user's portfolio, from a linked brokerage or entered by hand."
    • addedOutput schema / $defs / Position / properties / price_source / description
      Added value: +"Where the price came from: broker_derived = brokerage value / shares; cached_snapshot = saved market price, up to 7 days old; cache_miss = no price (value uses cost); demo_snapshot = fixed price of the labeled sample portfolio."
    • changedOutput schema / description
      Previous value: -"Return type for `list_portfolio()`. Rich shape matching web\n/portfolio: positions + totals + source split.\n\n`is_empty` is the explicit signal for empty-tenant / anonymous\ncallers — LLMs use it to distinguish \"no holdings yet\" from\n\"engine failure\". Post-BUG-24: NEVER return fake positions;\nempty state must render as empty state."New value: +"The user's holdings with totals. is_empty means there are no holdings to show."
    • addedOutput schema / properties / sign_in_hint
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "A sign-in or setup tip. Never a paid offer.",
      +  "title": "Sign In Hint"
      +}
    • removedOutput schema / properties / upgrade_hint
      Removed value: -{
      -  "anyOf": [
      -    {
      -      "type": "string"
      -    },
      -    {
      -      "type": "null"
      -    }
      -  ],
      -  "default": null,
      -  "title": "Upgrade Hint"
      -}
  2. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$defs": {
      +    "Position": {
      +      "additionalProperties": false,
      +      "description": "One holding in the caller's portfolio (manual entry OR\nPlaid-synced brokerage position). Merged view — matches the web\n/portfolio page shape.\n\n`price_source` documents where `current_price` came from:\n  - `broker_derived`: computed as `market_value / shares` where\n    `market_value` is Plaid-reported (fresh as of last brokerage\n    sync). Plaid doesn't send `current_price` directly — we\n    derive it, and this label says so honestly.\n  - `cached_snapshot`: read from stock_snapshot_cache (up to\n    7 days old; cache-refresh worker keeps it warm hourly).\n  - `cache_miss`: no price available; `current_price` is None\n    and `market_value` falls back to shares × avg_cost so\n    totals still make sense.\n  - `demo_snapshot`: BUG-57 (2026-08-25) — position belongs to\n    the shared demo portfolio (signed-in-empty tenant funneled\n    to anon pool) and price came from the reference-price map\n    baked into `_DEMO_PORTFOLIO_POSITIONS`. Honest label so\n    callers know this isn't a live market snapshot. Only appears\n    on PortfolioResult rows where `demo_mode=True`.\n\nAnti-BUG-24 discipline: no hardcoded fallback values. Empty is\nhonest; unknown price is honest. Never fake data.",
      +      "properties": {
      +        "account_type": {
      +          "title": "Account Type",
      +          "type": "string"
      +        },
      +        "avg_cost": {
      +          "title": "Avg Cost",
      +          "type": "number"
      +        },
      +        "cost_basis_status": {
      +          "default": "reported",
      +          "enum": [
      +            "reported",
      +            "split_uncertain"
      +          ],
      +          "title": "Cost Basis Status",
      +          "type": "string"
      +        },
      +        "current_price": {
      +          "anyOf": [
      +            {
      +              "type": "number"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null,
      +          "title": "Current Price"
      +        },
      +        "is_fund": {
      +          "default": false,
      +          "title": "Is Fund",
      +          "type": "boolean"
      +        },
      +        "market_value": {
      +          "title": "Market Value",
      +          "type": "number"
      +        },
      +        "pnl_dollars": {
      +          "anyOf": [
      +            {
      +              "type": "number"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null,
      +          "title": "Pnl Dollars"
      +        },
      +        "pnl_pct": {
      +          "anyOf": [
      +            {
      +              "type": "number"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "default": null,
      +          "title": "Pnl Pct"
      +        },
      +        "pnl_status": {
      +          "default": "computed",
      +          "enum": [
      +            "computed",
      +            "cost_unknown",
      +            "price_unavailable"
      +          ],
      +          "title": "Pnl Status",
      +          "type": "string"
      +        },
      +        "price_source": {
      +          "enum": [
      +            "broker_derived",
      +            "cached_snapshot",
      +            "cache_miss",
      +            "demo_snapshot"
      +          ],
      +          "title": "Price Source",
      +          "type": "string"
      +        },
      +        "shares": {
      +          "title": "Shares",
      +          "type": "number"
      +        },
      +        "source": {
      +          "enum": [
      +            "manual",
      +            "brokerage"
      +          ],
      +          "title": "Source",
      +          "type": "string"
      +        },
      +        "ticker": {
      +          "title": "Ticker",
      +          "type": "string"
      +        },
      +        "weight_pct": {
      +          "title": "Weight Pct",
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "ticker",
      +        "shares",
      +        "avg_cost",
      +        "market_value",
      +        "weight_pct",
      +        "account_type",
      +        "source",
      +        "price_source"
      +      ],
      +      "title": "Position",
      +      "type": "object"
      +    }
      +  },
      +  "additionalProperties": false,
      +  "description": "Return type for `list_portfolio()`. Rich shape matching web\n/portfolio: positions + totals + source split.\n\n`is_empty` is the explicit signal for empty-tenant / anonymous\ncallers — LLMs use it to distinguish \"no holdings yet\" from\n\"engine failure\". Post-BUG-24: NEVER return fake positions;\nempty state must render as empty state.",
      +  "properties": {
      +    "brokerage_count": {
      +      "default": 0,
      +      "title": "Brokerage Count",
      +      "type": "integer"
      +    },
      +    "demo_mode": {
      +      "default": false,
      +      "title": "Demo Mode",
      +      "type": "boolean"
      +    },
      +    "is_empty": {
      +      "title": "Is Empty",
      +      "type": "boolean"
      +    },
      +    "manual_count": {
      +      "default": 0,
      +      "title": "Manual Count",
      +      "type": "integer"
      +    },
      +    "positions": {
      +      "items": {
      +        "$ref": "#/$defs/Position"
      +      },
      +      "title": "Positions",
      +      "type": "array"
      +    },
      +    "price_freshness_note": {
      +      "title": "Price Freshness Note",
      +      "type": "string"
      +    },
      +    "total_cost": {
      +      "default": 0,
      +      "title": "Total Cost",
      +      "type": "number"
      +    },
      +    "total_pnl": {
      +      "default": 0,
      +      "title": "Total Pnl",
      +      "type": "number"
      +    },
      +    "total_pnl_pct": {
      +      "default": 0,
      +      "title": "Total Pnl Pct",
      +      "type": "number"
      +    },
      +    "total_value": {
      +      "default": 0,
      +      "title": "Total Value",
      +      "type": "number"
      +    },
      +    "upgrade_hint": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Upgrade Hint"
      +    }
      +  },
      +  "required": [
      +    "is_empty",
      +    "price_freshness_note"
      +  ],
      +  "title": "PortfolioResult",
      +  "type": "object"
      +}
  3. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Goes well beyond the annotations (which already declare readOnly/idempotent/non-destructive) by disclosing the sign-in requirement, the up-to-7-day price cache staleness, the no-guessing policy for unpriced positions, and the demo-portfolio behavior for users with no holdings. These are the exact caveats an agent needs to avoid misreporting stale or missing data; only the lack of any hint about ordering/size of the returned set keeps it from 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.

Conciseness4/5

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

Front-loaded with purpose, then usage routing, then a clearly delimited 'Limits:' block — highly scannable. Slightly redundant in repeating that unpriced positions and the demo portfolio are 'labeled', which costs a little tightness.

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?

Given an output schema carries the return shape, the description covers what the schema cannot: authentication requirement, data freshness, missing-data handling, and empty-state behavior. Nothing material for a correct call is absent.

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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate, and it correctly focuses on output meaning and preconditions instead.

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 ('List the user's stock portfolio holdings') and enumerates exactly what each position contains (shares, average cost, current price, market value, profit/loss, weight) plus totals. It also explicitly separates itself from stock_analysis for non-owned tickers, so an agent can route without opening a schema.

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 an explicit when-to-use condition ('when the user asks what they own or how their positions are doing') and an explicit when-not with the named alternative ('Don't use it for a public ticker the user doesn't own (use stock_analysis)').

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources