Skip to main content
Glama
haiyunsky

HPSILab - Quant Finance MCP Server for Stock Analysis and Options Analytics

HPSILab Quant Finance MCP Server for Stock & Options Analytics

PyPI CI License

HPSILab is an open-source Python quantitative finance MCP server for research on US equities, ETFs, and supported options. It brings stock signals, implied volatility, options analytics, Monte Carlo simulation, AI prediction, backtesting, and risk analysis into ChatGPT, Claude, Cursor, VS Code, and other MCP clients. Connect once, ask in natural language, and receive structured results that an assistant can compare and explain.

Research and educational use only. HPSILab does not provide investment advice and does not execute trades.

Get a Free API Key · Pricing · Tool reference · Client setup · Python SDK

Registry name

io.github.haiyunsky/hpsilab-quant-finance-mcp

Version

0.10.0 — a source checkout reports 0.10.0+source

Transports

Streamable HTTP (hosted) · stdio (PyPI package)

Remote endpoint

https://hpsilab.com/mcp

Package

pip install -U hpsilab-quant-finance-mcp

Authentication

Bearer API key, or HPSILAB_API_KEY for stdio

Tools

10 — nine financial research tools plus register_account

Connect: hosted Streamable HTTP

Recommended, and requires no local installation.

  1. Register a free account, sign in, and generate an API key from Settings.

  2. Add the server to your client's private configuration, replacing hpsi_your_key. Never commit a real key or paste one into chat.

The example below is Claude Code's .mcp.json; other clients use different configuration schemas, all covered in client setup.

{
  "mcpServers": {
    "hpsilab": {
      "type": "http",
      "url": "https://hpsilab.com/mcp",
      "headers": {
        "Authorization": "Bearer hpsi_your_key"
      }
    }
  }
}
  1. Verify the connection:

Use HPSILab to analyze AAPL. Separate observed metrics from interpretation,
identify conflicting signals, and finish with a concise risk summary.

All financial research tools require a valid API key. See authentication for key handling and rotation.

Related MCP server: yahoo-finance-mcp-server

Connect: local stdio

For clients that require a local process:

pip install -U hpsilab-quant-finance-mcp

This example uses the mcpServers schema supported by Claude and Cursor; VS Code and GitHub Copilot use a servers schema instead.

{
  "mcpServers": {
    "hpsilab": {
      "command": "hpsilab-quant-finance-mcp",
      "env": {
        "HPSILAB_API_KEY": "hpsi_your_key"
      }
    }
  }
}

Then verify it through the MCP client:

Use HPSILab to get the AI prediction for NVDA and summarize the model consensus.

The client discovers tools with MCP tools/list and invokes them with tools/call. See local setup and Python usage, which also covers calling the tool functions directly from Python.

Tools

Nine financial research tools, plus register_account. Tool names and parameter meanings are part of the public compatibility contract.

Tool

What it returns

Behavior

analyze_stock

Aggregate directional and quantitative stock analysis

Read-only

get_ai_prediction

Next-session prediction, confidence, and model consensus

Read-only

get_iv_radar

IV level, rank, percentile, skew, and regime

Read-only

get_option_pressure

Max pain, gamma walls, expected move, and pressure zones

Read-only

get_monte_carlo

30-day simulated distribution and probabilities

Read-only

get_equity_curve

Strategy backtests and risk-adjusted performance

Read-only

get_pretrade_risk_scan

Position, exposure, correlation, and risk checks

Read-only

generate_stock_images

Hosted stock and options chart artifacts

Creates an artifact; not idempotent

generate_stock_research_report

Structured Markdown research report and timestamp

Creates an artifact; not idempotent

register_account

Account credentials for the authenticated caller

Creates an account and sends email; not idempotent

Research tools accept one exchange ticker such as NVDA, SPY, or BRK.B; company names are not accepted. Live results can change between calls. Artifact tools can consume quota and should not be retried automatically.

Full inputs, outputs, side effects, and tool-selection guidance are in docs/tools.md.

Monte Carlo research example

PLTR Monte Carlo scenario visualization

Example visualization of scenario-based Monte Carlo research output. Results depend on the selected inputs and model assumptions. See get_monte_carlo for tool details.

Copy-ready prompts

Claude

Use HPSILab to analyze NVDA. Summarize the directional signal, AI model
consensus, IV regime, options pressure, 30-day Monte Carlo range, and the
three most important risks. Distinguish tool data from interpretation.

Cursor

Use HPSILab's IV radar and option-pressure tools for SPY. Compare IV rank,
percentile, skew, expected move, max pain, gamma wall, and pressure zones.
Return a compact table and do not recommend a trade.

ChatGPT

Run the HPSILab pre-trade risk scan for TSLA. Explain every warning or failed
check, preserve unavailable fields as unavailable, and quote the returned
reason instead of guessing. Do not execute or recommend a trade.

Setup guidance covers ChatGPT, Claude, Cursor, VS Code, GitHub Copilot, Continue, and Kimi. See the client setup guide for each client's transport and configuration format.

Errors, retries, and limits

Every failure is a structured object with a stable error_code, never prose an agent has to pattern-match. Five refusals matter, because each has a different remedy:

error_code

Meaning

What resolves it

api_key_required

No key is configured

Registering. Nothing is sent downstream

rate_limited

Calling too fast (429)

Waiting — next_actions carries the seconds

insufficient_credits

The Credit balance is empty (402)

Adding Credits, or registering for trial Credits

allowance_exhausted

The free evaluation ceiling is spent (402)

Registering, or verifying an email. Money does not lift it

settlement_unknown

A payment whose outcome is unconfirmed

Reconciliation. Do not retry it and do not pay again

Without a key the package stops locally, before constructing the downstream client or sending a request:

{
  "error": "api_key_required",
  "message": "A free API key is required.",
  "register_url": "https://hpsilab.com/register",
  "docs_url": "https://hpsilab.com/developer/v2"
}

401 and 402 responses are never retried. A 429 is retried only when it carries a valid Retry-After. Read-only calls use a finite retry budget for timeouts and recoverable 500/502/503/504 responses; artifact-producing calls are not retried automatically. The package also applies one process-local safeguard of 10 requests per rolling minute per API key — burst protection, not a quota, since only the hosted service knows the balance and the plan.

Field-by-field payloads, the Credits circuit breaker, and the reasoning behind each remedy are in docs/authentication.md and docs/python-sdk.md.

Why HPSILab

HPSILab gives assistants typed inputs, structured outputs, ticker validation, machine-readable errors, and dedicated tools instead of invented metrics. It supports US-listed equities, ETFs, and supported options data; coverage and limits depend on the hosted service and plan.

Safety and license

HPSILab is for research and education only. Outputs may be incomplete, delayed, or wrong and are not investment, financial, or trading advice. The MCP server has no brokerage connectivity, order entry, or trade-execution capability.

Licensed under the MIT License. Contributions are welcome; read AGENTS.md and CONTRIBUTING.md before proposing public schema changes.

Available Tools

9 tools
analyze_stockAInspect

Run a full institutional-grade quantitative analysis for a single stock.

This is the primary tool for a complete market view. It aggregates results from AI prediction, implied-volatility radar, options-pressure map, Monte Carlo simulation, and strategy backtesting into one unified signal.

Use this tool when:

  • You need a holistic bull/bear verdict with supporting evidence.

  • You want to compare multiple signal sources in a single call.

  • A user asks for a "stock analysis", "market view", or "trading signal".

Prefer the dedicated sub-tools (get_iv_radar, get_monte_carlo, etc.) when you need only a specific data dimension, to reduce latency and token usage.

Parameters

symbol : str Exchange ticker in uppercase, e.g. "NVDA", "AAPL", "SPY", "QQQ". Do NOT pass company names ("Nvidia") — use official tickers only.

Returns

dict with keys: symbol : str — normalized ticker signal : str — "Bullish" | "Bearish" | "Neutral" confidence_score: int — 0–100 directional confidence bullish_factors : list — evidence supporting an upward move bearish_factors : list — evidence supporting a downward move summary : str — one-sentence synthesis

Notes

  • Requires a valid HPSILAB_API_KEY.

  • API access, quota, and ticker coverage are governed by the HPSILab account.

  • Response latency is ~5–15 s due to multi-model aggregation.

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesExchange ticker in uppercase, e.g. 'NVDA', 'AAPL', 'SPY', 'QQQ'. Do NOT pass company names ('Nvidia') — use official tickers only.

TDQS

A4.9/5.0
Behavior5/5

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

Discloses aggregation of multiple data sources, API key requirement, quota/ticker coverage, and latency (~5-15 s). No annotations are provided, so the description fully covers behavioral traits.

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

Conciseness5/5

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

Well-organized with sections for purpose, usage, parameters, returns, and notes. Each sentence adds value without unnecessary verbosity.

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?

Despite no output schema, the description thoroughly explains return structure. Combined with behavioral and usage details, it provides a complete understanding for a complex tool.

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 input schema has 100% coverage for the single parameter. The description adds value by reinforcing the symbol format and explicitly forbidding company names, which goes beyond 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?

The description clearly states it performs 'full institutional-grade quantitative analysis for a single stock,' using a specific verb and resource. It distinguishes itself from sibling sub-tools by positioning itself as the primary holistic analysis tool.

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?

Explicitly lists when to use (holistic verdict, multiple signals, user requests 'stock analysis') and when not to (prefer sub-tools for specific dimensions), providing clear alternatives.

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

generate_stock_imagesAInspect

Generate chart image URLs for a stock: price chart, IV surface, and options flow heatmap.

Use this tool when:

  • A user explicitly asks to "see", "show", or "visualize" a chart.

  • You want to accompany a written analysis with supporting visuals.

  • You need to share chart links in a report or message.

Note: Images are served as public URLs. They expire after 24 hours. If images do not render in your client, copy the URL and open it in a browser directly.

Parameters

symbol : str Exchange ticker in uppercase, e.g. "NVDA", "AAPL".

Returns

dict with keys: symbol : str — normalized ticker price_chart_url : str — URL to candlestick + volume chart (PNG) iv_surface_url : str — URL to 3-D IV surface chart (PNG) options_flow_url: str — URL to options flow heatmap (PNG) expires_at : str — ISO 8601 expiry timestamp for the URLs

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesExchange ticker in uppercase, e.g. 'NVDA', 'AAPL'. Do NOT pass company names — use official tickers only.

TDQS

A4.5/5.0
Behavior5/5

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

Given no annotations, the description fully discloses key behaviors: images are public URLs, expire after 24 hours, and troubleshooting for rendering failures (copy URL to browser). It also details the return structure, which compensates for the lack of output schema.

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

Conciseness5/5

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

The description is well-organized with clear sections (usage, note, parameters, returns). Every sentence adds value without redundancy. It is front-loaded with the core purpose.

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 simple one-parameter tool with no output schema, the description provides complete information: what the tool does, when to use it, behavioral notes, parameter details, and return format (listing four keys). The context signals (1 param, no output schema) are fully addressed.

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%, and the description's parameter section ('symbol: Exchange ticker in uppercase, e.g. NVDA, AAPL') does not add significant meaning beyond the schema's pattern, examples, and description. Therefore, baseline 3 is appropriate.

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 description clearly states the tool generates chart image URLs for a stock, listing three specific chart types (price chart, IV surface, options flow heatmap). It distinguishes itself from siblings like 'analyze_stock' or 'get_equity_curves' by focusing on visual outputs.

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?

The description explicitly lists when to use the tool (user asks to see/show/visualize a chart, accompany analysis with visuals, share chart links). It does not include when-not-to-use or alternative tools, but the siblings are provided separately.

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

generate_stock_research_reportAInspect

Generate a structured, institutional-style markdown research report for a single stock, covering all major quantitative signal sources.

The report is divided into six sections:

  1. Executive Summary — bull/bear verdict, confidence score, one-line thesis

  2. AI Prediction — ensemble model votes, up-probability, regime

  3. Volatility Analysis — ATM IV, IV rank, vol regime, risk reversal

  4. Options Positioning — max pain, gamma wall, expected move, squeeze targets

  5. Monte Carlo Outlook — 30-day price distribution, 90 %/68 % confidence ranges

  6. Strategy Backtests — Sharpe, max drawdown, win rate across quant strategies

Output is a complete markdown string (~800–1200 words) ready to render or share. Response latency is ~10–20 s due to full multi-model data aggregation.

Use this tool when:

  • A user asks for a "report", "write-up", "research note", or "deep dive".

  • You want a pre-formatted narrative combining all signal sources in one document.

  • You need output suitable for archiving, PDF export, or investor communication.

Do NOT use this tool when:

  • You only need a quick directional verdict → use analyze_stock instead.

  • You need a specific data dimension (IV, Monte Carlo, etc.) → use the dedicated sub-tool (get_iv_radar, get_monte_carlo, etc.) for lower latency.

Parameters

symbol : str Exchange ticker in uppercase, e.g. "NVDA", "TSLA", "SPY". Do NOT pass company names — use official tickers only.

Returns

dict with keys: symbol : str — normalized ticker report : str — full markdown report (~800–1200 words, 6 sections) generated_at : str — ISO 8601 generation timestamp

Notes

  • Requires a valid HPSILAB_API_KEY.

  • API access, quota, and ticker coverage are governed by the HPSILab account.

  • For programmatic use, prefer analyze_stock which returns structured JSON.

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesExchange ticker in uppercase, e.g. 'NVDA', 'TSLA', 'SPY'. Do NOT pass company names — use official tickers only.

TDQS

A4.5/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. It discloses latency (~10-20 s), reliance on HPSILAB_API_KEY, and that output is a full markdown report of ~800-1200 words. Could mention if it's read-only or modifies state, but reasonable given context.

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?

Well-structured with headings, bullet points, and clear sections. Front-loaded with purpose and six sections list. Slightly verbose but each sentence adds value. Could tighten 'Output is a complete markdown string' vs earlier mention, but overall effective.

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

Completeness4/5

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

Given no output schema, description provides return keys (symbol, report, generated_at) and report length. Lists six sections in detail. Also includes notes on API key and programmatic alternatives. Covers most information an agent needs to decide and use the tool.

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?

