Skip to main content
Glama

Kaleidoscope MCP (SEC & financial data)

Short Interest (FINRA biweekly panel — shares short, days to cover, squeeze/spike flags)

short_interest
Read-onlyIdempotent

FINRA short interest history for a ticker — biweekly settlement-date panel since 2021-06-15. Returns shares short, days to cover, and mars's own pre-computed signal flags (squeeze_setup, short_spike, short_covering, short_extreme, short_zscore_high) per settlement, newest first.

Ticker is the join key (CIK resolves on only ~37% of rows in the source panel) — the tool tries the ticker as given, then with punctuation stripped (BRK.B / BRK-B -> BRKB), since FINRA's own ticker spelling in this feed doesn't always match ours.

NOT YET computed: % of shares outstanding / % of float (the source panel has raw shares short + avg daily volume but not a shares-outstanding join — days_to_cover and the flag fields are the best available signal today; a %OS/%float enrichment is a follow-up, not silently guessed here).

Known limitation: ticker symbol reuse (e.g. a delisted company's old ticker reassigned to a new one, as happened with META) is not detected — a long history pull may silently splice two different companies' data if the ticker was reused. Cross-check against the company's known listing history if the early history looks inconsistent with the company you mean.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "ticker": "<ticker>"
    },
    "name": "short_interest"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax settlement rows to return, newest first (default 60, max 300).
sinceNoEarliest settlement_date YYYY-MM-DD (default: full history since 2021-06-15).
tickerYesStock ticker (required — this panel is ticker-keyed, not reliably CIK-keyed).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: the ticker-as-given then punctuation-stripped resolution order (BRK.B → BRKB), newest-first ordering, an explicit statement that %OS/%float is NOT yet computed and will not be silently guessed, and a data-integrity warning that ticker symbol reuse can silently splice two companies' histories. These are exactly the caveats an agent cannot get from structured fields.

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 first sentence is front-loaded with the verb, resource, cadence, and return fields, and the paragraphs are labeled by concern (ticker keying, missing metric, known limitation). It is somewhat long and contains rough phrasing ('mars's own pre-computed signal flags') and parenthetical nesting, but every block carries real information for the caller.

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?

There is no output schema, so the description carries the return-value burden and does so: it lists the returned measures and names each flag field. Combined with the scaling note (limit default 60, max 300) in the schema, the keying caveats, and the explicit gap disclosure, an agent has everything needed to call this correctly and to interpret the results cautiously.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents limit, since, and ticker. The description still earns above baseline by explaining why ticker is the join key (CIK resolves on only ~37% of rows) and describing the normalization fallback, and by noting that since defaults to full history from the panel start. It adds genuine semantics rather than restating the schema.

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 names a specific verb and resource — FINRA short interest history for a ticker, biweekly settlement-date panel since 2021-06-15 — and enumerates the returned fields (shares short, days to cover, named flag fields). An agent can tell this is a short-interest time series rather than a price or volume tool. It stops short of 5 because it never names or contrasts the sibling short_volume, leaving the interest-vs-volume distinction for the agent to infer.

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 context is implied rather than stated: it explains that days_to_cover and the flags are the best available signal today because %OS/%float isn't computed, which nudges the agent toward this tool for squeeze-style signals. There is no explicit when-to-use/when-not and no named alternative to route to for daily short volume or for float-based metrics. The ticker-reuse cross-check caveat is a data-quality instruction, not selection guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources