Skip to main content
Glama
erikmaday

unusual-whales-mcp

by erikmaday

Unusual Whales MCP Server

An MCP server that provides access to Unusual Whales market data - options flow, dark pool activity, congressional trades, and more. Works with any MCP-compatible client (Claude, or any LLM/application that supports MCP).

What You Can Do

Ask about the market using natural language:

  • "What's the options flow for AAPL today?"

  • "Show me the latest congressional trades"

  • "What's the dark pool activity for TSLA?"

  • "Get the max pain for SPY options expiring this Friday"

  • "What are institutions buying in the tech sector?"

  • "Give me a daily market summary"

  • "Deep dive on NVDA - options, dark pool, insider activity"

Available Data

Category

What's Included

Stock

Options chains, Greeks, IV rank, OHLC candles, max pain, open interest, volatility

Options

Contract flow, historic prices, intraday data, volume profiles

Flow

Options flow alerts, full tape, net flow by expiry, sector flow (mag7, semis, etc.)

Dark Pool

Dark pool transactions with filtering

Congress

Congressional trades, late reports, individual member activity

Politicians

Portfolios, recent trades, holdings by ticker

Insider

Insider transactions, sector flow, ticker flow

Institutions

13F filings, holdings, sector exposure, ownership

Market

Market tide, sector tide, economic calendar, FDA calendar, correlations

Earnings

Premarket and afterhours schedules, historical earnings

ETF

Holdings, exposure, inflows/outflows, sector weights

Shorts

Short interest, FTDs, short volume ratio

Seasonality

Market seasonality, monthly performers, ticker patterns

Screener

Stock screener, options screener, analyst ratings

News

Market news headlines

Built-in Analysis Prompts

The server includes many ready-to-use prompts. Just ask to use any prompt by name.

Market Overview

Prompt

Description

Example

daily-summary

Comprehensive market overview with tide, sectors, flow, dark pool

"Use the daily-summary prompt"

morning-briefing

Start the day with tide, earnings, and key activity

"Use the morning-briefing prompt"

end-of-day-recap

EOD summary with top movers, sectors, and themes

"Use end-of-day-recap"

weekly-expiration

Max pain, gamma, and OI for weekly expiration

"Use weekly-expiration for SPY, QQQ, IWM"

top-movers

Top tickers by net premium and options impact

"Use top-movers"

Ticker Analysis

Prompt

Description

Example

ticker-analysis

Deep dive on a stock with options, dark pool, insiders, catalysts

"Use ticker-analysis for NVDA"

options-setup

IV rank, term structure, max pain - is premium cheap or expensive?

"Use options-setup for TSLA"

pre-earnings

Historical moves, IV, positioning before earnings

"Use pre-earnings for AAPL"

greek-exposure

Gamma, delta, vanna exposure by strike

"Use greek-exposure for SPY"

short-interest

Short interest, FTDs, squeeze potential

"Use short-interest for GME"

option-contract

Deep dive on a specific option contract

"Use option-contract for AAPL240119C00150000"

correlation-analysis

Analyze correlations between tickers

"Use correlation-analysis for NVDA,AMD,INTC"

Flow & Activity

Prompt

Description

Example

unusual-flow

Scan for unusual options activity across the market

"Use unusual-flow with min_premium 500000"

dark-pool-scanner

Find large dark pool prints and institutional activity

"Use dark-pool-scanner"

sector-flow

Options flow sentiment for sector groups (mag7, semi, bank, etc.)

"Use sector-flow for semi"

Smart Money

Prompt

Description

Example

congress-tracker

Recent congressional trading with pattern detection

"Use congress-tracker"

politician-portfolio

Portfolio holdings and trades for a specific politician

"Use politician-portfolio for Nancy Pelosi"

insider-scanner

Scan for insider buying/selling patterns

"Use insider-scanner"

institutional-activity

13F filings, holdings changes, sector rotation

"Use institutional-activity for technology"

analyst-tracker

Analyst ratings with options flow correlation

"Use analyst-tracker"

Calendars & Events

Prompt

Description

Example

earnings-calendar

Earnings with IV, expected moves, and positioning

"Use earnings-calendar for this week"

fda-calendar

FDA events with biotech options activity

"Use fda-calendar"

economic-calendar

FOMC, CPI, jobs data with market positioning

"Use economic-calendar"

Screening & Discovery

Prompt

Description

Example

iv-screener

Find high or low IV rank stocks for options strategies

"Use iv-screener"

bullish-confluence

Stocks with bullish flow + dark pool + insider buying