Only one parameter symbol with 100% schema description coverage. Description adds meaningful guidance beyond schema: 'Do NOT pass company names — use official tickers only.' This helps avoid common errors.

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 description clearly states it generates a structured markdown research report for a single stock covering all major quantitative signal sources. It distinguishes itself from siblings like analyze_stock (structured JSON), get_iv_radar, get_monte_carlo, etc., by noting these are faster for specific data.

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?

Explicitly states when to use (user asks for report, write-up, deep dive) and when not to use (quick directional verdict → analyze_stock, specific data dimension → sub-tools). Also mentions latency of 10-20 seconds as a trade-off.

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

get_ai_predictionAInspect

Get an AI/ML directional prediction for a stock's next-session move.

Use this tool when:

  • You want a data-driven probability estimate for the next trading day's direction (up vs. down).

  • You need the individual model votes (ensemble breakdown) to assess consensus strength.

  • You want to compare model confidence against current IV pricing.

The prediction engine uses an ensemble of gradient-boosted trees, an LSTM, and a VQC (quantum-classical hybrid) model. Features include VIX, relative strength, Treasury rates, and options flow signals.

Parameters

symbol : str Exchange ticker in uppercase, e.g. "NVDA", "META", "QQQ". Per-ticker model accuracy varies; META and QQQ have shown above- baseline hit rates in backtests.

Returns

dict with keys: symbol : str — normalized ticker prediction : str — "Up" | "Down" | "Neutral" up_probability : float — 0.0–1.0 probability of upward close confidence : float — 0.0–1.0 ensemble agreement score model_votes : dict — per-model predictions and probabilities regime : str — "Bull" | "Bear" | "Chop" market regime signal_strength : str — "Strong" | "Moderate" | "Weak"

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesExchange ticker in uppercase, e.g. 'NVDA', 'META', 'QQQ'. Do NOT pass company names — use official tickers only. Per-ticker model accuracy varies; META and QQQ have shown above-baseline hit rates in backtests.

TDQS

A4.4/5.0
Behavior4/5

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

Describes ensemble models (GBM, LSTM, VQC), input features (VIX, rates, options flow), and per-ticker accuracy variation. No annotations to contradict; detailed behavioral disclosure.

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?

Well-structured with sections for usage, engine details, parameters, and returns. No extra fluff; every sentence contributes. Slightly lengthy return description is justified by missing output schema.

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, so the description fully documents all return fields (symbol, prediction, probabilities, votes, regime, signal strength). Also covers model details and accuracy caveats, making the tool self-contained.

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?

Single parameter symbol has 100% schema coverage. Description adds 'Do NOT pass company names' and notes META/QQQ have better hit rates, providing extra beyond 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?

Specific verb+resource+scope: 'Get an AI/ML directional prediction for a stock's next-session move'. Clear action and outcome, distinct from sibling tools like get_iv_radar or get_monte_carlo.

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?

Provides explicit 'Use this tool when' scenarios: need probability estimate, ensemble breakdown, or compare confidence to IV pricing. Could mention alternatives but offers actionable context.

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

get_equity_curvesAInspect

Retrieve backtested equity curves and performance metrics for standard quantitative strategies applied to a single stock.

Use this tool when:

  • You want to evaluate how well rule-based strategies (momentum, mean- reversion, vol-targeting) have performed on this specific ticker.

  • You need risk-adjusted return metrics (Sharpe, Sortino, max drawdown) to compare strategy quality.

  • You are building a multi-leg options strategy and want historical context for the underlying's trending vs. mean-reverting behavior.

Parameters

symbol : str Exchange ticker in uppercase, e.g. "NVDA", "AAPL", "SPY".

Returns

dict with keys: symbol : str — normalized ticker strategies : list — each item is a dict with: name : str — strategy name total_return : float — cumulative return (e.g., 0.45 = +45 %) sharpe_ratio : float — annualized Sharpe ratio sortino_ratio : float — annualized Sortino ratio max_drawdown : float — maximum peak-to-trough loss (negative) win_rate : float — fraction of winning trades (0–1) pl_ratio : float — average win / average loss equity_curve : list — daily portfolio value series

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesExchange ticker in uppercase, e.g. 'NVDA', 'AAPL', 'SPY'. Do NOT pass company names — use official tickers only.

TDQS

A4.7/5.0
Behavior4/5

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

No annotations exist, so description carries full burden. It discloses read-only nature, return structure, and data type (dict with specific fields). Lacks details on error handling or prerequisites but adequate for a retrieval tool.

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

Conciseness5/5

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

Well-structured with clear headings (Parameters, Returns) and bullet points. Every sentence adds value; no fluff. Front-loaded with purpose and usage.

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, so description fully documents return structure with field names, types, and examples. Includes enough detail to understand expected output without ambiguity.

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%, baseline 3. Description adds value by warning against company names and reiterating symbol format, going beyond schema. However, it largely reiterates schema information.

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 description uses a specific verb ('Retrieve') and resource ('backtested equity curves and performance metrics for standard quantitative strategies applied to a single stock'), clearly distinguishing it from sibling tools like 'analyze_stock' or 'get_ai_prediction' which serve different purposes.

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 'Use this tool when' section with three concrete scenarios (evaluating rule-based strategies, needing risk-adjusted metrics, building multi-leg options strategies) provides clear guidance on when to invoke this tool.

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

