Pinegap

Retrieves a comprehensive post-earnings analysis for a completed earnings period. Provides AI-synthesized insights on financial results, beat/miss metrics, and key takeaways from the earnings call. This tool analyzes earnings call transcripts and press releases to extract: (1) a narrative summary of key earnings themes and management commentary, (2) a detailed metrics table comparing actual results vs consensus expectations with beat/miss percentages for revenue, EPS, and other key metrics, and (3) additional summary insights about guidance and performance drivers. **How it works:** - You provide the COMPLETED period you want a recap for - The tool retrieves the earnings analysis for that period - Returns structured data with narrative takeaways and quantitative metrics - Example: Pass Q4 2024 → Get recap of Q4 2024 earnings call **Input Behavior:** - If year is omitted, uses the latest available period automatically - quarter is required when year is provided (for quarterly reporters) - half is required when year is provided (for semi-annual reporters) - generate defaults to false - generate=false: returns stored recap only; if none exists yet, recap fields are empty - generate=true: returns stored recap when present; if none exists yet, enqueues recap generation **Output Contents:** - ticker, period: Identifiers for the earnings call analyzed - takeaway: AI-generated narrative summary highlighting key themes, surprises, and management commentary from the earnings call - table: Structured metrics table with rows containing Actual vs Consensus values, Beat/Miss percentages, and optional Guidance for key financial metrics (Revenue, EPS, EBITDA, etc.) - summary: Additional summary insights about the quarter's performance and forward guidance; includes inline [n] markers when citations are available - summaryCitations: Optional citations matching the inline [n] markers in the summary text **Example Usage:** - Recap AAPL's Q4 2024 earnings: `{ ticker: "AAPL", year: 2024, quarter: 4 }` - Recap latest available: `{ ticker: "AAPL" }` (auto-resolves to latest completed period)

earnings-recap

Returns a structured post-earnings scorecard covering price reactions, beat/miss metrics, estimate revisions, and guidance direction for an earnings period, for one or more tickers at once. **Input Behavior:** - tickers is required (one or more). - year/quarter/half optional; omitting year auto-resolves each ticker's latest period - quarter required with year for quarterly reporters; half required for semi-annual reporters - metricsOnly (default false): when true, skips the AI key-debates / guidance-commentary generation and returns ONLY the numeric scorecard (beat/miss, estimate revisions, price reactions, implied move). Much faster — no GPT calls. Use this for dashboards that only render the numeric cells. **Output Contents (per ticker, under results[]):** - status: ready | not_found (no earnings call) | error (fetch failed) - Ticker, Sector, Industry, Earnings Quarter - 1-D Reaction, 5-D Reaction: post-earnings price performance - Implied Move: options-implied earnings-day move from ATM straddle - Metric (Beat/Miss): Revenue, EBITDA, EBIT, EPS vs consensus - Estimate Revisions Next Quarter: EBIT, EPS revisions - Estimate Revisions Current Year: EBIT, EPS revisions - Guidance: overall direction (raised/lowered/maintained/unclear) - Guidance Commentary: narrative guidance summary - Key Debates: key debate points distilled from earnings commentary - Guidance, Guidance Commentary, Key Debates: omitted when metricsOnly is true **Example Usage:** - `{ tickers: ["NVDA", "AAPL"] }` (latest period, full) - `{ tickers: ["NVDA"], year: 2025, quarter: 1 }` - `{ tickers: ["NVDA", "AAPL", "MSFT"], metricsOnly: true }` (fast, numbers only) - Optional `agentUserTopologyId`: when provided, metric (beat/miss) and estimate revisions use topology-specific columns

earnings-takeaway

Generates detailed profiles for the C-Suite leadership team using multiple data sources. **How it works:** - Synthesizes data from Proxy Statements - Checks 8-K filings for recent leadership changes - Incorporates web research for background and prior roles **Output Contents:** - ticker: Stock symbol queried - data: Executive bios and ownership/governance analysis content **Example Usage:** - Get management team for Apple: `{ ticker: "AAPL" }`

executive-bios