"Use bullish-confluence"

bearish-confluence

Stocks with bearish flow + distribution + insider selling

"Use bearish-confluence"

news-scanner

Market news headlines with related flow

"Use news-scanner" or "Use news-scanner for TSLA"

Other

Prompt

Description

Example

seasonality

Historical seasonal patterns for a ticker or market

"Use seasonality for AAPL"

etf-flow

ETF inflows/outflows or find ETF exposure for a stock

"Use etf-flow for QQQ"

Combining Prompts

Chain prompts together for comprehensive analysis:

Use morning-briefing, then use unusual-flow to dig into the top movers
Use pre-earnings for NVDA, then use greek-exposure to see dealer positioning
Use bullish-confluence to find candidates, then use ticker-analysis on the top result

Related MCP server: quiver-quant-mcp

Getting Started

1. Get an API Key

Sign up at Unusual Whales and get your API key.

2. Install

Claude Code:

claude mcp add unusualwhales -e UW_API_KEY=your_api_key -- npx -y @erikmaday/unusual-whales-mcp

Claude Desktop:

Add to your config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unusualwhales": {
      "command": "npx",
      "args": ["-y", "@erikmaday/unusual-whales-mcp"],
      "env": {
        "UW_API_KEY": "your_api_key"
      }
    }
  }
}

3. Start Asking Questions

Once configured, just ask about the market. The Unusual Whales data will be used automatically.

Configuration (Optional)

The defaults work well for most users. All settings can be adjusted via environment variables:

Variable

Description

Default

UW_API_KEY

Your Unusual Whales API key

Required

UW_RATE_LIMIT_PER_MINUTE

Max requests per minute

120

UW_MAX_RETRIES

Retry attempts for failed requests

3

UW_CIRCUIT_BREAKER_THRESHOLD

Failures before pausing requests

5

UW_CIRCUIT_BREAKER_RESET_TIMEOUT

Milliseconds before retrying after failures

30000

The server automatically handles rate limiting, retries failed requests with backoff, and temporarily pauses requests if the API is having issues (circuit breaker). See CONTRIBUTING.md for technical details.

Contributing

See CONTRIBUTING.md for development setup, testing, and contribution guidelines.

License

MIT

Available Tools

16 tools
uw_alertsA
Read-onlyIdempotent

Access UnusualWhales user alerts and configurations.

Available actions:

  • alerts: Get triggered alerts for the user

  • configurations: Get alert configurations

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description ('Access') aligns with these and adds no new behavioral context. No annotation contradiction.

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 short and front-loaded with the purpose, followed by a concise bullet list. Every sentence is meaningful, though the bullets could be integrated.

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

Completeness3/5

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

Given no output schema, the description should hint at return structure. It only lists actions without describing what is returned (e.g., triggered alerts vs. configurations). A bit incomplete for a tool with no output schema.

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?

No parameters in the input schema, so the description need not explain any. The actions list provides context for what the tool does without requiring parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides access to user alerts and configurations, and lists two specific actions. It distinguishes itself from siblings which cover other financial data, but could be more specific about the resource (e.g., 'retrieve' instead of 'access').

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

Usage Guidelines3/5

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

Usage is implied by the sibling tools – all other tools cover different domains, so this is clearly for alerts. However, no explicit guidance on when to use it vs. alternatives, or prerequisites.

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

uw_congressB
Read-onlyIdempotent

Access UnusualWhales congress trading data including trades by congress members.

Available actions:

  • recent_trades: Get recent trades by congress members

  • late_reports: Get recent late reports by congress members

  • congress_trader: Get trades by a specific congress member (name required)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds no behavioral beyond listing actions. No additional context on data freshness, rate limits, or authorization.

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?

Description is short with clear list. Slightly inconsistent punctuation in bullet points (colons and parentheses), but overall efficient.

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

Completeness3/5

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

For a read-only tool with explicit actions, description is adequate. However, missing output schema and lack of parameters in schema leave ambiguity on how to invoke actions. The mention of a required parameter without schema support is a gap.

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

Parameters2/5

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

Input schema has zero parameters, but description mentions 'congress_trader' requires a name. This contradicts schema and could mislead agents. Schema coverage is 100% (no params), so description should not introduce undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states purpose: access congress trading data. Lists three actions. However, lacks explicit differentiation from sibling tools like uw_politicians, relying on name alone.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. The description lists actions but does not provide context for choosing this tool over other uw_ tools.

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

uw_darkpoolA
Read-onlyIdempotent