get_iv_radarAInspect

Retrieve implied-volatility (IV) metrics for a single stock.

Use this tool when:

  • You need to assess whether options are cheap or expensive relative to historical norms (IV rank / IV percentile).

  • You want the current volatility regime ("Low", "Normal", "Elevated", "Extreme") to frame risk sizing or strategy selection.

  • You are analyzing skew or risk-reversal direction (put-heavy vs call-heavy market).

Do NOT use this tool if you already called analyze_stock — the IV data is included in that response.

Parameters

symbol : str Exchange ticker in uppercase, e.g. "TSLA", "NVDA", "IWM".

Returns

dict with keys: symbol : str — normalized ticker atm_iv : float — at-the-money implied volatility (annualized %) iv_rank : float — 0–100; ≥80 = expensive, ≤20 = cheap iv_percentile : float — historical percentile (0–100) risk_reversal : float — 25-delta risk reversal (positive = call-skew) volatility_regime: str — "Low" | "Normal" | "Elevated" | "Extreme"

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesExchange ticker in uppercase, e.g. 'TSLA', 'NVDA', 'IWM'. Do NOT pass company names — use official tickers only.

TDQS

A4.2/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It explains the return structure and key metrics, which partially addresses transparency. However, it does not disclose behavioral traits such as authorization requirements, rate limits, or error handling. The read-only nature is implied but not explicitly stated.

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

Conciseness5/5

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

The description is concise and well-structured: a one-line summary, bulleted use cases, a do-not-use note, and formatted parameters/returns. Every sentence adds value, and the key information is front-loaded.

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

Completeness4/5

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

Given the tool's low complexity (single parameter, no output schema), the description is complete. It covers return fields, usage scenarios, and sibling differentiation. Minor omission: no mention of error behavior for invalid symbols, but overall sufficient.

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 input schema provides complete coverage (100%) with description, pattern, and examples for the single 'symbol' parameter. The tool description repeats this info but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate.

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 description clearly states 'Retrieve implied-volatility (IV) metrics for a single stock' and lists specific metrics (IV rank, percentile, volatility regime, risk reversal). It also explicitly distinguishes from the sibling 'analyze_stock' by noting that the IV data is included in that response, thus differentiating the tool's purpose.

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?

The description provides explicit 'Use this tool when:' scenarios (assessing options cheapness, current volatility regime, skew analysis) and a clear 'Do NOT use' condition (if already called analyze_stock). This gives concrete guidance on when to invoke this tool versus alternatives.

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

get_monte_carloAInspect

Run a Monte Carlo price-path simulation for a stock over a 30-day horizon.

Use this tool when:

  • You need a probabilistic price range rather than a single point estimate.

  • You want to quantify downside risk (e.g., probability of a 10 % drawdown).

  • You are sizing a position using a volatility-adjusted scenario.

The simulation uses a GBM (Geometric Brownian Motion) model calibrated with the stock's realized volatility and current IV. 10,000 paths are run by default.

Parameters

symbol : str Exchange ticker in uppercase, e.g. "MSFT", "NVDA", "SPY".

Returns

dict with keys: symbol : str — normalized ticker current_price : float — spot price at simulation start mean_price : float — expected price at horizon range_90 : dict — {"lower": float, "upper": float} 90 % CI range_68 : dict — {"lower": float, "upper": float} 68 % CI prob_above_spot: float — probability (0–1) price is above current spot prob_10pct_drop: float — probability (0–1) of ≥10 % decline distribution : dict — histogram data: {"bins": list, "frequencies": list, "kde_x": list, "kde_y": list}

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesExchange ticker in uppercase, e.g. 'MSFT', 'NVDA', 'SPY'. Do NOT pass company names — use official tickers only.

TDQS

A4.4/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses the GBM model, default 10,000 paths, and calibration data (realized volatility and IV). While it does not cover limitations or model assumptions, it provides sufficient behavioral context for a simulation tool.

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?

The description is well-structured with bullet points for use cases and a clear 'Returns' section. It is appropriately sized (~200 words) with each sentence adding value. Slightly more conciseness in the parameter description could push it to 5.

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 fully explains return values with a detailed dict breakdown, including nested dictionaries for range and distribution. Given the complexity of a Monte Carlo simulation with multiple outputs, the description is very complete.

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 baseline is 3. The description adds value beyond the schema by explicitly warning against using company names instead of tickers ('Do NOT pass company names — use official tickers only.'), which helps prevent common errors.

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 description explicitly states it runs a Monte Carlo price-path simulation for a stock over a 30-day horizon, with a specific verb (run/simulate) and resource (price-path). It distinguishes itself from siblings like 'analyze_stock' and 'get_ai_prediction' by focusing on probabilistic range and risk quantification.

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?