Retrieves a company document's full text — earnings call transcripts, press releases, 10-K/10-Q, 8-K, SEC filings (Form 3/4/5/13F), and more — for reading, quoting, and analysis. By default it returns the actual document text; it only returns a link instead when you explicitly ask for one. Fetch either by documentIds (exact stored documents) or by ticker + documentTypes (with optional periods). **Two ways to call:** - **By documentIds** — an array of stable ids (the ones carried on citations and on other tools' output). This is how you re-open sources after authenticated citation links expire — and you can pass MANY at once to fetch them in parallel instead of one call at a time. Cannot be combined with ticker/documentTypes/periods. - **By ticker + documentTypes** — resolves documents for that company. `documentTypes` is an array; `periods` is an optional array of `{ year, quarter?, half? }`. Omit `periods` to get the latest of each type. **One content response vs. an array — you choose by how many you ask for:** - **A single request** (one documentId, or one documentType with at most one period) → returned as paginatable `content` (text). Usually one document — but a type with many per period (8-K, Form 3/4/5) or a year given without a quarter concatenates all matching documents into that one response with section markers. Use `page`/`paginate` to read it in parts. This is the mode for reading/quoting. - **Several requests** (multiple documentIds, or multiple documentTypes/periods) → a structured `documents[]` array, one entry per resolved document (each with its own metadata + full text), **never paginated**. This is the mode for pulling a set at once (an earnings package, a multi-year time-series, or a batch of cited sources) with fewer calls. - to read one document in parts, use page/paginate on a single-document request. A multi-document request always returns whole documents, so paginate:true (or a page past the first) is rejected with CONFLICTING_PARAMETERS — omit them, or pass paginate:false (which is compatible: it also means "the whole thing"). **How it works:** - documentIds resolve exactly the stored documents you name — no siblings, no fallback. - ticker mode locates documents by ticker, type, and period. For the rare companies that store an earnings call as separate rows (e.g. Prepared Remarks + Q&A — most companies use a single row), those rows are concatenated with section markers within the one document. - for 10-K / 10-Q / DEF-14A, if nothing is stored for an explicitly requested year, ticker mode falls back to a live SEC EDGAR fetch. Those live results have no documentId (they aren't stored) and can't be re-fetched by id. - 8-K and SEC filing forms (Form 3/4/5/13F) are fetched as SEC filings rather than from the stored document table, so they are ticker-mode only, carry no documentId, and are not retrievable by id. metadata.documentId is present only for stored documents that can be re-fetched. **Input Behavior:** - Provide either documentIds, or a ticker with documentTypes. Supplying neither returns MISSING_REQUIRED_FIELD. - documentIds cannot be combined with ticker, documentTypes, or periods → CONFLICTING_PARAMETERS. Repeated ids are fetched once; a single call is capped at a fixed number of ids (split larger sets into batches). - Each (type, period) pair must be valid: quarter and half are mutually exclusive; a 10-Q requires a quarter; 10-K, DEF-14A, 8-K, and Form 3/4/5/13F take only a year (no quarter/half). An invalid pair fails the whole call, naming the offending item. The request is capped at a fixed number of (type × period) items — narrow documentTypes/periods if you exceed it. - deliveryMode defaults to "content" and you should keep it there for anything that involves reading, quoting, or analyzing the document. Only choose "viewer" (a browser link) or "download" (a file) when the user explicitly asks to open or download; those return a URL ONLY and NO text. "download" bundles multiple documents into one ZIP; "viewer" supports a single render family at a time (documents that render differently can't be one link). - Multi-document results are bounded by document-count caps; when a set exceeds them the response is truncated (truncated:true) with specifics in `message`, and sub-requests that matched nothing or failed to fetch are listed in `notFound`/`failures`. In ticker mode, EDGAR-sourced documents (8-K, Forms, and live SEC fallbacks) have a tighter cap than DB-served documents. **Output Contents:** - mode: "content" (single document), "content_batch" (document array), "viewer_link", or "download_link" - metadata: documentsCount, and per document: ticker, documentType, year, quarter/half, subType, releaseDate, title, and documentId (present only for stored documents re-fetchable by id — omitted for 8-K/Forms and live-SEC results) - content: the requested page of text (or full text with `paginate: false`) in single "content" mode. Empty string in "content_batch" and link modes. - documents: "content_batch" mode only — an array of resolved documents, each with its own metadata + full text. metadata.documents is a lightweight index of the same set. - notFound / failures: "content_batch" mode only — sub-requests (or ids) that matched nothing, or documents found but not fetchable. - pagination: page, totalPages, hasMore, and character counts (single paginated content mode only) - truncated: single mode → true if more pages remain; batch mode → true if some documents were dropped to stay within the caps; always false in `paginate: false` and link modes - viewer (deliveryMode "viewer"): a standalone viewer URL for reading the document in the browser; the viewer includes its own Download button - download (deliveryMode "download"): a direct file/ZIP download URL for the original document source - message: status hint (e.g. pagination guidance, or when no documents are found) **Example Usage:** - Re-open a citation's source by id: `{ documentIds: [821453] }` - Read the next page of that document: `{ documentIds: [821453], page: 2 }` - Open it in the browser viewer: `{ documentIds: [821453], deliveryMode: "viewer" }` - Re-fetch several cited sources at once (document array): `{ documentIds: [821453, 821777, 830012] }` - A specific earnings call (one document, paginatable): `{ ticker: "AAPL", documentTypes: ["Earnings call"], periods: [{ year: 2024, quarter: 3 }] }` - Second page of the latest 10-K: `{ ticker: "MSFT", documentTypes: ["10K"], page: 2 }` - Latest 10-K as one full-text response: `{ ticker: "MSFT", documentTypes: ["10K"], paginate: false }` - 10-Ks across three years (document array): `{ ticker: "AAPL", documentTypes: ["10K"], periods: [{ year: 2021 }, { year: 2022 }, { year: 2023 }] }` - The full Q3 2024 earnings package (document array): `{ ticker: "AAPL", documentTypes: ["Earnings call", "Press Release", "Earnings Presentation"], periods: [{ year: 2024, quarter: 3 }] }` - Download bundle (one ZIP): `{ ticker: "AAPL", documentTypes: ["Earnings call", "Press Release"], periods: [{ year: 2024, quarter: 3 }], deliveryMode: "download" }`

fetch-document

Converts a parameter ID (pid) to a Pinegap Data ID (pgid / pinegapDataId), or matches a ticker+query to relevant metrics (at most 3) and returns their pgids. **Input Behavior:** - mode optional: encode when pid is set, match when ticker+query are set - encode requires pid; match requires ticker and query - match returns 1-3 results: a clear exact match may return a single metric; only returns more when the query is ambiguous **Output Contents:** - encode: pid, pgid - match: ticker, query, matches[{ rank, pid, pname, pgid }] **Example Usage:** - `{ pid: 30 }` - `{ ticker: "AAPL", query: "gross margin" }`

fetch-pgid

Flags financial and accounting risks from the latest 10-K/10-Q, Annual Report, Interim Report, or Annual Financial Statement, including liquidity stress, earnings-quality issues, aggressive accounting or non-GAAP adjustments, control weaknesses, covenant pressure, and balance-sheet impairment triggers. **How it works:** - Resolves the latest annual filing and latest 10-Q, then selects the most recent by release date - Checks existing RedFlag and AgentData records for the latest document - Generates analysis if no usable data is found or previous runs failed, unless generate is false **Input Behavior:** - Uses the most recent 10-K/10-Q, Annual Report, Interim Report, or Annual Financial Statement by release date - generate defaults to true. When false, returns a completed stored report or a not-found error without generating. **Output Contents:** - scope: "financial" - source: Where the analysis came from (red_flag_table, agent_data, generated) - documentType: The document type actually used for analysis - redFlags: Financial red flag assessments with prior-period context **Example Usage:** - Latest financial red flags: `{ ticker: "AAPL" }` - Stored report only: `{ ticker: "AAPL", generate: false }`

red-flag-financial

Unified access to hedge-fund investor letters — holdings, macro and sector views, and the letters themselves. **How it works:** - positions: Company-level holdings extracted from letters (direction, status, thesis, catalysts, risks), optionally scoped to ticker(s) - macro: Macro views extracted from letters (rates, inflation, geopolitics, …) - themes: Sector and cross-sector theme views extracted from letters - list-letters: The documents themselves, optionally scoped to ticker(s) or funds - list-funds: Fund names in the window, for discovering the `funds` filter - get-letter: One letter's metadata and extracted summary, by id - get-document: A short-lived PDF URL for one letter **Which mode to use:** - Use positions when the user asks what funds said about a stock, who is long/short, or for a thesis on a holding - Use macro when the question is about rates, inflation, geopolitics, or other macro views across managers - Use themes when the question is about a sector or a cross-stock theme - Use list-letters to browse or cite the underlying documents; use get-letter for one document's summary; use get-document for the PDF - Use list-funds first when the user names a manager and you need the exact fund string the other modes filter on **Input Behavior:** - mode is always required - Lookback: `periodUnit` is days, weeks, quarters, or years. `periods` defaults to 4 and `periodUnit` defaults to quarters - days / weeks count calendar time from when the letter was published (`sourceCreatedAt`, then `letterDate`). Use these for "what funds said about NVDA in the past week / last 2 days". days max 365, weeks max 52 - quarters / years count closed reporting periods, not calendar time. Letters report on a closed quarter and publish weeks later, so on 3 September the newest letters are Q2. A year is four quarters. Max 20 - For positions and list-letters, provide at most one of `ticker` or `tickers`; supplying both is rejected. Omitting both browses unfiltered - `ticker` / `tickers` are ignored in macro, themes, list-funds, get-letter, and get-document — those modes are not company-scoped - Pagination defaults to limit 50, offset 0, capped at 200 - `get-letter` and `get-document` require `letterId` - `funds` is an exact, case-insensitive match on the stored fund name. Use list-funds to discover names; several funds contain commas, so pass them as array elements rather than a comma-joined string **Output Contents:** - positions / macro / themes: insight rows with fund, dates, thesis or view, and a durable `link` that opens the letter in the app - letters: document list with id, fund, dates, page count, and `link` - funds: fund names plus letter counts in the window - letter: one document's metadata, extracted summary, manager/firm, and `link` - document: `pdfUrl` (expires in expiresInSeconds — do not cite it) plus durable `link` - metadata: count, totalCount, pagination, lookback, and notFoundTickers for unresolved symbols **Example Usage:** - What funds said about a stock: `{ mode: "positions", ticker: "MSFT" }` - Insights published in the last 2 days: `{ mode: "positions", ticker: "NVDA", periodUnit: "days", periods: 2 }` - Insights published in the past week: `{ mode: "positions", ticker: "NVDA", periodUnit: "weeks", periods: 1 }` - Longs initiated in the last year: `{ mode: "positions", ticker: "MSFT", directionStatus: ["long_initiated"], periodUnit: "years", periods: 1 }` - Macro views on rates: `{ mode: "macro", domain: ["rates", "monetary_policy"] }` - Sector views: `{ mode: "themes", sector: ["information_technology"], scope: ["sector"] }` - Letters mentioning a stock: `{ mode: "list-letters", ticker: "MSFT" }` - Discover fund names: `{ mode: "list-funds" }` - One letter: `{ mode: "get-letter", letterId: 5468 }` - PDF URL: `{ mode: "get-document", letterId: 5468 }`

fund-letters

Surfaces corporate governance and shareholder-rights red flags from proxy disclosures (DEF-14A), including board independence/oversight issues, problematic pay practices, related-party transactions, weak say-on-pay signals, and anti-shareholder provisions. **How it works:** - Resolves the latest DEF-14A for the ticker (optional fallback to annual/20-F if enabled) - Checks existing RedFlag and AgentData records for the latest document - Generates analysis if no usable data is found or previous runs failed, unless generate is false **Input Behavior:** - allowAnnualFallback defaults to false - When enabled, falls back to ANNUAL_10K → TWENTY_F → ANNUAL_REPORT if no DEF-14A exists - generate defaults to true. When false, returns a completed stored report or a not-found error without generating. **Output Contents:** - scope: "governance" - source: Where the analysis came from (red_flag_table, agent_data, generated) - documentType: The document type actually used for analysis - redFlags: Governance-focused red flag assessments with prior-period context **Example Usage:** - DEF-14A only: `{ ticker: "AAPL" }` - Allow annual fallback: `{ ticker: "AAPL", allowAnnualFallback: true }` - Stored report only: `{ ticker: "AAPL", generate: false }`

red-flag-governance

Verifies the MCP server is running and its dependencies (database) are connected. Use this tool to diagnose connectivity issues or verify the server is operational before making other requests. **Output Contents:** - status: Server health status ('ok', 'degraded', or 'error') - dbConnected: Whether the database connection is active - timestamp: ISO 8601 timestamp of the health check - version: MCP server version string

health

Fetches historical daily prices for a ticker. **How it works:** - Resolves the best-available market symbol from the internal database (if present) - Requests daily price history from the market data provider - Returns OHLC and volume fields per trading day **Input Behavior:** - startDate and endDate are optional filters for the returned history - If the ticker exists internally with a mapped market symbol, that symbol is used - Otherwise, the provided ticker is queried directly **Output Contents:** - ticker: The requested ticker - symbol: The market symbol used for the lookup - startDate/endDate: Filter window applied to the history - prices: Daily price entries with OHLC and volume fields - message: Present when no price history is found **Example Usage:** - Full history: `{ ticker: "AAPL" }` - Date range: `{ ticker: "AAPL", startDate: "2024-01-01", endDate: "2024-06-30" }`

historical-prices

Retrieves the most discussed topics and key debates from earnings calls, for one or more tickers at once. These are the themes and topics that management and analysts focused on during the call, identifying what was truly important to the investment community about the company's performance and outlook. This tool analyzes earnings call transcripts to extract: (1) the most discussed topics identified through frequency analysis and importance weighting, (2) summaries of what was said about each topic, (3) citations with clickable links to view the source text in the document, and (4) supporting context about why each topic mattered during that earnings call. **How it works:** - You provide one or more tickers and (optionally) the COMPLETED earnings period to analyze - Each ticker is resolved and processed independently; one ticker failing never fails the rest - Returns structured topics with their discussion summaries and citations per ticker - Each citation includes a clickable link to view the source text with highlighting **Input Behavior:** - tickers is required (one or more). - If year is omitted, each ticker uses its latest available period automatically - quarter is required when year is provided (for quarterly reporters) - half is required when year is provided (for semi-annual reporters) **Output Contents:** - results: one entry per requested ticker (in order), each with: - status: ready (debates returned) | not_found (no debates / no earnings call) | error (lookup failed) - ticker, period: Identifiers for the earnings call analyzed - keyDebates[]: Array of key debate topics, each containing: - topic: The debate topic name - summary: Discussion summary with inline [n] citation markers already embedded - tag: Optional tag (e.g., "most_discussed") - citations[]: 1-indexed per-debate citations — each has index, quote, doc_type, doc_date, and link - renderHints: Rendering guidance for how to display citations inline - message: Helpful message if no debates were found **Citation rendering:** - Each debate's summary already embeds inline [n] markers (e.g., "Copilot usage is growing [1].") - Indices are per-debate and reset to 1 for each new topic — [n] maps to that debate's citations[n-1] - Hyperlink each [n] to citations[n-1].link, displayed as [n] or [View Source] - Do not renumber citations globally or collect them in a block at the end **Example Usage:** - Get key debates for a watchlist: `{ tickers: ["AAPL", "MSFT", "NVDA"] }` (latest period each) - Specific period: `{ tickers: ["AAPL"], year: 2024, quarter: 4 }`

key-debates

Returns fiscal period information for a ticker. Two modes: **Mode 1 - Get Latest Period** (no year/quarter/half provided): Returns the most recent fiscal period for which content is available. Defaults to earnings calls; if the latest earnings call is more than 100 days old, also checks the latest press release and returns whichever is more recent. Pass an explicit documentType to retrieve the latest period for that document type only. **Mode 2 - Check Period Exists** (year + quarter/half provided): Checks whether a document exists for the specified period. Defaults to earnings calls; pass documentType to check a different document type. **Input Behavior:** - To retrieve the latest period, omit year, quarter, and half together - If year is provided, switches to existence-check mode and requires exactly one of quarter or half - Use quarter for quarterly reporters or half for semi-annual reporters; never provide both **Output Contents:** - ticker, documentType: Echo of query parameters - mode: "latest" or "exists" depending on whether year was provided - exists: Whether the period/document was found - period: Object with year, quarter (null if semi-annual), half (null if quarterly), and formatted periodString (e.g., "Q4 2024") - document: (latest mode only) Details of the most recent document including id, title, and releaseDate - message: Status message when not found **Example Usage:** - Latest earnings period: `{ ticker: "NVDA" }` - Latest period for one document type: `{ ticker: "NVDA", documentType: "Press Release" }` - Check a quarterly period: `{ ticker: "NVDA", year: 2027, quarter: 2 }` - Check a semi-annual period: `{ ticker: "SHEL", year: 2026, half: 1 }`

latest-period

Returns financially material news for one or more tickers over a lookback window. Checks stored news first; if generate is not false, falls back to AI generation for tickers with no stored news. **Input Behavior:** - tickers is required and accepts a JSON array, e.g. ["AAPL", "MSFT"] - tickers accepts up to 5 symbols in all modes - generate defaults to true: stored news first, then AI generation for missing news - generate:false enables stored-news-only mode with no AI calls - Even with generate:true, stored news is always served when available; AI is only called for tickers with no stored news in the requested window - days defaults to 1 (last 24 hours) **Output Contents (per ticker, under results[]):** - status: ready (lookup completed) | not_found (no stored news when generate:false) | error (fetch failed) - ticker: The queried stock symbol - companyName: Resolved company name; invalid ticker rows use "Invalid ticker" - days, startDate: Lookback window used - filtered: Filtered, sentiment-labelled news ranked by materiality; absent when no relevant news in the window - message: Present when no news found or on per-ticker error; for not_found with generate:false, suggests calling with generate:true **Example Usage:** - Single ticker: `{ tickers: ["AAPL"] }` - Single ticker, 3 days: `{ tickers: ["MSFT"], days: 3 }` - Multi-ticker, AI fallback: `{ tickers: ["AAPL", "MSFT"], days: 3 }` - Large watchlist, stored-news-only: `{ tickers: ["AAPL", "MSFT"], generate: false }` - Generate missing news after stored-news lookup: `{ tickers: ["AAPL"], generate: true }`

ticker-news

Lists available conference coverage across all companies — every conference-related document we have, optionally narrowed by ticker, fiscal period, or release-date range. Use this to discover what conference coverage exists before reaching for `conference-recap` or `conference-takeaways`. **Document types surfaced:** Conference, Analyst Day, Analyst Day Docs, Investor Day, Investor Day Docs, Capital Markets Day, Capital Markets Day Docs. **Not included:** annual general meetings and earnings calls are separate document types and are NOT returned here — a ticker with only those (e.g. some non-US names) correctly returns no results. **Input Behavior:** - All filters are optional. With no filters, returns the most recent conferences across all coverage (newest first). - ticker: narrows to a single company. - types: optional subset of the conference document types above (defaults to all). - year / quarter / half: filter on the **fiscal/earnings anchor period** a conference is grouped under — **NOT the calendar date of the event**. A conference held in Jan 2026 may be tagged year 2025 because it follows that company's 2025 reporting cycle. For calendar-date filtering, use startDate/endDate instead. quarter or half requires year. - startDate / endDate (YYYY-MM-DD, inclusive): filter on the **release date** — when the event's transcript/materials were published. This is the recommended way to filter by calendar time. - Pagination defaults to limit 50, offset 0. **Output Contents:** - conferences: Array of { documentId, ticker, companyName, title, type, releaseDate, year, quarter, half }, newest first. An event and its `_DOCS` slide deck are returned as separate rows, distinguished by `type`. - metadata: count (rows on this page), totalCount, limit, offset. Note: `totalCount` counts documents, so an event and its slide deck count as two — it is not a distinct-event count. **Example Usage:** - Latest coverage across the universe: `{}` - One company: `{ ticker: "AAPL" }` - Tagged-period filter: `{ year: 2025, quarter: 1 }` - Release-date window: `{ startDate: "2025-01-01", endDate: "2025-03-31" }` - Only analyst days for a name: `{ ticker: "AAPL", types: ["Analyst Day"] }`

conference-list

Returns the current user's watchlists and, optionally, latest document release dates for each ticker. **Input Behavior:** - If `documentTypes` is omitted, each watchlist is returned in the standard shape: - `{ id, name, tickers: string[] }` - documentTypes (optional): Multi-select list of document types to look up for each ticker - If `documentTypes` is included, it must contain at least one value - Pass documentTypes as an array of exact enum strings, for example: - `["Earnings call"]` - `["Earnings call", "10Q", "Investor Day Docs"]` - If documentTypes contains one or more values, each watchlist is returned in an enriched shape: - `{ id, name, tickers: Array<{ ticker, latestReleaseDates }> }` - In enriched mode, `latestReleaseDates` contains only document types that were found for that ticker. If a selected type has no matching document, that key is omitted. **Output Contents:** - watchlists: Array of watchlist objects - id: Watchlist ID - name: Watchlist name - tickers: - default mode: array of stock ticker symbols in the watchlist - enriched mode: array of ticker objects with `ticker` and `latestReleaseDates` - count: Total number of watchlists **Example Usage:** - List all watchlists: `{}` - Single document type: `{ "documentTypes": ["Earnings call"] }` - Enriched list with dates: `{ "documentTypes": ["Earnings call", "10Q"] }`

watchlist-list

List, search, add, or remove Reddit subreddits on the authenticated user's tracking list. Use `reddit` to fetch posts from subreddits you already track. **How it works:** - list: returns every subreddit you currently track - search: looks up a subreddit by name and reports whether you already track it - add: starts tracking a subreddit by name - remove: stops tracking a subreddit by name. The subreddit is removed from your list and cannot be recovered without adding it again **Input Behavior:** - action is always required - list takes no extra params - search, add, and remove take subreddit **Output Contents:** - list: subreddits array with all currently tracked subreddits - search: subreddit with isTracked flag - add: subreddit and updated subreddits list - remove: removed flag and message, plus updated subreddits list **Example Usage:** - List tracked subreddits: `{ action: "list" }` - Search for a subreddit: `{ action: "search", subreddit: "stocks" }` - Track a subreddit: `{ action: "add", subreddit: "wallstreetbets" }` - Stop tracking: `{ action: "remove", subreddit: "wallstreetbets" }`

manage-reddit

Extracts the performance drivers and explicit weightings that determine executive incentive pay (not the dollar compensation amounts) from the latest proxy filing (or 20-F/Annual Report fallback). Produces a concise markdown summary separating short-term vs long-term incentive drivers for named executive officers, grounded solely in the filing text. When enabled, it also attempts to include the prior fiscal year for comparison. **How it works:** - Resolves the latest DEF-14A, falling back to 20-F then Annual Report if needed - Attempts to reuse the freshest cached Management Drivers data before regenerating - Generates a driver-focused report with short-term vs long-term incentive weights **Input Behavior:** - includePriorYear defaults to true - Prior-year section is only included when a prior filing is available and parsed **Output Contents:** - ticker: Stock ticker symbol - latestYear: Latest fiscal year covered in the report - priorYear: Prior fiscal year covered, if included - content: Markdown report of incentive compensation drivers and weights **Example Usage:** - Default (include prior year): `{ ticker: "AAPL" }` - Latest only: `{ ticker: "AAPL", includePriorYear: false }`

management-compensation-drivers

Fetches management follow-up questions for the latest earnings call, grouped by thematic section (financial performance, operations, strategy, etc.). Always uses the most recent earnings call for the ticker. **Output Contents:** - content: Markdown document of follow-up questions organised by section - documentId: The earnings call document ID this analysis is based on (pass to fetch-document to open the transcript) - documentType, year, quarter, half: Period identifiers for the earnings call used **Example Usage:** - `{ ticker: "AAPL" }`

management-followup

Advanced guidance extraction system that captures all forward-looking statements from management during earnings calls—from precise quantitative targets to qualitative directional commentary—for one or more tickers at once. **How it works:** - Analyzes earnings call transcripts using state-of-the-art AI extraction - Captures standardized financial metrics (revenue, EPS, margins, capex, etc.) - Extracts non-standard guidance including product launches, market trends, supply constraints, strategic initiatives, hiring plans, and any forward-looking commentary - Identifies guidance changes: RAISED, LOWERED, MAINTAINED, or NEW - Provides consensus estimates at the time of earnings for comparison - Handles both specific numerical ranges and vague qualitative statements (e.g., "strong growth", "supply-constrained", "increasing adoption") - Each ticker is resolved and processed independently; one ticker failing never fails the rest **Input Behavior:** - tickers is required (one or more). - If year is omitted, each ticker uses its latest available period automatically - quarter is required when year is provided (for quarterly reporters) - half is required when year is provided (for semi-annual reporters) - generate defaults to false - generate=false: returns stored guidance only; if none exists yet, that ticker comes back with status not_found - generate=true: returns stored guidance when present; if none exists, enqueues extraction (status pending) unless a run is already scheduled or in progress for that document **Output Contents:** - results: one entry per requested ticker (in order), each with: - status: ready (stored guidance returned) | not_found (no stored guidance / no earnings call) | pending (extraction enqueued or in progress) | error (lookup failed) - ticker, period: Identifiers for the earnings call analyzed - guidance[]: Array of extracted guidance items, each containing metric name, value/range, target period, outcome (RAISED/LOWERED/MAINTAINED/NEW), supporting commentary, and citations with authenticated source links when available - message: Optional status when generation was enqueued or extra context applies - message: Batch-level hint when generation was enqueued/in progress for some tickers **Example Usage:** - Get guidance for a watchlist (latest period each): `{ tickers: ["AAPL", "MSFT", "NVDA"] }` (auto-resolves to latest completed period) - Specific period: `{ tickers: ["NVDA"], year: 2024, quarter: 3 }` - Enqueue extraction if missing: `{ tickers: ["NVDA"], year: 2024, quarter: 3, generate: true }`

guidance

Fetches the latest market quote for a ticker. **How it works:** - Resolves the best-available market symbol from the internal database (if present) - Loads full historical EOD for today's date and company profile from the market data provider - Returns price, session low/high (from the EOD bar), and 52-week range from profile when available **When to use stock-price-live instead:** - For live last prices (and/or multiple tickers), use `stock-price-live` — it calls batch-quote **Input Behavior:** - If the ticker exists internally with a mapped market symbol, that symbol is used - Otherwise, the provided ticker is queried directly **Output Contents:** - ticker: The requested ticker - symbol: The market symbol used for the lookup - date: As-of date for the quote (YYYY-MM-DD), from the EOD bar when available - price, changesPercentage: Latest price and percent change - dayLow/dayHigh, yearLow/yearHigh: Session and 52-week ranges - message: Present when no quote is found **Example Usage:** - Basic: `{ ticker: "AAPL" }`

market-quote

Retrieves model page data for a ticker, including financial and operating metric rows across historical periods and future estimate periods. Uses the authenticated MCP user's saved model cells when available. If the user has no custom model cells for the ticker, default model cells are used. **Input Behavior:** - mode defaults to full. - cells-by-pgid requires pgid. - cells-by-period requires year. Provide quarter for quarterly periods, half for half-year periods, or neither for annual periods. **Modes:** - full: Returns the complete formatted model page payload, including stock metadata, rows, headers, and all cells. - without-cells: Returns stock metadata, rows, and period headers, but omits the cells array. Use this when you only need the model page structure or want a smaller response. - cells-by-pgid: Returns the model page payload with cells filtered to a single Pinegap Data ID. Requires pgid. - cells-by-period: Returns the model page payload with cells filtered to a specific period. Requires year. Provide quarter for a quarterly period, half for a half-year period, or only year for annual cells. Formatted output notes: - Dates and timestamps are returned as MM-DD-YYYY. - Financial value fields are compacted to two-decimal K/M/B/T strings where applicable. Identifiers and period fields remain numeric. **Output Contents:** - ticker: Requested ticker - data: Formatted model page payload for the ticker, including stock metadata, metric rows, period headers, actuals, consensus estimates, surprises, YoY changes, and QoQ changes. In filtered modes, data.cells contains only the matching cells. **Example Usage:** - Full model page: `{ ticker: "AAPL" }` - One metric's cells: `{ ticker: "AAPL", mode: "cells-by-pgid", pgid: "4359" }` - One quarterly period: `{ ticker: "AAPL", mode: "cells-by-period", year: 2025, quarter: 1 }` - One annual period: `{ ticker: "AAPL", mode: "cells-by-period", year: 2025 }`

model-data

Retrieves curated key performance indicators (KPIs) and operating metrics for a specific company. KPIs are industry-specific metrics (e.g., RevPAR for hotels, ARR for SaaS, Same-Store Sales for retail) sourced from our curated quant data provider. Data covers the last 8 quarters (or 4 halves). **How it works:** - Retrieves pre-calculated metrics from the database - No AI inference is used; this is raw, curated financial data - Returns a markdown-formatted table ready for display **Output Contents:** - ticker: Stock symbol queried - halfReported: Whether company reports semi-annually (true) or quarterly (false) - kpiTable: Pre-formatted markdown table with Metric, Period, Value, Unit, and Currency columns - kpis[]: Raw array of KPI objects with metric name, period, value, unit, and currency for programmatic access **Example Usage:** - Get KPIs for Apple: `{ ticker: "AAPL" }`

kpis

Pulls verbatim management quotes from a single source document — the latest earnings call transcript, or the latest press release as a fallback — organised into 12 operational categories. Every bullet is a direct quote — nothing is paraphrased, summarised, or generated. Use this tool when you need to know exactly what management said about unit volumes, pricing, retention, segment trends, or forward indicators, with the precise numbers they cited. **How it works:** - Resolves to the latest available period — earnings call preferred; falls back to the latest press release if no earnings call is available within the past 100 days - Extracts exact sentences and meaningful sentence fragments from the document into 12 categories — no new content is created - All 12 sections are always present; sections with no relevant excerpts are marked "No relevant excerpt found." **The 12 sections and what each captures:** - **Volume & unit metrics** — units sold/shipped, production output, capacity utilisation, installed base figures, throughput, deployment counts - **Revenue composition** — breakdown by product line, customer segment, geography, or contract type; run-rate figures for business units - **Pricing & monetization** — ASP trends, deal sizes, pricing actions, tariff impacts, rate/fee changes, monetisation model shifts - **Retention & expansion** — churn/renewal rates, repeat purchase behaviour, customer satisfaction scores, new-to-product ratios, subscriber growth - **Sales efficiency** — win rates, order book conversion, backlog burn, channel inventory levels, market share commentary - **Product/segment drivers** — specific reasons cited for growth or decline in particular business lines or geographies - **Go-to-market changes** — channel mix, distribution partnerships, new market entry, store openings, customer concentration shifts - **Contract terms** — average contract length, payment terms, multi-year or take-or-pay structures, subscription model transitions - **Usage & operational metrics** — consumption trends, run-rates, utilisation, capacity additions, fleet/network activity levels - **Capital allocation** — buyback amounts and targets, capex deployment and guidance, dividend specifics, cash and debt balances - **Sequential trends** — explicit QoQ changes with management context (e.g. margin moves, volume shifts quarter-on-quarter) - **Forward indicators** — backlog, order intake, pipeline commentary, booking trends, production ramp timelines, guidance colour **What this tool does NOT return:** - Synthesis, interpretation, or analyst commentary - Total revenue growth rates, overall margin percentages, or EPS (those belong in financial summary tools) - Generic "strong performance" statements without a concrete number - Macroeconomic commentary or boilerplate guidance language **Input Behavior:** - If year is omitted, uses the latest available period automatically (earnings call preferred; press release fallback if no earnings call within the past 100 days) - quarter is required when year is provided for quarterly reporters - half is required when year is provided for semi-annual reporters **Output Contents:** - ticker: The requested stock symbol - period: Formatted fiscal period (e.g. "Q3 2024") - year / quarter / half: Numeric period components - content: Markdown with 12 bolded section headings; each bullet is a verbatim quote from the transcript containing at least one concrete number or substantive operational insight - documentId / sourceDocumentType: The source document's ID and type (Earnings call or Press Release); pass documentId to fetch-document to open the source **Example Usage:** - Latest period: `{ ticker: "AAPL" }` - Specific quarter: `{ ticker: "AAPL", year: 2024, quarter: 3 }` - Semi-annual: `{ ticker: "HSBA", year: 2024, half: 1 }`

operating-metrics-commentary

Unified access to investment-focused podcasts — browse episodes, fetch transcripts, and retrieve equity insights linked to specific tickers. **Input Behavior:** - For `ticker-mentions`, provide exactly one of `ticker` (single symbol) or `tickers` (a list to scan in one call); supplying both is rejected - For `ticker-mentions`, `startDate` is inclusive from 00:00:00 UTC and `endDate` is inclusive through 23:59:59.999 UTC on that calendar day - For `ticker-mentions`, if `startDate` and `endDate` are omitted, defaults to the last 30 days - For `ticker-mentions`, pagination spans the combined result set across all requested tickers, ordered by publish date - `transcriptFormat` defaults to `json` - Pagination defaults to limit 50, offset 0 - `includeRawAnalysis` defaults to false **Output Contents:** - podcasts: List of supported podcasts - episodes: Episode list for a podcast or filtered query - episode: Single episode detail when requested - transcriptItems/transcriptText: Transcript content (JSON or text) - insights: Company-level insights with cleaned analysis and structured sentiment points - tickerMentions: Episodes mentioning the requested ticker(s) with insights; each insight carries its own ticker - link: episode/insight opens the episode page; analysis point opens the quoted transcript (use the insight link if the point has none) - metadata: count, totalCount, pagination, lookbackDays if applied, and notFoundTickers for any requested symbols with no matching security **Example Usage:** - List podcasts: `{ mode: "list-podcasts" }` - List episodes: `{ mode: "list-episodes", podcastId: 12, limit: 20 }` - Episode briefing (summary only): `{ mode: "get-episode", episodeId: 345 }` - Transcript: `{ mode: "get-transcript", episodeId: 345, transcriptFormat: "text" }` - Ticker mentions (last 30d default): `{ mode: "ticker-mentions", ticker: "MSFT" }` - Ticker mentions (multiple tickers): `{ mode: "ticker-mentions", tickers: ["MSFT", "AAPL"], limit: 100 }` - Ticker mentions (custom range): `{ mode: "ticker-mentions", ticker: "MSFT", startDate: "2025-01-01", endDate: "2025-02-01" }` - Episode insights only: `{ mode: "get-insights", episodeId: 345 }`

podcast

Retrieves the latest available primer sections for a company from the database. **How it works:** - Looks up the stock by ticker - Fetches the most recent primer sections from the primer data tables - Applies latest management updates. - Optionally scopes the response to specific sections via `sections`. **Token-bounded retrieval (avoid one large default dump):** - The default (all sections) can be large. To read the same data in smaller chunks over multiple calls, request one section (or a small group) per call via `sections`; the union of the per-section responses equals the full default. `COMP_SHEET` is the largest section and must be requested explicitly. **Parameters:** - ticker: Stock ticker symbol (required) - sections: Optional array of primer section types to return (e.g. COMPANY_OVERVIEW, BUSINESS_MODEL, RISKS, COMPETITORS). Omit to receive all available sections. Include "COMP_SHEET" explicitly to also build the comparison sheet (expensive; excluded by default even when other sections are omitted). **Output Contents:** - ticker: Stock symbol queried - data: Ordered primer sections with heading, type, and section payload **Example Usage:** - Get full primer data for Apple: `{ ticker: "AAPL" }` - Get only the business model section: `{ ticker: "AAPL", sections: ["BUSINESS_MODEL"] }` - Get multiple sections: `{ ticker: "AAPL", sections: ["RISKS", "COMPETITORS", "SWOT"] }`

primer

Retrieves a stored markdown proxy review report or generates one when missing. It covers board oversight/composition, ownership and voting control, executive compensation structure and performance linkage, and notable shareholder proposals or disclosure concerns. Generated reports are grounded solely in the filing text from a DEF-14A, with optional fallback to 20-F/Annual Report when unavailable. **How it works:** - Resolves the latest DEF-14A for the ticker - Optionally falls back to 20-F, then Annual Report if enabled - Returns a completed stored report when available - If missing, extracts filing text and generates an analyst-style proxy review unless generate is false **Input Behavior:** - allowAnnualFallback defaults to false - If enabled, fallback order is 20-F → Annual Report, useful for ADRs and foreign companies. - generate defaults to true. When false, the tool returns a completed stored report or a not-found error without generating one. **Output Contents:** - ticker: Stock ticker symbol - documentId: Document used for analysis - documentTypeUsed: Actual document type used (may differ if fallback applied) - content: AI-generated proxy review report **Example Usage:** - DEF-14A only: `{ ticker: "AAPL" }` - Stored report only: `{ ticker: "AAPL", generate: false }` - Allow fallback: `{ ticker: "AAPL", allowAnnualFallback: true }`

proxy-review

Summarizes the voting matters in a company's latest DEF 14A proxy statement — each proposal and the board's own stated position on it — for research. This is descriptive; it does not recommend how to vote. **How it works:** - Validates the ticker exists - Retrieves the latest DEF 14A proxy statement for the ticker - Extracts DEF 14A document text from the document store - Identifies each voting proposal and the board's stated position on it - Returns the structured, descriptive summary **Output Contents:** - ticker: Stock ticker symbol - documentId: Source DEF 14A document ID (pass to fetch-document to re-open the filing) - eventDate: Document release date (YYYY-MM-DD) - resultJson: Per-proposal summary — proposal text, the board's stated position, and any sources used (no AI-recommended vote) **Example Usage:** - Summarize proxy voting matters for `{ ticker: "AAPL" }`

proxy-voting

Scores earnings quality risk across six accounting dimensions using the most recent 10-K or 10-Q, returning per-flag verdicts and filing-specific evidence for each raised risk. **How it works:** - Identifies the most recent available filing (10-K or 10-Q) for the ticker by release date - Runs a proprietary multi-stage LLM analysis pipeline across the current filing and its prior-period comparator document - Each of the six dimensions is scored independently; raised flags include evidence extracted directly from the filing text **Input Behavior:** - Uses the most recent 10-Q or 10-K by release date - Falls back to 20-F or Annual Report only if no 10-K/10-Q exists **Output Contents:** - ticker, year, quarter/half, documentType: Identifies the exact filing used for the analysis - documentId: ID of the filing the analysis was run on (pass to fetch-document to open it). Note: the prior-period comparator behind previousQuarterStatus is a separate document not reflected here - analysisDate: ISO timestamp of when the analysis was generated - source: Provenance metadata — informational, no action required - flags: Always exactly six entries, one per earnings quality dimension. Each entry contains: - currentQuarterStatus (bool): true if the risk is active in the current filing - previousQuarterStatus (bool | null): true if the same risk was flagged in the prior-period filing; null if no prior-period data is available. Use this to distinguish new risks (false → true), persistent risks (true → true), and resolved risks (true → false) - analysis: Always populated. When currentQuarterStatus is true, contains specific filing-referenced evidence — note citations (e.g. "Note 2"), quantified comparisons (e.g. "unbilled A/R grew 64.9% vs 27.7% revenue growth"), and verbatim management disclosures. "No concerns identified." when the flag is not raised. - Dimensions covered: - Revenue Recognition Policy Changes: shifts in how or when revenue is recorded - Disproportionate Contract Asset Growth: unbilled receivables or contract assets growing materially faster than revenue - Rising DSOs / Slower Collections: accounts receivable outpacing revenue, suggesting collection deterioration or changed billing terms - Changes in Significant Accounting Estimates: management revisions to useful lives, impairment assumptions, or similar judgements that directly move earnings - Aggressive Cost Capitalization: expenses shifted from the P&L to the balance sheet (e.g. internal-use software, sales commissions) at an accelerating or newly introduced rate - Non-GAAP Creep: new exclusions added to non-GAAP metrics, or redefined metrics not recast for prior periods - quarterlyFlags: Same six-flag structure for the interim period; only present for non-US annual report filers where quarterly press releases serve as the comparator **Example Usage:** - Latest earnings quality assessment: `{ ticker: "AAPL" }`

quality-of-earnings

Retrieves quantitative financial metrics for one or more stocks using a natural language query. **How it works:** - Analyzes the query to determine which financial parameters and time periods are relevant - Fetches data from a financial data provider across the requested metric categories - Supports historical actuals, forward estimates, valuation multiples, estimate revisions, and earnings surprises **Input Behavior:** - query describes the desired metrics in plain English; be specific about time periods and metric categories for best results - tickers accepts up to 20 stock symbols **Output Contents:** - All monetary values are denominated in USD - tickers: stocks included in the response - notFound: any tickers not found in the database - standardizedData: income statement, balance sheet, and cash flow actuals and estimates (e.g., Revenue, EBITDA, Free Cash Flow, EPS) - valuationMetrics: valuation multiples such as P/E, EV/EBITDA, Price/Book, FCF Yield - marketData: market capitalisation and enterprise value per ticker - estimatesData: consensus analyst estimates with broker count and dispersion statistics - revisionsData: how consensus estimates have changed over time windows (30D, 90D, post-earnings) - surprisesData: actual vs consensus surprise percentages for recently reported periods - message: present when partial data was returned or fallback data was used **Example Usage:** - Revenue and margins: `{ query: "revenue, gross margin, and EBITDA for the last 3 fiscal years", tickers: ["AAPL", "MSFT"] }` - Valuation: `{ query: "NTM P/E, EV/EBITDA, and Price/Book multiples", tickers: ["NVDA"] }` - Estimates and revisions: `{ query: "consensus EPS estimates and 30-day revisions for next fiscal year", tickers: ["GOOGL", "META"] }` - Earnings surprises: `{ query: "revenue and EPS surprises for the last 4 quarters", tickers: ["AMZN"] }` - Market data: `{ query: "market cap and enterprise value", tickers: ["TSLA", "GM", "F"] }`

quant-metrics

Returns quotes from other companies' recent earnings calls, press releases, and investor event transcripts (conferences, analyst days, investor days, capital markets days) that linked back to one or more target tickers, along with inferred impact and relationship context. **How it works:** - Starts from the target tickers, then searches recent source-company disclosures within either the requested custom date window or the rolling look-back window - Keeps `FIRST_ORDER` matches when a target is named directly and `SECOND_ORDER` matches when relevance is inferred through peer, supplier, customer, partner, or competitor relationships - Filters source companies by sector, market, and minimum market cap before returning rows - Ranks the strongest matches so the output surfaces the highest-signal read-throughs first - Up to 30 tickers per request; each row carries `targetTicker` so results for multiple targets can be grouped **Input Behavior:** - tickers: Required array of target company tickers (1–30 symbols) - lookBackDays: Optional rolling look-back window in days. Defaults to 7 when no explicit date range is provided. - startDate/endDate: Optional inclusive custom date window in YYYY-MM-DD format. Use the same date for both to request a single day. - sourceSectors: Optional source-company sectors to include - sourceMarkets: Optional source-company markets to include - sourceMarketCap: Optional minimum source-company market cap in million USD. For example, 1000 means $1B. - targetKinds: Optional signal kinds to include - sourceDocumentTypes: Optional source document types to include (`EARNINGS_CALL`, `PRESS_RELEASE`, `CONFERENCE`, `ANALYST_DAY`, `INVESTOR_DAY`, `CAPITAL_MARKETS_DAY`); omitted means all types - `lookBackDays` cannot be combined with `startDate` or `endDate` - All filters are optional; omitted filters default to a 7-day look-back, a 1000 million USD source-market-cap floor, all supported sectors, all supported markets, all source document types, and both `FIRST_ORDER` and `SECOND_ORDER` - `sourceMarketCap` is entered in million USD, so `1000` means $1B - `sourceMarketCap: 0` intentionally disables the market-cap floor, while omitting the field uses the default floor - Sector, market, and market-cap filters apply to the source companies making the statements, not the requested target tickers **Output Contents:** - `tickers`: Target tickers successfully resolved from the request - `notFound`: Tickers from the request that were not found in the database (omitted when all tickers resolved) - `message`: Present when some tickers could not be resolved; results are returned for any valid tickers found - `filters`: Normalized filters actually applied to the query; either `lookBackDays` or `startDate`/`endDate` will be present, and `sourceMarketCap` here is reported in raw USD after internal conversion for the backend read path - `count`: Total number of read-through rows returned across all target tickers - `data[]`: Ranked read-through rows for all requested targets, with one source quote per row. Each row includes: - `targetTicker`: The target ticker this row pertains to (use this to group results when multiple tickers are requested) - `readthroughOrder`: Relative ordering of the strongest matches for that target ticker - `classification`: `firstOrder` means the target was named directly; `secondOrder` means the relevance was inferred indirectly - `topic` and `sourceTopic`: User-facing normalized topic label plus the raw topic label from the source quote - `direction` and `relationship`: Inferred impact and source-to-target relationship when the pipeline could resolve them - `whyItMatters` and `reason`: Short significance summary plus, when available, the rationale for linking the quote back to the target - `source*` fields: Origin of the quote, including company, document, period, release date, section, and speaker when available - `target*` fields: Target company context used to frame the read-through against its latest earnings period - `quote`: Verbatim quote text from the source disclosure; multi-part stored quotes stay inline and get [n] markers inserted before each `...` boundary - `citations`: Optional source citations matching the inline [n] markers in `quote` **Example Usage:** - `{ tickers: ["MSFT"] }` - `{ tickers: ["MSFT", "AAPL"], lookBackDays: 20, targetKinds: ["FIRST_ORDER"] }` - `{ tickers: ["MSFT"], startDate: "2026-05-27", endDate: "2026-05-29" }` - `{ tickers: ["MSFT", "NVDA"], sourceSectors: ["Information Technology"], sourceMarketCap: 5000 }`

readthroughs

Retrieves processed Reddit post insights from subreddits the authenticated user tracks. Does not add or remove tracked subreddits — use `manage-reddit` for that. **How it works:** - fetch-posts: Returns structured, AI-processed Reddit insights from subreddits you track, filtered by date, tickers, and content type **Which mode to use:** - Use fetch-posts when the user wants structured, AI-processed insights from subreddits they already track. This is best for dashboards, monitoring feeds, ticker-linked news, long/short ideas, sentiment, catalysts, and date/ticker/type filtering. Results are normalized and tied to Pinegap stocks - Use `manage-reddit` when the user wants to list, search, add, or remove tracked subreddits **Input Behavior:** - mode is always required and must be fetch-posts - startDate and endDate are optional (YYYY-MM-DD). Default window is the last 7 days when omitted. Date range cannot exceed 90 days - tickers limits to posts linked to those stocks (up to 50 symbols) - kinds limits to core and/or contextual items - If tickers are provided and none resolve, the request fails with STOCK_NOT_FOUND; if some tickers are invalid, results for valid tickers are returned and a message is included **Output Contents:** - fetch-posts: posts array with content, sentiment, kind, catalyst, ticker, company name, subreddit, and source URL; metadata with date window **Example Usage:** - Latest posts (default 7-day window): `{ mode: "fetch-posts" }` - Date range with ideas only: `{ mode: "fetch-posts", startDate: "2026-05-01", endDate: "2026-05-03", types: ["long_idea", "short_idea"] }` - Filter by tickers: `{ mode: "fetch-posts", tickers: ["AAPL", "MSFT"] }` - Core items only: `{ mode: "fetch-posts", kinds: ["core"] }`

reddit

Retrieves the latest running screener by default, or lists all screeners for the user. When a screener is completed, returns the final tickers and metrics with optional report content. **How it works:** - Defaults to the most recent running screener (falls back to latest overall) - Supports list mode for showing all screener conversations - Includes progress summary and tool execution stats - Returns metrics and optionally report content when completed **Input Behavior:** - If `mode` is "list", returns a list of screeners for the user - If `conversationId` is provided, fetches that specific screener - Otherwise, resolves to the most recent running screener, then latest overall - Report content is included only if results <= threshold or `includeReports` is true - Use `reportTickers` to request report content for specific tickers **Output Contents:** - mode: The response mode (latest or list) - state: "completed", "running", or "unknown" - status: Progress summary and tool stats - results: Final results with metrics and optional reports (when completed) - tickers: The complete final ticker list — pass directly to `watchlist-create` to save results as a new watchlist - totalResults: Total number of result companies **Exporting results to a watchlist:** When `state` is "completed", pass `tickers` directly to `watchlist-create`: `{ name: "My Screener Results", tickers: <tickers from this response> }` **Example Usage:** - Poll for completion: `{ conversationId: 123 }` - Latest: `{}` - List all: `{ mode: "list" }` - Fetch reports for specific tickers: `{ conversationId: 123, reportTickers: ["AAPL", "MSFT"] }` - Save results to a watchlist on completion: `{ conversationId: 123, watchlistName: "AI Picks" }` (saved only when state is "completed"; otherwise `watchlistMessage` explains why)

screener-status

Returns quantitative sector earnings comparison tables for a ticker — Revenue, Operating Margin, and EPS — across the user's configured peer set. **Input Behavior:** - Requires an authenticated user context with a configured peer set for the ticker **Output Contents:** - ticker: The company analyzed - metrics[]: One entry per metric (REVENUE, OPERATING_MARGIN, EPS), each with: - metricName: Metric identifier - headers: Table column labels - data: Table rows with peer comparison values **Example Usage:** - `{ ticker: "MSFT" }`

sector-earnings

Tracks how management sentiment around specific keywords shifts across consecutive earnings calls, for one or more tickers at once. Compares the current and previous periods to surface meaningful changes in tone, emphasis, confidence, and language, with verbatim supporting excerpts. **How it works:** - For each ticker, resolves the relevant earnings call and reads any sentiment already stored for the requested keywords (returned instantly). - Keywords not yet stored are generated on-demand: generation is kicked off in the background and those keywords come back marked pending. Poll the tool again (re-call with the same arguments) to pick them up once ready — typically within a few minutes. - Generated results are persisted and reused, so repeat requests for common keywords are immediate. - Keyword matching is case-smart: short tokens (≤4 chars, e.g. AI, TGV, AGM) keep their case; longer tokens are lowercased. So "AI Revenue" and "AI revenue" are the same keyword, but "Ai revenue" is different. **Input Behavior:** - tickers is required (one or more). - keywords is optional: - If provided: tracks each keyword across all tickers. - If omitted: returns the stored, curated keyword set for each ticker. - generate defaults to true: keywords not yet stored are generated in the background and reported as pending. Set generate=false to only look up what is already stored, without triggering any generation (missing keywords come back under missingKeywords). - If year is omitted, uses each ticker's latest available earnings period automatically. - quarter is required when year is provided (for quarterly reporters); half is required when year is provided (for semi-annual reporters). **Output Contents:** - results: one entry per requested ticker (in order), each with: - status: ready (all requested data present) | partial (some ready, rest generating) | pending (generating, nothing ready yet) | not_found (no earnings call, or nothing stored when generate=false) | error (lookup failed) - sentimentByKeyword: sentiment results for the keywords that are ready (per keyword: change yes/no, managementConfidence, managementLanguage, and a changeReason with explanation + verbatim citation_new/citation_old) - pendingKeywords: keywords still being generated — poll again to fetch them - missingKeywords: keywords not stored and not generated (only when generate=false) - keywordSources: source of each curated keyword (ai or user); curated mode only - message: present when any ticker is still generating, with a "check back in ~N minutes" hint **Example Usage:** - Track a keyword across a watchlist: `{ tickers: ["AAPL", "MSFT", "NVDA"], keywords: ["AI Revenue"] }` - Search without generating: `{ tickers: ["AAPL"], keywords: ["pricing power"], generate: false }` - Specific period: `{ tickers: ["MSFT"], keywords: ["Azure demand"], year: 2024, quarter: 3 }` - Curated set (latest): `{ tickers: ["AAPL"] }`

sentiment-analysis

Fetches short-interest history (% of float, bi-monthly settlement data) for a single ticker. Designed to be rendered as a time-series chart by the calling agent. **How it works:** - Computes short-interest-as-percent-of-float per settlement date by combining live regulatory short-interest filings with the most recent reported float - Returns the trailing ~89 days of settlement points - Bundles a renderHints block so the agent can draw a chart that visually matches the standard canonical look **Input Behavior:** - One ticker per call. For multi-ticker comparisons, call this tool once per ticker and rotate seriesColor through the palette ["#266DF0", "#049262", "#F59E0B", "#8B5CF6", "#EF4444"] - Window is fixed at trailing ~89 days **Output Contents:** - found: true iff the ticker resolved AND the window contained at least one point - points[i].percentOfFloat: short interest as a percent of float, already in percent form (e.g., 5.42 means 5.42%) - points[i].date: settlement date in ISO yyyy-mm-dd, ordered ascending - renderHints: canonical visual spec — apply yAxisSuffix to tick labels, format y-values to yAxisDecimals decimals, draw the line at lineWidth px in seriesColor with a fillOpacity area fill, target chartHeightPx tall - renderHints.chartType is "step-after": each point's value holds flat until the next settlement, then jumps. Short interest is filed bi-monthly at discrete settlement dates and does not interpolate between them — render as a step-after line (e.g., SVG <polyline> with horizontal-then-vertical segments), NOT a smooth/linear line - message: explanation when found is false **Example Usage:** - `{ ticker: "GME" }`

short-interest

Creates a new screener conversation and, if follow-up questions are required, requests answers via MCP elicitation or returns them for conversational collection. **How it works:** - Creates a screener conversation with an optional filter overlay - If follow-up questions are generated, attempts elicitation; otherwise returns questions for you to ask the user - On acceptance, submits follow-up answers and starts the screener run - If no follow-up questions are generated, the screener proceeds automatically - The screener runs asynchronously — use `screener-status` with the returned `conversationId` to poll for completion and retrieve results **Input Behavior:** - Provide `query` to create a new screener conversation - Provide `conversationId` + `followUp` to submit answers for an existing conversation - `filters` are applied on creation and can be re-sent on follow-up submission to preserve user overrides - `filters.watchlistIds`: constrain the screener universe to the members of specific watchlists — the screener only evaluates stocks in those lists. Use `watchlist-list` to get watchlist IDs. Multiple IDs are unioned. - `filters.sectors`, `filters.industries`, `filters.markets`, `filters.marketCap`: standard universe narrowing; can be combined with `watchlistIds` **Output Contents:** - conversationId: Use this with `screener-status` to check progress and retrieve the final ticker list - needsFollowUp: Whether follow-up answers are still required - questions: Follow-up questions if elicitation was declined or unsupported - status: Progress summary for the conversation - message: Optional status message for fallbacks **Fallback (when `needsFollowUp` is true):** When elicitation is unavailable or declined, the response will contain `questions` that need user answers. Present each question to the user conversationally and collect their answers. Then call this tool again with: `{ conversationId: <id>, followUp: [{ question: "...", answer: "..." }, ...] }` **Example Usage:** - Broad screener: `{ query: "Find profitable US fintechs", filters: { markets: ["North_America"] } }` - Watchlist screener: `{ query: "Which of these have improving margins?", filters: { watchlistIds: [42] } }` (get IDs from `watchlist-list`) - Submit follow-ups: `{ conversationId: 123, followUp: [{ question: "...", answer: "..." }] }`

screener-start

Filters the covered stock universe by sector/industry classification and screener metrics, returning the matching stocks with their details. **How it works:** - Narrows the universe by geographic market, then by GICS classification (sector / industry group / industry / sub-industry) - Applies each metric filter. - Returns every match, sorted by market cap (largest first) **Discovering the exact classification values:** pass `listClassification` (`"sector"`, `"industryGroup"`, `"industry"`, or `"subIndustry"`) to get the available values at that level with company counts, instead of stocks. Scope it with the classification filters — `{ listClassification: "subIndustry", sectors: ["Health Care"] }` lists only the sub-industries inside Health Care. Use this to get the exact strings the event tools and this tool expect. In this mode `markets` narrows the companies counted and `limit` caps how many values come back; `metrics` and `topPerSector` are per-stock filters and are rejected rather than ignored. **Input Behavior:** - All filters are optional; with none, the whole covered universe is returned — narrow with filters, or cap the response with `limit` - Omitting `markets` searches all markets; multiple values within a filter are OR'd, while different filters are AND'd - Classification filters match a stock's primary **or** secondary classification, so the returned classification may differ from the one requested - Values within one classification field are OR'd; different fields are AND'd, so they must nest (an industry inside the given sector). An empty array or an omitted field means "all" - Classification names are matched forgivingly ("healthcare" resolves to "Health Care"); an unrecognised name is rejected with the nearest valid options rather than silently matching nothing - `gt` and `lt` are inclusive bounds; each metric filter needs at least one of them - Metric bounds use the metric's **own unit**, the same unit the output reports it in: raw USD for amounts (`1e10` = $10B market cap), a plain multiple for ratios (`Price / Earnings: 15`), and percent for margins and growth (`Operating margin: 20` = 20%). Exponent notation is accepted, so `1e10` avoids miscounting zeros - Metric values are period-scoped and default to `LTM`. Market-data metrics (Market Cap, Enterprise Value, Last price EOD) have a single latest value, so `period` is ignored for them - A stock with no value for a filtered metric is excluded - `topPerSector` keeps the largest N of **each** sector — use it whenever several sectors (or all of them) are in scope, otherwise a plain `limit` returns only the mega-caps of one or two sectors. Sectors are grouped by the `sector` value reported for each stock - `limit` is an overall cap applied **after** `topPerSector`, so the two combine (e.g. 20 per sector, no more than 200 rows total) - Both keep the largest by market cap; `totalMatched` always reports the full pre-cap match count **Output Contents:** - classifications[]: In `listClassification` mode — the available values at that level, each with `stockCount` and its parent sector/industryGroup/industry, largest first. `stocks[]` is empty in this mode - totalMatched: How many stocks passed every filter, before `topPerSector`/`limit` are applied - returned: How many stocks are in this response, after those caps — equals `totalMatched` when neither cap trimmed anything - stocks[]: Matching stocks, largest market cap first — ticker, company name, exchange, country, sector/industry classification, latest market cap in USD, and the value behind each requested metric filter - message: Present when nothing matched **Example Usage:** - Large caps in one sector over 100 million$: `{ sectors: ["Information Technology"], metrics: [{ name: "Market Cap", gt: 100000000 }] }` - Any sector, above $10B: `{ metrics: [{ name: "Market Cap", gt: 1e10 }] }` - Top 20 of every sector: `{ topPerSector: 20 }` - Top 20 per sector across three sectors: `{ sectors: ["Information Technology", "Health Care", "Energy"], topPerSector: 20 }` - Top 100 by market cap: `{ markets: ["North_America"], limit: 100 }` - Cheap US industrials: `{ sectors: ["Industrials"], markets: ["North_America"], metrics: [{ name: "Price / Earnings", lt: 15 }] }` - List every sub-industry with company counts: `{ listClassification: "subIndustry" }` - List the industries inside two sectors: `{ listClassification: "industry", sectors: ["Health Care", "Information Technology"] }` - Filter by a narrow level: `{ subIndustries: ["Biotechnology"] }` - Profitable growers: `{ industries: ["Software"], metrics: [{ name: "Operating margin", gt: 20 }, { name: "Total revenue, YoY", gt: 15 }] }`

coverage

Retrieves stock information by ticker symbol, Bloomberg ticker, Nasdaq ticker, or company name. Returns company metadata including ID, name, exchange, sector, reporting frequency, and external data provider identifiers. **Input Behavior:** - At least one of ticker, bloombergTicker, nasdaqTicker, or name must be provided - If multiple identifiers are provided, precedence is: ticker, then bloombergTicker, then nasdaqTicker, then name - Ticker lookup tries exact match first, then falls back to suffixed variants like `MND_US` - Bloomberg ticker lookups are exact matches - Nasdaq ticker lookups are exact matches against stored Nasdaq tickers - Name search uses Fuse-based fuzzy matching on raw and normalized company names to find close matches **Output Contents:** - found: Whether any matches were found - ticker/bloombergTicker/nasdaqTicker/query: The search term used for the chosen lookup mode - stock: Single StockInfo object for exact ticker or Bloomberg ticker matches - stocks[], count: Array of StockInfo objects for name search or ticker suffix fallback matches, ranked best-first (by market cap and data coverage) - message: Status message when no matches are found or when a fallback/best-match result is returned - didYouMean: For ticker lookups resolving to a single stock, sibling tickers sharing the same base across markets, as [ticker, name, bloombergTicker] tuples. Bidirectional (AAL -> American Airlines flags AAL_UK / Anglo American; AAL_UK flags AAL). Present only when such collisions exist; the Bloomberg ticker element may be null - StockInfo includes: id, ticker, name, exchange, country, sector/industry classification, halfReported (reporting frequency), baseCurrency, and external identifiers (visibleAlphaCid, quartrCompanyId, bloombergTicker, yahooTicker, secCik, nasdaqTickers, etc.) **Ticker collisions:** - `didYouMean` is populated only when the resolved ticker shares a base with tickers in other markets (AAL -> American Airlines, sibling AAL_UK -> Anglo American). Its absence means no same-base sibling exists. - When it is present, the exact match in `stock` is one of several companies behind that base, so it may not be the market the request refers to. Each entry carries name + Bloomberg ticker, which distinguishes the companies; a lookup on a sibling ticker returns that company instead. - Downstream tools use whichever ticker they are given — ticker identity is fixed at this step, not re-resolved later. **Example Usage:** - Lookup by ticker: `{ ticker: "AAPL" }` - Lookup by Bloomberg ticker: `{ bloombergTicker: "AAPL US" }` - Lookup by Nasdaq ticker: `{ nasdaqTicker: "GOOGL" }` - Search by name: `{ name: "Apple" }`

stock-lookup

Fetches technical indicator series for a ticker (RSI, SMA, EMA, DEMA, TEMA, WMA, ADX, Williams %R, Standard Deviation). **How it works:** - Resolves the best-available market symbol from the internal database (if present) - Calls the market data provider's technical indicator endpoint per request - Returns indicator time series with aligned dates **Input Behavior:** - Provide indicator requests in the "indicators" array - If indicators are omitted, defaults to RSI_14 and SMA_50 (daily); volume mode defaults to SMA_50 - `mode` is required (default `price` if omitted): `price` | `volume`; volume allows SMA/EMA/WMA/DEMA/TEMA/standardDeviation only, period ≤ 365, daily timeframe - startDate and endDate are optional filters for all indicator series - If the ticker exists internally with a mapped market symbol, that symbol is used **Output Contents:** - ticker: The requested ticker - symbol: The market symbol used for the lookup - mode: price or volume used for this response - indicators: Time series for each requested indicator (volume series names prefixed VOL_) - message: Present when no indicator data is found **Example Usage:** - Defaults: `{ ticker: "AAPL" }` - Custom: `{ ticker: "AAPL", indicators: [{ type: "rsi", period: 14 }, { type: "sma", period: 200 }] }` - Date range: `{ ticker: "AAPL", startDate: "2024-01-01", endDate: "2024-06-30", indicators: [{ type: "ema", period: 20 }] }` - Volume: `{ ticker: "NVDA", mode: "volume", indicators: [{ type: "sma", period: 200 }] }`

technical-indicators

Fetches total returns for a ticker using a standard period or a custom date range. **How it works:** - Resolves the best-available market symbol from the internal database (if present) - Uses standard period returns for quick lookup or a custom range for precise dates - Returns the total return as a percent **Input Behavior:** - Provide either a standard period OR a start/end date range (not both) - If neither is provided, defaults to a 3M period - startDate and endDate must be provided together - If the ticker exists internally with a mapped market symbol, that symbol is used **Output Contents:** - ticker: The requested ticker - symbol: The market symbol used for the lookup - period or start/end dates: The return window - periodDescription: Human-readable window description - returnValue: Total return for the period (percent) - message: Present when no return data is found **Example Usage:** - Standard period: `{ ticker: "AAPL", period: "3M" }` - Custom range: `{ ticker: "AAPL", startDate: "2024-01-01", endDate: "2024-06-30" }`

returns