Access UnusualWhales darkpool trade data.

Available actions:

  • recent: Get recent darkpool trades across the market

  • ticker: Get darkpool trades for a specific ticker

Filtering options include premium range, size range, and volume range.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already indicate readOnly, openWorld, and idempotent behavior. The description adds context about actions and filters but no additional behavioral details beyond what annotations provide.

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?

Description is very concise, front-loaded with the purpose, and structured with bullet-style actions. Every sentence is informative without redundancy.

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?

For a tool with no input parameters and rich annotations, the description adequately covers purpose and available actions. It does not explain return values, but given simplicity, completeness is high.

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?

Input schema has no parameters, so schema coverage is 100%. Description mentions filtering options but adds no specific parameter details since none exist. Baseline score of 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 accesses UnusualWhales darkpool trade data and lists specific actions (recent, ticker). The name and context distinguish it from sibling tools which cover other data types.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. The description does not explain trade-offs or suggest when to choose uw_darkpool over other uw_* tools.

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

uw_earningsC
Read-onlyIdempotent

Access UnusualWhales earnings data including premarket and afterhours earnings schedules.

Available actions:

  • premarket: Get premarket earnings for a date

  • afterhours: Get afterhours earnings for a date

  • ticker: Get historical earnings for a ticker (ticker required)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.4/5.0
Behavior2/5

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

Annotations declare readOnlyHint, which is consistent with 'access' and 'get'. However, the description lists actions that would require parameters (e.g., date, ticker) but the schema has no properties, creating a behavioral inconsistency that undermines trust.

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?

The description uses a bullet list for actions, which is structured. However, the content is misleading due to the missing parameters, making it less efficient.

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

Completeness2/5

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

Without parameters or output schema, the description is incomplete. The three actions imply different input requirements, but none are defined, leaving the agent without enough information to use the tool correctly.

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

Parameters2/5

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

Schema coverage is 100% but the schema is empty. The description mentions actions that would typically need parameters but offers no way to pass them. This adds no value and confuses the agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it accesses UnusualWhales earnings data and lists three actions (premarket, afterhours, ticker), which gives a general idea. However, the lack of parameters in the input schema contradicts the implied need for date or ticker inputs, reducing clarity.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus siblings like uw_stock or uw_screener. There's no mention of prerequisites or context for each action, leaving the agent to guess.

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

uw_etfB
Read-onlyIdempotent

Access UnusualWhales ETF data including holdings, exposure, inflows/outflows, and weights.

Available actions:

  • info: Get ETF information (ticker required)

  • holdings: Get ETF holdings (ticker required)

  • exposure: Get ETFs that hold a ticker (ticker required)

  • in_outflow: Get ETF inflow/outflow data (ticker required)

  • weights: Get sector and country weights (ticker required)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3/5.0
Behavior1/5

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

The description claims 'ticker required' for all actions, but the input schema has zero parameters, creating a direct contradiction. Additionally, while annotations indicate read-only behavior, the description does not disclose the return format or any side effects. This is severely misleading.

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 uses a clear bullet-list structure to enumerate actions, making it easy to scan. The first sentence is somewhat generic, but overall it is efficient with no unnecessary fluff.

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

Completeness2/5

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

Given the tool has no output schema and multiple actions, the description fails to explain what each action returns or provide any example output. This leaves the agent with insufficient context to understand the response format, especially for an openWorldHint tool.

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

Parameters1/5

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

The input schema has no parameters (0 coverage), yet the description states 'ticker required' without it appearing in the schema. This misleads the agent into thinking a parameter exists when it does not. For zero-parameter tools, the baseline is 4, but the false claim warrants a 1.

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 accesses UnusualWhales ETF data and lists specific actions (info, holdings, exposure, etc.), differentiating it from sibling tools that cover other data categories like alerts, congress, darkpool, etc.

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 context by listing available actions, making it obvious when to use this tool (for ETF-related queries). However, it does not explicitly state when not to use it or mention alternatives, though the sibling list implies alternatives for other data types.

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

uw_flowA
Read-onlyIdempotent

Access UnusualWhales options flow data including flow alerts, full tape, net flow, group flow, and lit exchange flow.

Available actions:

  • flow_alerts: Get flow alerts with extensive filtering options

  • full_tape: Get full options tape for a date (date required)

  • net_flow_expiry: Get net flow by expiry date (date optional)

  • group_greek_flow: Get greek flow (delta & vega) for a flow group (flow_group required; date optional)

  • group_greek_flow_expiry: Get greek flow by expiry for a flow group (flow_group, expiry required; date optional)

  • lit_flow_recent: Get recent lit exchange trades across the market

  • lit_flow_ticker: Get lit exchange trades for a specific ticker (ticker required)