The description provides clear when-to-use scenarios: needing a probabilistic range, quantifying downside risk, sizing positions. It implicitly suggests alternatives for single-point estimates but does not explicitly name sibling tools as alternatives, keeping it from a 5.

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

get_option_pressureAInspect

Retrieve options-market positioning and dealer-hedging pressure zones.

Use this tool when:

  • You want to identify max-pain price (where option sellers face least loss at expiry) as a gravitational target near expiration.

  • You need to locate gamma walls (strike clusters with large open interest) that act as price magnets or resistance/support levels.

  • You want the expected-move range implied by the options market for the current weekly/monthly expiry cycle.

Parameters

symbol : str Exchange ticker in uppercase, e.g. "AAPL", "SPY", "NVDA".

Returns

dict with keys: symbol : str — normalized ticker max_pain : float — max-pain strike price gamma_wall : float — largest gamma concentration strike expected_move : float — ±expected move in dollars for nearest expiry squeeze_target: float — upside squeeze price target expiry_date : str — target expiry date (YYYY-MM-DD) pressure_zones: list — list of significant strike/OI concentration dicts

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesExchange ticker in uppercase, e.g. 'AAPL', 'SPY', 'NVDA'. Do NOT pass company names — use official tickers only.

TDQS

A4.5/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden. It clearly describes what the tool does (retrieves data) and what it returns, implying a read-only operation. It could explicitly state it has no side effects, but the language is consistent with a non-destructive tool.

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

Conciseness5/5

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

The description is concise and well-structured: a lead sentence, a bullet list of use cases, a parameter section, and a returns section. Every sentence adds value, and the most important information is front-loaded.

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 the tool has only one parameter, no output schema, and no annotations, the description is very complete. It covers the purpose, when to use, the required parameter, and a detailed list of return values.

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% with a single parameter. The description repeats the schema info but adds value with a negative instruction: 'Do NOT pass company names — use official tickers only.' This goes beyond the schema's examples.

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 description starts with a clear, specific verb+resource: 'Retrieve options-market positioning and dealer-hedging pressure zones.' It lists concrete use cases (max-pain, gamma walls, expected move), distinguishing it from sibling tools like analyze_stock or get_iv_radar.

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?

The description explicitly says 'Use this tool when:' and provides three specific scenarios, giving clear context. It does not mention when not to use or name alternatives, but the sibling tools are sufficiently different so this is a minor gap.

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

get_pretrade_risk_scanAInspect

Run a pre-trade risk scan for adding a single stock to the user's tracked portfolio, covering volatility/beta/VaR/drawdown deltas, market regime, a forward return distribution, position-sizing checks, sector/symbol exposure impact, and correlation against existing holdings.

Use this tool when:

  • You need a risk-first check before evaluating or placing a trade.

  • You want position-sizing guardrails (volatility, drawdown, beta, liquidity) evaluated against warn/fail thresholds, not just raw numbers.

  • You need to see how adding this symbol would shift sector or per-symbol concentration in the existing portfolio.

  • You want the new symbol's correlation to current holdings, to judge diversification benefit vs. redundant exposure.

Do NOT use this tool for:

  • A standalone price-distribution simulation with no portfolio context → use get_monte_carlo instead.

  • A general bullish/bearish read on the stock → use analyze_stock.

Parameters

symbol : str Exchange ticker in uppercase, e.g. "NVDA", "AAPL", "SPY".

Example

get_pretrade_risk_scan("NVDA")

Returns

