Pinegap

Generates a comprehensive pre-earnings analysis for an UPCOMING earnings report. Always uses the most recent completed earnings period as reference — backdated previews are not supported. Combines multiple data sources: (1) consensus estimates and historical beat/miss patterns, (2) recent news articles summarized by AI, and (3) an AI-generated preview takeaway that synthesizes estimates + news into key points to watch. The takeaway is generated fresh or retrieved from cache. Best used 1-2 weeks before an earnings call to prepare for the release. **How it works:** - Always auto-resolves to the latest available completed period - The tool generates a preview for the UPCOMING/NEXT period **Input Behavior:** - generate defaults to false - generate=false: return only DB-stored preview data, news summary; if missing, return an informative error based on upcoming earnings timing (effective window = within 21 calendar days of the next earnings date) - generate=true: return DB-stored preview data if present; otherwise generate live data and always regenerate news summary. - includeCharts defaults to true. Set to false to skip the charts[] array (valuation revision and short interest time series) when it isn't needed — reduces response size. **Output Contents:** - basePeriod: The completed reference period auto-resolved (e.g. "Q3 2024") - upcomingPeriod: The period being previewed (e.g. "Q4 2024") - previewData: Analyst consensus estimates, management guidance, and stock/sector performance context for the upcoming period - previewData.earningModelData: Per-metric rows for the upcoming earnings preview. Field meanings: "metricName" is the display metric name; "estimates" is the consensus estimate for the upcoming/current reporting quarter being previewed (FQ1); "yoyGrowth" is expected YoY growth for that FQ1 estimate; "fq2Estimate" is the next-quarter consensus estimate (FQ2); "fq2EstimateRevision" is the recent revision for FQ2; "last30DaysEstimateRevision" is the recent revision for FQ1; "fyEstimate" is the current fiscal-year consensus estimate (FY1); "fyYoyGrowth" is expected YoY growth for FY1; "fyEstimateRevision" is the recent revision for FY1; "guidance" is management guidance if attached, often "N/A"; "sectionHeading" is the display grouping such as Revenue, Operating Income, EBITDA, KPI, or User Specific Metrics; "scale" is Visible Alpha scale metadata; "unit" is the display unit; "orderingIndex" is table sort order; "pid" is the optional Visible Alpha parameter id, sanitized to pgid in MCP output where applicable. - previewData.metricsData: Management guidance / company-provided metric context for the upcoming period when available. - previewData.competitorSnapshot: Peer latest-quarter surprise and market context, including revenue/EPS surprise percentages for comparable companies. - previewData.brokerRatingChanges / brokerEstimateChanges: Recent broker rating and estimate revision changes when available from the stored preview payload. - takeaway: AI-generated markdown paragraph synthesizing estimates, guidance, and news into key risks and opportunities to watch heading into the print - takeawayStatus: "ready" (takeaway available), "generating" (enqueued, retry shortly), or "failed" - newsRecap: AI-synthesized bullet-point summary of material news since the last earnings call (guidance changes, M&A, regulatory actions, leadership moves) - conferenceTakeaways: Takeaways from investor conference presentations held between the reference earnings call and the upcoming print **Example Usage:** - To preview AAPL's upcoming earnings: DB-only (default): `{ ticker: "AAPL" }` (auto-resolves to latest completed period) - Force generation if missing: `{ ticker: "AAPL", generate: true }`

earnings-preview

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

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 - Regenerates analysis if no usable data is found or previous runs failed **Input Behavior:** - allowAnnualFallback defaults to false - When enabled, falls back to ANNUAL_10K → TWENTY_F → ANNUAL_REPORT if no DEF-14A exists **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 }`

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

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:** - If year is omitted, returns the latest available period - If year is provided, switches to existence-check mode - quarter is required with year for quarterly reporters - half is required with year for semi-annual reporters **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

latest-period

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

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

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 - 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

Generates a markdown proxy review report covering board oversight/composition, ownership and voting control, executive compensation structure and performance linkage, and notable shareholder proposals or disclosure concerns. The report is 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 - Extracts the filing text and generates an analyst-style proxy review **Input Behavior:** - allowAnnualFallback defaults to false - If enabled, fallback order is 20-F → Annual Report, useful for ADRs and foreign companies. **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" }` - 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

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

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

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.) **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

Detects unusual, novel, escalated, or suppressed management disclosures by comparing the latest earnings call / press release against prior periods, for one or more tickers at once. **How it works:** - For each ticker: validates the ticker, retrieves its latest earnings call or press release, and compares it against recent prior documents of the same type - documentTypes (optional): omit to analyze whichever of an earnings call / press release is most recent (one row per ticker). Provide one or both types to get a row per ticker per requested type. Each row's documentType field says which it is. - Uses an AI analysis pass to surface disclosures that are newly added, escalated, withdrawn, or downgraded etc. - Returns previously generated findings when available, otherwise generates them on demand - Each ticker (and type) is processed independently; one failing never fails the rest **Output Contents:** - results: one entry per requested ticker — or per ticker × documentType when documentTypes is provided — each with: - status: ready (findings returned) | not_found (no stock, or no matching document) | error (analysis failed) - ticker: Stock ticker symbol - eventDate: Source document release date (YYYY-MM-DD) - documentType: Source document type (Earnings Call or Press Release) - period: Fiscal period analyzed (e.g., Q3 2024) - resultJson: Findings split into new_and_escalated, withdrawn_and_suppressed, and a disclosure_balance_assessment - message: Per-row status or error detail **Example Usage:** - Latest disclosure (either type) for a watchlist: `{ tickers: ["AAPL", "MSFT", "NVDA"] }` - Force the earnings call: `{ tickers: ["AAPL"], documentTypes: ["Earnings call"] }` - Both types per ticker: `{ tickers: ["AAPL"], documentTypes: ["Earnings call", "Press Release"] }`

unusual-disclosure

Updates an existing watchlist for the current user. **Input Behavior:** - watchlistId (required): ID of the watchlist to update - name (optional): New name for the watchlist (1-255 characters) - tickers (optional): Full replacement list of stock tickers. If provided, replaces all existing stocks in the watchlist. **Output Contents:** - watchlist: The updated watchlist object containing: - id: Unique identifier - name: Watchlist name - tickers: List of stock ticker symbols - updated: Always true on success **Example Usage:** - Rename a watchlist: `{ "watchlistId": 123, "name": "New Name" }` - Update stocks: `{ "watchlistId": 123, "tickers": ["AAPL", "MSFT", "GOOGL"] }` - Both: `{ "watchlistId": 123, "name": "Tech Giants", "tickers": ["AAPL", "MSFT"] }` **Notes:** - A watchlist that is deleted, does not exist, or belongs to another user returns a not-found error.

watchlist-update

Retrieves the value-chain peer list for a ticker. Returns ordered value-chain members for the authenticated user and ticker. **Input:** - ticker: Base company ticker **Output:** - topologyId: Internal topology id (if available) - members[]: Ordered value-chain members with ticker/name/type

value-chain