Flow groups: airline, bank, basic materials, china, communication services, consumer cyclical, consumer defensive, crypto, cyber, energy, financial services, gas, gold, healthcare, industrials, mag7, oil, real estate, refiners, reit, semi, silver, technology, uranium, utilities

Flow alerts filtering options include: ticker, premium range, volume range, OI range, DTE range, and more. Lit flow filtering options include: premium range, size range, volume range, and timestamp filters.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds context about the types of flow data and filtering options, which helps the agent understand what to expect without contradicting the annotations.

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?

The description is moderately structured with actions listed and notes on groups and filtering. However, it is somewhat verbose and could be more concise with clearer front-loading of essential information.

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

Completeness3/5

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

Given the lack of an output schema, the description should clarify the return format of each action. It describes what each action retrieves but not the structure. For a data retrieval tool, this is adequate but not complete.

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

Parameters2/5

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

The input schema has zero parameters, yet the description mentions several required parameters (e.g., date, flow_group, expiry) for specific actions. This creates confusion and inconsistency, undermining the usefulness of the description for parameter understanding.

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 identifies the tool as accessing UnusualWhales options flow data and enumerates specific actions (e.g., flow_alerts, full_tape). This distinguishes it from sibling tools focusing on other data types like alerts, congress, or darkpool.

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

Usage Guidelines3/5

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

While the description lists the available actions, it does not provide explicit guidance on when to use this tool over siblings or when to avoid it. Usage is implied by the mention of options flow data, but no exclusions or alternatives are given.

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

uw_insiderB
Read-onlyIdempotent

Access UnusualWhales insider trading data including transactions and flow.

Available actions:

  • transactions: Get insider transactions with filters. Use ticker_symbol for comma-separated tickers (e.g., AAPL,INTC)

  • sector_flow: Get aggregated insider flow for a sector (sector required)

  • ticker_flow: Get aggregated insider flow for a ticker (ticker required)

  • insiders: Get all insiders for a ticker (ticker required)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the tool's safety profile is clear. The description adds behavioral context by detailing the four actions and their parameter requirements. It does not disclose any additional side effects or limitations beyond what annotations imply.

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 organized with a bullet-type list for actions, making it scannable. It is reasonably concise, though the first sentence could be more direct. The front-loading is good, with the high-level purpose first, then details.

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

Completeness3/5

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

Given the tool's complexity (four distinct actions) and the absence of an output schema, the description adequately covers the actions and required parameters. However, it lacks information on output format, error handling, and prerequisites. The empty input schema is a significant gap that the description cannot fully compensate for.

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

Parameters2/5

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

The input schema is empty, but the description implies required parameters (ticker_symbol, sector, ticker) for specific actions. While the description adds semantics not present in the schema, the mismatch between description and schema creates confusion. This severely undermines the tool's usability for an AI agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides access to UnusualWhales insider trading data including transactions and flow. The verb 'access' and resource 'insider trading data' are specific. However, it does not differentiate from sibling tools like uw_flow or uw_stock, which may also provide similar data types.

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

Usage Guidelines3/5

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

The description lists available actions and specifies required parameters for each (e.g., ticker_symbol for transactions, sector for sector_flow). It provides some usage context but no guidance on when to choose this tool over siblings or when not to use it. Alternatives are not mentioned.

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

uw_institutionsC
Read-onlyIdempotent

Access UnusualWhales institutional holdings and ownership data.

Available actions:

  • list: List institutions with filters

  • holdings: Get holdings for an institution (name required)

  • activity: Get trading activity for an institution (name required)

  • sectors: Get sector exposure for an institution (name required)

  • ownership: Get institutional ownership of a ticker (ticker required)

  • latest_filings: Get latest institutional filings

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.2/5.0
Behavior2/5

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

Annotations indicate readOnlyHint, openWorldHint, and idempotentHint, which cover safety. The description adds no behavioral detail beyond action names, and contradicts the schema by implying parameters.

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?

The description is concise but the contradiction with the schema undermines its value. Front-loading is acceptable but misleading.

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

Completeness2/5

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

With no output schema and a schema with zero parameters, the description is incomplete. It does not explain how to specify the action (e.g., missing action parameter), leaving critical gaps.

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

Parameters1/5

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