dict with keys: symbol : str — normalized ticker asOf : str — ISO 8601 date the scan was computed regime : str — "bull" | "bear" | "chop" market regime regimeConfidence: float — 0–1 confidence in the regime classification riskDeltas : list — before/after risk metrics from adding the position, each item a dict with: label : str — e.g. "Annualized Volatility", "Beta (vs SPY)", "1-Day VaR (95%)", "Max Drawdown (1Y)" beforeValue : float — metric value for current portfolio afterValue : float — metric value after adding the position unit : str — "%" or "" (unitless, e.g. beta) higherIsRiskier : bool — whether an increase in this metric is worse distribution : dict — forward return distribution: {"bins": list, "frequencies": list, "kde_x": list, "kde_y": list} range_90 : dict — {"lower": float, "upper": float} 90 % CI on forward return (%) mean : float — expected forward return (%) threshold : float — reference return threshold used in the scan sizingChecks : list — pass/warn/fail guardrail checks, each a dict: label : str — "Volatility" | "Drawdown Risk" | "Market Exposure" | "Liquidity" status : str — "pass" | "warn" | "fail" detail : str — human-readable explanation with the thresholds used exposure : dict — portfolio concentration impact: available : bool — false if the user has no watchlist symbols to compare against bySector : list of {sector, currentPct, postTradePct, deltaPct} — empty list when available is false bySymbol : list of {symbol, currentPct, postTradePct, deltaPct} — empty list when available is false concentrationFlag : str — "pass" | "warn" | "fail" | "unknown" ("unknown" when available is false) assumedPositionWeight: float | None — None when available is false weightingMethod : str — e.g. "equal_weight_proxy" reason : str — present only when available is false; human-readable explanation (e.g. "No watchlist symbols to compare against. Add symbols to your watchlist to see portfolio exposure.") — surface this to the user instead of guessing why the section is empty correlation : dict — correlation of the new symbol to holdings: available : bool — false if the user has no watchlist symbols to compare against aggregate : dict | None — None when available is false; otherwise {avgCorrelationWithPortfolio, level, mostCorrelated: {symbol, correlation}, leastCorrelated: {symbol, correlation}} matrix : dict | None — None when available is false; otherwise {"symbols": list, "values": list[list[float]]} full pairwise correlation matrix reason : str — present only when available is false; human-readable explanation (e.g. "No watchlist symbols to compare against. Add symbols to your watchlist to see correlation.") — surface this to the user instead of guessing why the section is empty

Notes

  • Requires a valid HPSILAB_API_KEY.

  • Exposure and correlation sections assume the user has an existing tracked watchlist/portfolio. If none exists, "available" is false in both sections, their data fields are null/empty, and each includes a "reason" string explaining why — relay that reason to the user (e.g. suggest adding symbols to their watchlist) rather than treating the missing data as an error.

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesExchange ticker in uppercase, e.g. 'NVDA', 'AAPL', 'SPY'. Do NOT pass company names — use official tickers only.

TDQS

A4.4/5.0
Behavior4/5

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

No annotations exist, so the description carries the full burden. It thoroughly explains return structure, edge cases (e.g., no watchlist), and authentication requirements. However, it does not explicitly state whether the operation is read-only or has side effects, which is a minor gap.

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?

Well-structured with clear sections (purpose, usage, params, example, returns, notes). The parameter section is redundant with the schema, but overall the description is concise given the tool's complexity and front-loads the main purpose.

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?

Provides comprehensive documentation of all return fields, including nested structures, edge cases, and user-facing messages. With no output schema, the description fully compensates, and the single parameter is well-defined.

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 coverage is 100% for the single parameter; both the schema and description provide identical details (uppercase ticker, examples, no company names). The description adds an example call but no additional semantic meaning beyond 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?

The description clearly states the tool runs a pre-trade risk scan for adding a single stock, listing specific risk metrics. It explicitly distinguishes from siblings 'get_monte_carlo' and 'analyze_stock', making the tool's unique purpose unmistakable.

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?

