Skip to main content
Glama

Analyze a Stock

stock_analysis
Read-onlyIdempotent

Public market numbers for one US stock or ETF.

Returns price, day change, 52-week range, market cap and trailing P/E. Use this when the user asks about a specific ticker, for example AAPL or BRK.B. Don't use it for the user's own holdings (use list_portfolio) or for buy/sell decisions.

Limits: US tickers only; data from Yahoo Finance, up to 15 minutes old; without sign-in there is a shared daily limit. When signed in, the answer also says whether the ticker is on the user's watchlist. Educational information, not investment advice.

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

Input Schema

NameRequiredDescriptionDefault
tickerYesUS stock or ETF ticker, for example AAPL or BRK.B.

Output Schema

NameRequiredDescriptionDefault
nameNo
as_ofNo
priceNo
sourceYes
tickerYes
currencyNo
pe_ratioNo
narrativeYes
change_absNo
change_pctNo
market_capNo
week52_lowNo
data_statusNook = numbers found; not_found = no such ticker; unavailable = market data is down; busy = try again in a minute; limit = signed-out daily limit reached.
week52_highNo
sign_in_hintNoA sign-in or setup tip. Never a paid offer.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / properties / ticker / description
      Added value: +"US stock or ETF ticker, for example AAPL or BRK.B."
    • changedOutput schema / description
      Previous value: -"Return type for `stock_analysis(ticker)`.\n\nMARKET-17 S5-2: real public numbers from `mcp_server.stock_quote`\n(Yahoo, cached). Every number is computed in Python; None = unknown,\nnever a made-up 0. `data_status` says why numbers are missing:\n`not_found` (no such ticker), `unavailable` (Yahoo down), `busy`\n(global fetch cap), `limit` (signed-out daily cap). Educational only:\nno fair value, thesis or buy/sell call."New value: +"Public market numbers for one stock or ETF. Empty numbers mean unknown, never zero."
    • addedOutput schema / properties / data_status / description
      Added value: +"ok = numbers found; not_found = no such ticker; unavailable = market data is down; busy = try again in a minute; limit = signed-out daily limit reached."
    • 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: +{
      +  "additionalProperties": false,
      +  "description": "Return type for `stock_analysis(ticker)`.\n\nMARKET-17 S5-2: real public numbers from `mcp_server.stock_quote`\n(Yahoo, cached). Every number is computed in Python; None = unknown,\nnever a made-up 0. `data_status` says why numbers are missing:\n`not_found` (no such ticker), `unavailable` (Yahoo down), `busy`\n(global fetch cap), `limit` (signed-out daily cap). Educational only:\nno fair value, thesis or buy/sell call.",
      +  "properties": {
      +    "as_of": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "As Of"
      +    },
      +    "change_abs": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Change Abs"
      +    },
      +    "change_pct": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Change Pct"
      +    },
      +    "currency": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Currency"
      +    },
      +    "data_status": {
      +      "anyOf": [
      +        {
      +          "enum": [
      +            "ok",
      +            "not_found",
      +            "unavailable",
      +            "busy",
      +            "limit"
      +          ],
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Data Status"
      +    },
      +    "market_cap": {
      +      "anyOf": [
      +        {
      +          "type": "integer"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Market Cap"
      +    },
      +    "name": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Name"
      +    },
      +    "narrative": {
      +      "title": "Narrative",
      +      "type": "string"
      +    },
      +    "pe_ratio": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Pe Ratio"
      +    },
      +    "price": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Price"
      +    },
      +    "source": {
      +      "enum": [
      +        "watchlist",
      +        "public"
      +      ],
      +      "title": "Source",
      +      "type": "string"
      +    },
      +    "ticker": {
      +      "title": "Ticker",
      +      "type": "string"
      +    },
      +    "upgrade_hint": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Upgrade Hint"
      +    },
      +    "week52_high": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Week52 High"
      +    },
      +    "week52_low": {
      +      "anyOf": [
      +        {
      +          "type": "number"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "title": "Week52 Low"
      +    }
      +  },
      +  "required": [
      +    "ticker",
      +    "narrative",
      +    "source"
      +  ],
      +  "title": "StockAnalysis",
      +  "type": "object"
      +}
  3. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, open-world and non-destructive, and the description adds materially more: US-only coverage, Yahoo Finance as source, up to 15-minute staleness, a shared daily limit when unauthenticated, and watchlist enrichment when signed in. Those are exactly the constraints an agent needs to set user expectations and avoid promising real-time or global coverage.

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 limits and disclaimers in a scannable order; every block serves a distinct need. Minor waste from restating the AAPL/BRK.B example that the schema already contains, plus a compliance disclaimer that is boilerplate but defensible.

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 single-parameter read tool with an output schema (so return values need no prose), the description covers everything else that matters: scope, data provenance, freshness, rate limits, auth-dependent behavior, and the educational-use caveat. Nothing an agent needs to call or frame the result is missing.

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?

The only parameter, ticker, is fully documented in the schema (100% coverage) including the same AAPL/BRK.B example repeated here, so the description adds no new argument-level meaning. The 'US tickers only' and ETF allowance statements are borderline new but largely mirror the schema text.

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 precise verb-resource statement ('Public market numbers for one US stock or ETF') and immediately enumerates the returned fields (price, day change, 52-week range, market cap, trailing P/E), so the agent knows exactly what the tool yields. It also explicitly carves itself away from list_portfolio, making it distinguishable from siblings without reading any 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 a concrete positive trigger ('user asks about a specific ticker, for example AAPL or BRK.B') plus two explicit exclusions with a named alternative: holdings go to list_portfolio, and buy/sell decisions are out of scope. That is the when/when-not/alternative triad at full strength.

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