Input schema has zero parameters, but description says actions like holdings require 'name'. This contradicts the schema, adding misleading semantics. Schema coverage is 100% but description does not align.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it accesses institutional holdings and ownership data, and lists available actions. However, the input schema has no parameters, while the description implies required parameters for actions (e.g., name, ticker), creating confusion about how to invoke the tool.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus sibling tools like uw_insider or uw_stock. The list of actions lacks context for selection.

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

uw_marketD
Read-onlyIdempotent

Access UnusualWhales market-wide data including market tide, sector ETFs, economic calendar, FDA calendar, and more.

Available actions:

  • market_tide: Get market tide data showing net premium flow (date optional; otm_only, interval_5m optional)

  • sector_tide: Get sector-specific tide (sector required; date optional)

  • etf_tide: Get ETF-based tide (ticker required; date optional)

  • sector_etfs: Get SPDR sector ETF statistics

  • economic_calendar: Get economic calendar events

  • fda_calendar: Get FDA calendar (announced_date_min/max, target_date_min/max, drug, ticker, limit optional)

  • correlations: Get correlations between tickers (tickers required; interval, start_date, end_date optional)

  • insider_buy_sells: Get total insider buy/sell statistics (limit optional)

  • oi_change: Get top OI changes (date, limit, order optional)

  • spike: Get SPIKE values (date optional)

  • top_net_impact: Get top tickers by net premium (date, issue_types, limit optional)

  • total_options_volume: Get total market options volume (limit optional)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1.9/5.0
Behavior2/5

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

Annotations (readOnlyHint, idempotentHint) are consistent with read operations, but the description inadequately addresses the mismatch between the listed actions (with parameters) and the empty input schema, creating confusion about actual behavior.

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

Conciseness2/5

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

The description is structured with bullet points but is lengthy and contains redundant detail. The content is not concise given the inaccurate relationship to the schema.

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

Completeness2/5

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

Despite listing many actions, the description lacks details on how to invoke them (no selector parameter), does not mention return values, and fails to explain the discrepancy with the input schema. Incomplete for a complex multi-action tool.

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

Parameters1/5

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

The input schema has no parameters (100% coverage), yet the description details actions with required/optional parameters. This adds misleading information that contradicts the schema, providing no helpful meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description lists many market-wide data actions (e.g., market_tide, sector_etfs) but the input schema is empty, providing no way to select an action. This makes the tool's purpose unclear and potentially misleading.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus sibling uw_* tools. The description implies many capabilities but does not differentiate or advise on selection criteria.

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

uw_newsC
Read-onlyIdempotent

Access UnusualWhales news headlines.

Available actions:

  • headlines: Get news headlines with optional filters (ticker, sources, search_term, major_only, page)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.4/5.0
Behavior2/5

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, but the description adds no extra behavioral context; worse, it mentions optional filters not present in the schema, contradicting the schema.

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?

Short description, but the action list is front-loaded; however, it is incomplete and misleading, reducing efficiency.

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

Completeness2/5

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

Given zero parameters in schema and no output schema, the description should specify the actual filtering mechanism; instead it misrepresents the input, leaving the agent confused.

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

Parameters1/5

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

Schema has zero parameters, but the description lists optional filters (ticker, sources, etc.) that are not in the schema, creating a contradiction; no value added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool accesses UnusualWhales news headlines, with a specific verb 'Access' and resource 'news headlines', distinguishing it from siblings.

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

Usage Guidelines2/5

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

No guidance on when to use this tool vs siblings like uw_market or uw_stock; the description does not provide context for selection.

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

uw_optionsA
Read-onlyIdempotent

Access UnusualWhales option contract data including flow, historic prices, intraday data, and volume profiles.

Available actions:

  • flow: Get option contract flow (id required; side, min_premium, limit, date optional)

  • historic: Get historic option contract data (id required; limit optional)

  • intraday: Get intraday option contract data (id required; date optional)

  • volume_profile: Get volume profile for option contract (id required; date optional)

The 'id' parameter is the option contract symbol (e.g., AAPL240119C00150000).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint as true. Description adds action-specific parameter dependencies but no behavioral traits beyond what annotations imply.

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?

Description is well-structured with bullet points for each action, efficient in length, and front-loaded with the main purpose.

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

Completeness3/5

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

Covers actions and parameters adequately, but lacks description of return values or output format, which is notable given no output schema.

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

Parameters2/5

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

Input schema is empty (0 parameters), yet description states 'id' is required and lists optional parameters for each action. This contradiction between description and schema reduces clarity. Schema coverage is 100% but only because schema has no parameters.

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?