Provides explicit 'Use this tool when' and 'Do NOT use this tool for' sections, with alternative tool names and clear criteria. This gives an AI agent unambiguous guidance on when to select this tool over siblings.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 9 tool updatesv0.3.1
    • Changedanalyze_stock3 fields changed
      • addedInput schema / properties / symbol / description
        Added value: +"Exchange ticker in uppercase, e.g. 'NVDA', 'AAPL', 'SPY', 'QQQ'. Do NOT pass company names ('Nvidia') — use official tickers only."
      • addedInput schema / properties / symbol / examples
        Added value: +[
        +  "NVDA",
        +  "AAPL",
        +  "SPY",
        +  "QQQ"
        +]
      • addedInput schema / properties / symbol / pattern
        Added value: +"^[A-Z][A-Z0-9.-]{0,15}$"
    • Changedgenerate_stock_images3 fields changed
      • addedInput schema / properties / symbol / description
        Added value: +"Exchange ticker in uppercase, e.g. 'NVDA', 'AAPL'. Do NOT pass company names — use official tickers only."
      • addedInput schema / properties / symbol / examples
        Added value: +[
        +  "NVDA",
        +  "AAPL"
        +]
      • addedInput schema / properties / symbol / pattern
        Added value: +"^[A-Z][A-Z0-9.-]{0,15}$"
    • Changedgenerate_stock_research_report3 fields changed
      • addedInput schema / properties / symbol / description
        Added value: +"Exchange ticker in uppercase, e.g. 'NVDA', 'TSLA', 'SPY'. Do NOT pass company names — use official tickers only."
      • addedInput schema / properties / symbol / examples
        Added value: +[
        +  "NVDA",
        +  "TSLA",
        +  "SPY"
        +]
      • addedInput schema / properties / symbol / pattern
        Added value: +"^[A-Z][A-Z0-9.-]{0,15}$"
    • Changedget_ai_prediction3 fields changed
      • addedInput schema / properties / symbol / description
        Added value: +"Exchange ticker in uppercase, e.g. 'NVDA', 'META', 'QQQ'. Do NOT pass company names — use official tickers only. Per-ticker model accuracy varies; META and QQQ have shown above-baseline hit rates in backtests."
      • addedInput schema / properties / symbol / examples
        Added value: +[
        +  "NVDA",
        +  "META",
        +  "QQQ"
        +]
      • addedInput schema / properties / symbol / pattern
        Added value: +"^[A-Z][A-Z0-9.-]{0,15}$"
    • Changedget_equity_curves3 fields changed
      • addedInput schema / properties / symbol / description
        Added value: +"Exchange ticker in uppercase, e.g. 'NVDA', 'AAPL', 'SPY'. Do NOT pass company names — use official tickers only."
      • addedInput schema / properties / symbol / examples
        Added value: +[
        +  "NVDA",
        +  "AAPL",
        +  "SPY"
        +]
      • addedInput schema / properties / symbol / pattern
        Added value: +"^[A-Z][A-Z0-9.-]{0,15}$"
    • Changedget_iv_radar3 fields changed
      • addedInput schema / properties / symbol / description
        Added value: +"Exchange ticker in uppercase, e.g. 'TSLA', 'NVDA', 'IWM'. Do NOT pass company names — use official tickers only."
      • addedInput schema / properties / symbol / examples
        Added value: +[
        +  "TSLA",
        +  "NVDA",
        +  "IWM"
        +]
      • addedInput schema / properties / symbol / pattern
        Added value: +"^[A-Z][A-Z0-9.-]{0,15}$"
    • Changedget_monte_carlo3 fields changed
      • addedInput schema / properties / symbol / description
        Added value: +"Exchange ticker in uppercase, e.g. 'MSFT', 'NVDA', 'SPY'. Do NOT pass company names — use official tickers only."
      • addedInput schema / properties / symbol / examples
        Added value: +[
        +  "MSFT",
        +  "NVDA",
        +  "SPY"
        +]
      • addedInput schema / properties / symbol / pattern
        Added value: +"^[A-Z][A-Z0-9.-]{0,15}$"
    • Changedget_option_pressure3 fields changed
      • addedInput schema / properties / symbol / description
        Added value: +"Exchange ticker in uppercase, e.g. 'AAPL', 'SPY', 'NVDA'. Do NOT pass company names — use official tickers only."
      • addedInput schema / properties / symbol / examples
        Added value: +[
        +  "AAPL",
        +  "SPY",
        +  "NVDA"
        +]
      • addedInput schema / properties / symbol / pattern
        Added value: +"^[A-Z][A-Z0-9.-]{0,15}$"
    • Addedget_pretrade_risk_scan
  2. 8 tool updatesv0.1.0
    • First observedanalyze_stock
    • First observedgenerate_stock_images
    • First observedgenerate_stock_research_report
    • First observedget_ai_prediction
    • First observedget_equity_curves
    • First observedget_iv_radar
    • First observedget_monte_carlo
    • First observedget_option_pressure

TDQS

A4.6/5.0

Scored across 9 tools

Disambiguation5/5

Each tool targets a distinct aspect of stock/options analysis: aggregated analysis, chart generation, research reports, AI prediction, backtest curves, IV metrics, Monte Carlo simulation, options pressure, and pre-trade risk scan. Even the two comprehensive tools (analyze_stock and generate_stock_research_report) are clearly differentiated by output format (JSON vs. markdown) and recommended use cases.

Naming Consistency5/5

All 9 tools follow a consistent verb_noun pattern in snake_case: analyze_stock, generate_stock_images, generate_stock_research_report, get_ai_prediction, get_equity_curves, get_iv_radar, get_monte_carlo, get_option_pressure, get_pretrade_risk_scan. The verbs are appropriate and the naming is uniform.

Tool Count5/5

With 9 tools, the server is well-scoped for quantitative stock and options analytics. The tool count covers an aggregate analysis, specific data dimensions (AI, IV, Monte Carlo, options pressure, backtest, risk scan), and presentation (charts, reports) without unnecessary overlap or bloat.

Completeness5/5

The tool set provides comprehensive coverage for stock analysis and options analytics: directional prediction, volatility analysis, options positioning, Monte Carlo simulations, strategy backtests, risk scanning with portfolio context, and visualizations. There are no obvious gaps for the stated domain.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    An MCP server that exposes comprehensive Yahoo Finance data (quotes, financials, options, news, and more) to AI agents via the yfinance library, requiring no API key.
    24
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    Provides institutional-grade equity analysis for any LLM via MCP, aggregating insider trading, superinvestor holdings, analyst consensus, options data, and valuation into a confidence-weighted verdict.
    7
    MIT
  • A
    license
    B
    quality
    A
    maintenance
    The Finance Toolkit gives AI assistants access to 200+ financial metrics, all calculated transparently from raw financial statements, not pulled from third-party endpoints.
    26
    5,354
    MIT

Appeared in Searches