Clearly states it accesses UnusualWhales option contract data and lists four specific actions (flow, historic, intraday, volume_profile), differentiating it from sibling tools that focus on other data types like alerts, congress, or darkpool.

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 detailed breakdown of each action with required and optional parameters, but does not explicitly state when to use this tool versus alternatives like uw_flow or uw_stock.

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

uw_politiciansA
Read-onlyIdempotent

Access UnusualWhales politician portfolio and trading data.

Available actions:

  • people: List all politicians

  • portfolio: Get a politician's portfolio (politician_id required; optional: aggregate_all_portfolios)

  • recent_trades: Get recent politician trades (optional: date, ticker, politician_id, filter_late_reports, disclosure_newer_than, disclosure_older_than, transaction_newer_than, transaction_older_than)

  • holders: Get politicians holding a ticker (ticker required; optional: aggregate_all_portfolios)

  • disclosures: Get annual disclosure file records (optional: politician_id, latest_only, year)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint as true, indicating a safe, read-only operation. The description adds value by detailing multiple actions and their parameter requirements, which goes beyond what annotations provide. No contradiction with annotations.

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 front-loaded with the purpose and then uses a bulleted list of actions. It is concise given the amount of information, but could be more structured (e.g., markdown sections). No verbosity.

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

Completeness2/5

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

The tool is complex with multiple actions and no output schema. The description does not explain how to specify the action (e.g., hidden action field) or describe return values. Annotation coverage is good, but for a tool with empty schema and many actions, the description leaves gaps for an agent to invoke it correctly.

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

Parameters2/5

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

The input schema is empty, but the description describes parameters for each action (e.g., politician_id required for portfolio). This mismatch creates confusion: an agent relying on the schema would see no parameters, yet the description requires them. The description adds meaning but conflict with schema reduces usability.

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 provides 'Access UnusualWhales politician portfolio and trading data' and lists specific actions (people, portfolio, recent_trades, holders, disclosures). This distinguishes it from siblings like uw_alerts or uw_congress, each focusing on different domains.

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

Usage Guidelines3/5

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

The description describes each action's purpose (e.g., 'Get recent politician trades') but does not explicitly state when to use this tool over alternatives or provide exclusions. The sibling list offers context, but within the description, usage guidance is implicit rather than direct.

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

uw_screenerB
Read-onlyIdempotent

Access UnusualWhales screeners for stocks, options, and analysts.

Available actions:

  • stocks: Screen stocks with various filters

  • option_contracts: Screen option contracts with filters

  • analysts: Screen analyst ratings

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds the available actions but does not disclose details like authentication, rate limits, or whether filters are optional. Minimal added value beyond annotations.

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?

Description is concise with a clear list of actions. However, it could be more compact by removing redundancy. Front-loaded with the tool's purpose.

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

Completeness2/5

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

No output schema exists, but the description does not explain return values or data format. Given the complexity of screening results, this omission leaves agents uncertain about what to expect.

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

Parameters1/5

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

Input schema has zero properties, yet description mentions 'various filters' for each action, implying parameters exist. This contradiction misleads about the tool's interface. The description fails to clarify the discrepancy.

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?

Description clearly states it accesses UnusualWhales screeners for stocks, options, and analysts, listing three specific actions. This differentiates it from sibling tools like uw_stock or uw_options.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. Sibling tools like uw_stock or uw_options may overlap, and the description does not clarify the distinction.

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

uw_seasonalityC
Read-onlyIdempotent

Access UnusualWhales seasonality data showing historical performance patterns.

Available actions:

  • market: Get market-wide seasonality data

  • performers: Get top/bottom performers for a month (month required, 1-12) Optional filters: min_years, ticker_for_sector, s_p_500_nasdaq_only, min_oi, limit, order, order_direction

  • monthly: Get monthly seasonality for a ticker (ticker required)

  • year_month: Get year-month breakdown for a ticker (ticker required)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.9/5.0
Behavior2/5

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

Annotations indicate readOnlyHint, openWorldHint, and idempotentHint, which align with the description's 'get' and 'show' language. However, the description claims parameters exist (e.g., month, ticker) while the schema has none, creating confusion about the tool's actual behavior.

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-organized with clear bullet points for actions. It is front-loaded with the overall purpose and then details each action. It could be slightly more concise, but the structure is effective.

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

Completeness2/5

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

Given the absence of an output schema and the complexity of multiple actions, the description provides reasonable context for each action. However, the empty input schema means the agent cannot correctly invoke the tool, leaving a critical gap in completeness.

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

Parameters2/5

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

The input schema has zero parameters, yet the description describes required and optional parameters for actions. This adds meaning beyond the schema but is inconsistent and misleading, as the agent cannot use these parameters based on the schema definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool accesses UnusualWhales seasonality data and lists four distinct actions (market, performers, monthly, year_month). It distinguishes itself from sibling tools like uw_alerts and uw_flow by focusing on seasonality patterns.

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

Usage Guidelines3/5

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

The description provides explicit details for each action, including required parameters (e.g., month for performers) and optional filters. However, it lacks guidance on when to use this tool versus others, and the mismatch with the empty input schema undermines usability.

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

uw_shortsA
Read-onlyIdempotent

Access UnusualWhales short selling data including short interest, FTDs, and volume.

Available actions:

  • data: Get short data for a ticker (ticker required)

  • ftds: Get failure to deliver data (ticker required)

  • interest_float: Get short interest as percent of float (ticker required)

  • volume_ratio: Get short volume and ratio (ticker required)

  • volumes_by_exchange: Get short volumes by exchange (ticker required)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior4/5

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

Annotations already indicate readOnly, openWorld, and idempotent hints. The description adds value by disclosing the multiple action types (data, ftds, etc.) and that each requires a ticker, which is behavioral context beyond annotations. No contradictions.

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 reasonably concise with a clear front-loaded purpose and bulleted actions, but each action repeats 'ticker required' unnecessarily. It is well-structured but could be more efficient.

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

Completeness2/5

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

Despite low complexity (no parameters, no output schema), the description fails to explain how to provide the required ticker, which is critical for using the tool. This omission makes the description incomplete for an AI agent.

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% (no parameters), so baseline is 3. The description adds meaning by listing actions and stating ticker is required, but there is a mismatch: the schema lacks a ticker parameter. This confusion reduces the helpfulness of the parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides UnusualWhales short selling data and lists specific actions (data, ftds, etc.), distinguishing it from sibling tools focused on other data types. However, it fails to explain how to specify the required ticker since the input schema has no parameters, creating ambiguity.

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

Usage Guidelines3/5

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

The description implies usage for short selling data through its verb and listed actions, but provides no explicit guidance on when to use this tool versus alternatives (e.g., uw_options, uw_darkpool) or any exclusions, leaving the agent to infer context.

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

uw_stockC
Read-onlyIdempotent

Access UnusualWhales stock data including options chains, greeks, IV, OHLC candles, open interest, and more.

Available actions:

  • info: Get stock information (ticker required)

  • ohlc: Get OHLC candles (ticker, candle_size required; date, timeframe, end_date, limit optional)

  • option_chains: Get option chains (ticker required; date optional)

  • option_contracts: Get option contracts (ticker, expiry required; option_type, filters, limit optional)

  • greeks: Get greeks data (ticker, expiry required; date optional)

  • greek_exposure: Get gamma/delta/vanna exposure (ticker required; date, timeframe optional)

  • greek_exposure_by_expiry: Get greek exposure by expiry (ticker required; date optional)

  • greek_exposure_by_strike: Get greek exposure by strike (ticker required; date optional)

  • greek_exposure_by_strike_expiry: Get greek exposure by strike and expiry (ticker, expiry required; date optional)

  • greek_flow: Get greek flow (ticker required; date optional)

  • greek_flow_by_expiry: Get greek flow by expiry (ticker, expiry required; date optional)

  • iv_rank: Get IV rank (ticker required; date, timespan optional)

  • interpolated_iv: Get interpolated IV (ticker required; date optional)

  • max_pain: Get max pain (ticker required; date optional)

  • oi_change: Get OI change (ticker required; date, limit, page, order optional)

  • oi_per_expiry: Get OI per expiry (ticker required; date optional)

  • oi_per_strike: Get OI per strike (ticker required; date optional)

  • options_volume: Get options volume (ticker required; limit optional)

  • volume_oi_expiry: Get volume/OI by expiry (ticker required; date optional)

  • atm_chains: Get ATM chains for given expirations (ticker, expirations required)

  • expiry_breakdown: Get expiry breakdown (ticker required; date optional)

  • flow_per_expiry: Get flow per expiry (ticker required)

  • flow_per_strike: Get flow per strike (ticker required; date optional)

  • flow_per_strike_intraday: Get intraday flow per strike (ticker required; date, filter optional)

  • flow_recent: Get recent flow (ticker required; side, min_premium optional)

  • net_prem_ticks: Get net premium ticks (ticker required; date optional)

  • nope: Get NOPE data (ticker required; date optional)

  • stock_price_levels: Get stock price levels (ticker required; date optional)

  • stock_volume_price_levels: Get volume price levels (ticker required; date optional)

  • spot_exposures: Get spot exposures (ticker required; date optional)

  • spot_exposures_by_expiry_strike: Get spot exposures by expiry/strike (ticker, expirations required; date, filters optional)

  • spot_exposures_by_strike: Get spot exposures by strike (ticker required; date, filters optional)

  • spot_exposures_expiry_strike: Get spot exposures for specific expiry (ticker, expirations required; date, strike filters optional)

  • historical_risk_reversal_skew: Get risk reversal skew (ticker, expiry, delta required; date, timeframe optional)

  • volatility_realized: Get realized volatility (ticker required; date, timeframe optional)

  • volatility_stats: Get volatility stats (ticker required; date optional)

  • volatility_term_structure: Get term structure (ticker required; date optional)

  • stock_state: Get stock state (ticker required)

  • insider_buy_sells: Get insider buy/sells for stock (ticker required; limit optional)

  • ownership: Get ownership data (ticker required; limit optional)

  • tickers_by_sector: Get tickers in sector (sector required)

  • ticker_exchanges: Get mapping of all tickers to their exchanges (no params required)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.1/5.0
Behavior1/5

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

The description implies parameters (ticker, expiry, etc.) but the input schema declares no properties, creating a direct contradiction. Annotations indicate read-only and idempotent behavior, but the description fails to address this mismatch or other behavioral traits like rate limits.

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?

The description is front-loaded with the purpose but becomes verbose with a long list of 30+ actions. Each line is informative, but the overall length could overwhelm an agent. Structure is clear but not concise.

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

Completeness2/5

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

Despite covering many actions, the description omits the parameter structure (missing from schema), return format, usage examples, and authentication needs. For a complex tool with no output schema, this is insufficient.

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?

With zero parameters in the schema, baseline is 4 according to rules. The description adds rich parameter info for each action (e.g., ticker required, optional filters), but these are not formalized in the schema, reducing reliability. Overall, it adds value but is inconsistent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool accesses UnusualWhales stock data, but the input schema has no properties, contradicting the detailed parameter requirements listed for each action. This inconsistency undermines clarity, making it unclear what the agent should send.

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

Usage Guidelines2/5

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

The description lists many actions but provides no guidance on when to use this tool versus sibling tools like uw_options or uw_flow. No context on use cases or exclusions is given.

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. 16 tool updatesv0.3.0
    • First observeduw_alerts
    • First observeduw_congress
    • First observeduw_darkpool
    • First observeduw_earnings
    • First observeduw_etf
    • First observeduw_flow
    • First observeduw_insider
    • First observeduw_institutions
    • First observeduw_market
    • First observeduw_news
    • First observeduw_options
    • First observeduw_politicians
    • First observeduw_screener
    • First observeduw_seasonality
    • First observeduw_shorts
    • First observeduw_stock

TDQS

B3.3/5.0

Scored across 16 tools

Disambiguation4/5

The tools are grouped into distinct categories (alerts, congress, darkpool, etc.), but some overlap exists between uw_flow, uw_options, and uw_stock regarding options data, which could cause misselection by an agent.

Naming Consistency5/5

All tool names follow a consistent 'uw_<category>' pattern with lowercase nouns, making it predictable and easy to understand.

Tool Count5/5

With 16 tools covering a wide range of financial data, the count is well-scoped for the server's purpose, providing comprehensive coverage without being excessive.

Completeness5/5

The server covers a comprehensive set of financial data domains (alerts, congress, darkpool, earnings, ETFs, flow, insider, institutions, market, news, options, politicians, screener, seasonality, shorts, stocks), leaving no obvious gaps for its intended use.

Maintenance

ActivityActive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    C
    quality
    D
    maintenance
    Provides access to the Unusual Whales API for real-time financial data, options flow analysis, dark pool activity, and congressional trading tracking. It enables users to perform comprehensive market intelligence and stock analysis across 33 different tools.
    33
    17 npm
    4
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables querying alternative financial data including congressional trades, insider transactions, government contracts, and WallStreetBets activity through the Quiver Quantitative API.
    1
    -
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables querying of U.S. congressional stock trade data, including price history, recent trades, buy signals, stock activity, and politician activity, through natural language tools.
    1
    MIT