{ "$schema": "https://tempestshaw.github.io/FinanceCLI/schemas/finance-cli-tools.schema.json", "name": "finresearch-cli", "version": "0.1.0b0", "description": "Machine-readable Finance CLI command metadata for LLM agents, MCP adapters, and plugin wrappers.", "canonical_docs": "https://tempestshaw.github.io/FinanceCLI/", "result_envelope": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "description": "Command-specific payload. Null when ok is false." }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "record_schema": { "type": "object", "required": [ "entity", "kind", "fields" ], "properties": { "entity": { "type": "string", "description": "Ticker, company, query, market, or other record subject." }, "kind": { "type": "string", "description": "Normalized fact type, usually derived from the command or row collection." }, "period": { "type": [ "string", "null" ], "description": "Fiscal or reporting period when available." }, "timestamp": { "type": [ "string", "null" ], "description": "Date or timestamp when available." }, "fields": { "type": "object", "description": "Record-specific facts after entity/kind/time/source extraction." }, "source": { "type": [ "string", "null" ], "description": "Provider, filing, or document source when available." }, "metadata": { "type": [ "object", "null" ], "description": "Optional adapter metadata for retrieval or audit trails." } }, "additionalProperties": false }, "output_formats": { "json": { "description": "Canonical command result envelope. Preserves ok, data, error, and warnings for audit and tool contracts.", "record_renderer": false }, "text": { "description": "Legacy plain text view for humans.", "record_renderer": false }, "compact": { "description": "Pipe-delimited normalized records with repeated keys removed where practical.", "record_renderer": true }, "schema": { "description": "Schema-once row format: one header line plus compact rows for repeated records.", "record_renderer": true } }, "side_effect_levels": { "pure_calculation": "No network, no filesystem read, no mutation.", "local_file_read": "Reads local files supplied by the caller. Does not mutate files.", "network_read_only": "Reads remote public/provider data. Does not mutate external state.", "local_or_network_read": "Reads a local path or remote URL supplied by the caller. Does not mutate files or external state." }, "trust_policy": { "cite_when_available": [ "accession", "accession_no", "url", "report_name", "section", "page", "start_char", "end_char", "source", "provider", "timestamp" ], "market_data": "Never present market data without provider/source and timestamp/date fields when available.", "source_truth": "Treat Yahoo, FMP, SEC, GDELT, transcripts, and company IR as source-specific records, not ground truth.", "credentials": "API keys are read from environment variables at runtime and are not written by the CLI." }, "playbooks": [ { "task": "extract_metric_from_10k", "when": "The user asks for a metric or table value from a company's latest 10-K.", "steps": [ "filings.recent", "filings.statement", "document.scan", "document.window", "formula.*" ], "failure_modes": [ "If no XBRL row matches, fall back to filings.reports then document.scan.", "If document.scan finds multiple matches, use document.window around each candidate and cite offsets." ] }, { "task": "explain_price_move", "when": "The user asks what happened around a dated price move.", "steps": [ "price.moves", "price.context", "news.search", "filings.recent", "transcripts.search" ], "failure_modes": [ "If no dated evidence appears, say the CLI found no direct evidence rather than inferring causality.", "Always cite provider, date, and URL/accession when available." ] }, { "task": "screen_and_contextualize_equities", "when": "The user asks for market ideas from predefined Yahoo screens.", "steps": [ "screen.predefined", "screen.run", "symbol.snapshot", "market.quote", "filings.recent" ], "failure_modes": [ "If a screen returns fewer rows than requested, keep the returned count and source.", "Do not describe screen membership as a recommendation." ] }, { "task": "run_reproducible_backtest", "when": "The user asks to test a strategy over explicit symbols and dates.", "steps": [ "backtest.strategies", "backtest.describe", "backtest.run", "backtest.tune" ], "failure_modes": [ "If provider data is unavailable, fail clearly with the provider error.", "Preserve strategy name, symbols, dates, params, and JSON output." ] } ], "commands": [ { "name": "backtest.describe", "namespace": "backtest", "description": "Describe a backtest strategy and its parameters", "usage": "finance backtest.describe STRATEGY", "examples": [ "finance backtest.describe sma_cross", "finance backtest.describe custom" ], "notes": [], "args": { "strategy": { "type": "string", "description": "Built-in strategy key.", "required": true } }, "input_schema": { "type": "object", "properties": { "strategy": { "type": "string", "description": "Built-in strategy key." } }, "required": [ "strategy" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Backtest metrics, trades, plots, or payload metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "none", "rate_limit_notes": "Provider data downloads may be rate limited.", "citation_fields": [], "agent": { "use_when": "Use for repeatable strategy checks, payload construction, and VectorBT result summaries.", "avoid_when": "Do not present backtests as live trading recommendations.", "next_steps": [] } }, { "name": "backtest.factor.payload", "namespace": "backtest", "description": "Build a normalized factor backtest payload", "usage": "finance backtest.factor.payload FACTOR_NAME SYMBOLS START_DATE END_DATE [timeframe=1d top_pct=0.2 bottom_pct=0.2]", "examples": [ "finance backtest.factor.payload rsi_14 AAPL,MSFT,NVDA 2024-01-01 2024-12-31" ], "notes": [], "args": { "factor_name": { "type": "string", "description": "Name assigned to the factor signal.", "required": true }, "symbols": { "type": "string", "description": "Ticker symbol or comma-separated ticker list.", "required": true }, "start_date": { "type": "string", "format": "date", "description": "Start date.", "required": true }, "end_date": { "type": "string", "format": "date", "description": "End date.", "required": true }, "timeframe": { "type": "string", "description": "Provider-supported timeframe or research horizon.", "required": false, "default": "1d" }, "top_pct": { "type": "number", "description": "Top-ranked percentage used for the long or overweight side.", "default": 0.2, "required": false }, "bottom_pct": { "type": "number", "description": "Bottom-ranked percentage used for the short or underweight side.", "default": 0.2, "required": false } }, "input_schema": { "type": "object", "properties": { "factor_name": { "type": "string", "description": "Name assigned to the factor signal." }, "symbols": { "type": "string", "description": "Ticker symbol or comma-separated ticker list." }, "start_date": { "type": "string", "format": "date", "description": "Start date." }, "end_date": { "type": "string", "format": "date", "description": "End date." }, "timeframe": { "type": "string", "description": "Provider-supported timeframe or research horizon.", "default": "1d" }, "top_pct": { "type": "number", "description": "Top-ranked percentage used for the long or overweight side.", "default": 0.2 }, "bottom_pct": { "type": "number", "description": "Bottom-ranked percentage used for the short or underweight side.", "default": 0.2 } }, "required": [ "factor_name", "symbols", "start_date", "end_date" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Backtest metrics, trades, plots, or payload metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "none", "rate_limit_notes": "Provider data downloads may be rate limited.", "citation_fields": [], "agent": { "use_when": "Use for repeatable strategy checks, payload construction, and VectorBT result summaries.", "avoid_when": "Do not present backtests as live trading recommendations.", "next_steps": [] } }, { "name": "backtest.factor.weights", "namespace": "backtest", "description": "Preview quantile factor target weights", "usage": "finance backtest.factor.weights FACTOR_NAME scores='{\"AAPL\":1.2,\"MSFT\":0.4}' [top_pct=0.2 bottom_pct=0.2]", "examples": [ "finance backtest.factor.weights rsi_14 scores='{\"AAPL\":1.1,\"MSFT\":0.3,\"NVDA\":2.0}'" ], "notes": [], "args": { "factor_name": { "type": "string", "description": "Name assigned to the factor signal.", "required": true }, "scores": { "type": "string", "description": "Mapping of symbols to factor scores.", "required": true }, "top_pct": { "type": "number", "description": "Top-ranked percentage used for the long or overweight side.", "default": 0.2, "required": false }, "bottom_pct": { "type": "number", "description": "Bottom-ranked percentage used for the short or underweight side.", "default": 0.2, "required": false } }, "input_schema": { "type": "object", "properties": { "factor_name": { "type": "string", "description": "Name assigned to the factor signal." }, "scores": { "type": "string", "description": "Mapping of symbols to factor scores." }, "top_pct": { "type": "number", "description": "Top-ranked percentage used for the long or overweight side.", "default": 0.2 }, "bottom_pct": { "type": "number", "description": "Bottom-ranked percentage used for the short or underweight side.", "default": 0.2 } }, "required": [ "factor_name", "scores" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Backtest metrics, trades, plots, or payload metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "none", "rate_limit_notes": "Provider data downloads may be rate limited.", "citation_fields": [], "agent": { "use_when": "Use for repeatable strategy checks, payload construction, and VectorBT result summaries.", "avoid_when": "Do not present backtests as live trading recommendations.", "next_steps": [] } }, { "name": "backtest.run", "namespace": "backtest", "description": "Run a VectorBT strategy backtest", "usage": "finance backtest.run STRATEGY SYMBOLS START_DATE END_DATE [params='{}' strategy_file=./rule.py]", "examples": [ "finance backtest.run sma_cross AAPL 2020-01-01 2024-12-31 fast=20 slow=100", "finance backtest.run custom AAPL 2020-01-01 2024-12-31 strategy_file=./rule.py params='{}'" ], "notes": [], "args": { "strategy": { "type": "string", "description": "Built-in strategy key.", "required": true }, "symbols": { "type": "string", "description": "Ticker symbol or comma-separated ticker list.", "required": true }, "start_date": { "type": "string", "format": "date", "description": "Start date.", "required": true }, "end_date": { "type": "string", "format": "date", "description": "End date.", "required": true }, "params": { "type": "object", "description": "Strategy parameters supplied as JSON or key-value pairs.", "required": false, "default": "{}" }, "strategy_file": { "type": "string", "description": "Path to a custom strategy file.", "required": false, "default": "./rule.py" } }, "input_schema": { "type": "object", "properties": { "strategy": { "type": "string", "description": "Built-in strategy key." }, "symbols": { "type": "string", "description": "Ticker symbol or comma-separated ticker list." }, "start_date": { "type": "string", "format": "date", "description": "Start date." }, "end_date": { "type": "string", "format": "date", "description": "End date." }, "params": { "type": "object", "description": "Strategy parameters supplied as JSON or key-value pairs.", "default": "{}" }, "strategy_file": { "type": "string", "description": "Path to a custom strategy file.", "default": "./rule.py" } }, "required": [ "strategy", "symbols", "start_date", "end_date" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Backtest metrics, trades, plots, or payload metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "none", "rate_limit_notes": "Provider data downloads may be rate limited.", "citation_fields": [], "agent": { "use_when": "Use when the user asks to run a named strategy over explicit symbols and dates.", "avoid_when": "Do not use as proof a strategy will work live.", "next_steps": [] } }, { "name": "backtest.strategies", "namespace": "backtest", "description": "List VectorBT-backed strategy presets", "usage": "finance backtest.strategies", "examples": [ "finance backtest.strategies" ], "notes": [], "args": {}, "input_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Backtest metrics, trades, plots, or payload metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "none", "rate_limit_notes": "Provider data downloads may be rate limited.", "citation_fields": [], "agent": { "use_when": "Use for repeatable strategy checks, payload construction, and VectorBT result summaries.", "avoid_when": "Do not present backtests as live trading recommendations.", "next_steps": [] } }, { "name": "backtest.strategy.payload", "namespace": "backtest", "description": "Build a normalized strategy backtest payload", "usage": "finance backtest.strategy.payload STRATEGY_ID START_DATE END_DATE [initial_cash=100000 parameters='{}']", "examples": [ "finance backtest.strategy.payload mean_reversion 2024-01-01 2024-12-31" ], "notes": [], "args": { "strategy_id": { "type": "string", "description": "Built-in strategy key to describe, run, or package.", "required": true }, "start_date": { "type": "string", "format": "date", "description": "Start date.", "required": true }, "end_date": { "type": "string", "format": "date", "description": "End date.", "required": true }, "initial_cash": { "type": "integer", "description": "Starting cash balance for the simulation.", "default": 100000, "required": false }, "parameters": { "type": "object", "description": "Strategy parameter object included in the payload.", "required": false, "default": "{}" } }, "input_schema": { "type": "object", "properties": { "strategy_id": { "type": "string", "description": "Built-in strategy key to describe, run, or package." }, "start_date": { "type": "string", "format": "date", "description": "Start date." }, "end_date": { "type": "string", "format": "date", "description": "End date." }, "initial_cash": { "type": "integer", "description": "Starting cash balance for the simulation.", "default": 100000 }, "parameters": { "type": "object", "description": "Strategy parameter object included in the payload.", "default": "{}" } }, "required": [ "strategy_id", "start_date", "end_date" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Backtest metrics, trades, plots, or payload metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "none", "rate_limit_notes": "Provider data downloads may be rate limited.", "citation_fields": [], "agent": { "use_when": "Use for repeatable strategy checks, payload construction, and VectorBT result summaries.", "avoid_when": "Do not present backtests as live trading recommendations.", "next_steps": [] } }, { "name": "backtest.tune", "namespace": "backtest", "description": "Run a bounded VectorBT parameter grid", "usage": "finance backtest.tune STRATEGY SYMBOLS START_DATE END_DATE grid='{}' [metric=sharpe_ratio max_runs=100]", "examples": [ "finance backtest.tune sma_cross AAPL 2020-01-01 2024-12-31 grid='{\"fast\":[10,20],\"slow\":[50,100]}'" ], "notes": [], "args": { "strategy": { "type": "string", "description": "Built-in strategy key.", "required": true }, "symbols": { "type": "string", "description": "Ticker symbol or comma-separated ticker list.", "required": true }, "start_date": { "type": "string", "format": "date", "description": "Start date.", "required": true }, "end_date": { "type": "string", "format": "date", "description": "End date.", "required": true }, "grid": { "type": "object", "description": "Parameter grid where each key maps to candidate values.", "required": true }, "metric": { "type": "string", "description": "Metric used to rank tuning results.", "required": false, "default": "sharpe_ratio" }, "max_runs": { "type": "integer", "description": "Maximum parameter combinations to evaluate.", "default": 100, "required": false } }, "input_schema": { "type": "object", "properties": { "strategy": { "type": "string", "description": "Built-in strategy key." }, "symbols": { "type": "string", "description": "Ticker symbol or comma-separated ticker list." }, "start_date": { "type": "string", "format": "date", "description": "Start date." }, "end_date": { "type": "string", "format": "date", "description": "End date." }, "grid": { "type": "object", "description": "Parameter grid where each key maps to candidate values." }, "metric": { "type": "string", "description": "Metric used to rank tuning results.", "default": "sharpe_ratio" }, "max_runs": { "type": "integer", "description": "Maximum parameter combinations to evaluate.", "default": 100 } }, "required": [ "strategy", "symbols", "start_date", "end_date", "grid" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Backtest metrics, trades, plots, or payload metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "none", "rate_limit_notes": "Provider data downloads may be rate limited.", "citation_fields": [], "agent": { "use_when": "Use for repeatable strategy checks, payload construction, and VectorBT result summaries.", "avoid_when": "Do not present backtests as live trading recommendations.", "next_steps": [] } }, { "name": "calendar.company", "namespace": "calendar", "description": "Fetch company earnings/dividend calendar fields", "usage": "finance calendar.company SYMBOL", "examples": [ "finance calendar.company AAPL" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Company calendar or earnings-date rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo Finance responses can vary by symbol and session.", "citation_fields": [], "agent": { "use_when": "Use for company calendar fields and earnings-date rows.", "avoid_when": null, "next_steps": [] } }, { "name": "calendar.earnings", "namespace": "calendar", "description": "Fetch earnings-date rows for a company", "usage": "finance calendar.earnings SYMBOL [limit=12]", "examples": [ "finance calendar.earnings AAPL limit=8" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 12, "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 12 } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Company calendar or earnings-date rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo Finance responses can vary by symbol and session.", "citation_fields": [], "agent": { "use_when": "Use for company calendar fields and earnings-date rows.", "avoid_when": null, "next_steps": [] } }, { "name": "document.ocr", "namespace": "document", "description": "Run PaddleOCR/PP-StructureV3 OCR fallback on a local or remote document", "usage": "finance document.ocr SOURCE|source=PATH_OR_URL [max_chars=12000 max_pages=5]", "examples": [ "finance document.ocr ./deck.pdf max_pages=3", "finance document.ocr ./deck.pdf max_chars=4000" ], "notes": [ "Prefer document.read or document.scan for text-based PDFs.", "Uses the default Finance CLI OCR stack.", "Use as fallback for scanned or image-heavy documents." ], "args": { "source": { "type": "string", "description": "Source key, path, or URL depending on command.", "required": true }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 12000, "required": false }, "max_pages": { "type": "integer", "description": "Maximum PDF pages to read.", "default": 5, "required": false } }, "input_schema": { "type": "object", "properties": { "source": { "type": "string", "description": "Source key, path, or URL depending on command." }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 12000 }, "max_pages": { "type": "integer", "description": "Maximum PDF pages to read.", "default": 5 } }, "required": [ "source" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Document text, blocks, matches, tables, OCR, or window metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "local_or_network_read", "side_effects_description": "Reads a local path or remote URL supplied by the caller. Does not mutate files or external state.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [ "source", "url", "path", "page", "start_char", "end_char", "match_id" ], "agent": { "use_when": "Use as fallback for scanned or image-heavy PDFs after document.read/scan cannot extract text.", "avoid_when": null, "next_steps": [] } }, { "name": "document.read", "namespace": "document", "description": "Extract native PDF or HTML text and layout/search blocks", "usage": "finance document.read SOURCE|source=PATH_OR_URL [format=pdf|html max_chars=12000 max_pages=5]", "examples": [ "finance document.read ./deck.pdf max_pages=3", "finance document.read ./deck.pdf max_chars=4000", "finance document.read ./filing.html format=html max_chars=4000" ], "notes": [ "Lightweight first-pass parser for text-based PDFs and HTML filings; does not run OCR.", "Returns page text plus positioned or offset-bearing blocks for downstream matching and analysis." ], "args": { "source": { "type": "string", "description": "Source key, path, or URL depending on command.", "required": true }, "format": { "type": "string", "enum": [ "pdf", "html" ], "required": false, "description": "Value supplied for `format`." }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 12000, "required": false }, "max_pages": { "type": "integer", "description": "Maximum PDF pages to read.", "default": 5, "required": false } }, "input_schema": { "type": "object", "properties": { "source": { "type": "string", "description": "Source key, path, or URL depending on command." }, "format": { "type": "string", "enum": [ "pdf", "html" ], "description": "Value supplied for `format`." }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 12000 }, "max_pages": { "type": "integer", "description": "Maximum PDF pages to read.", "default": 5 } }, "required": [ "source" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Document text, blocks, matches, tables, OCR, or window metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "local_or_network_read", "side_effects_description": "Reads a local path or remote URL supplied by the caller. Does not mutate files or external state.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [ "source", "url", "path", "page", "start_char", "end_char", "match_id" ], "agent": { "use_when": "Use for first-pass text extraction from a known PDF or SEC HTML URL.", "avoid_when": null, "next_steps": [ "document.scan", "document.window", "document.tables", "document.ocr" ] } }, { "name": "document.scan", "namespace": "document", "description": "Scan document text/layout for configured topics or literal queries with RapidFuzz", "usage": "finance document.scan SOURCE|source=PATH_OR_URL [query=TEXT topics=risk,disclosure format=pdf|html match=fuzzy|all_terms threshold=80 max_chars=12000 max_pages=5 limit=50 window=0 start_char=0 end_char=0]", "examples": [ "finance document.scan ./report.pdf topics=risk,financial_reporting", "finance document.scan ./deck.pdf topics=guidance threshold=75 max_pages=10", "finance document.scan ./filing.html format=html query='Operating lease costs' max_chars=0 window=1200", "finance document.scan ./filing.html format=html match=all_terms threshold=100 query='Receivables net Total current assets' max_chars=0", "finance document.scan ./filing.html format=html start_char=122000 query='Accounts payable'" ], "notes": [ "Uses PyMuPDF for native PDF layout, BeautifulSoup for HTML text, and RapidFuzz for deterministic fuzzy matching.", "Known topics include disclosure, risk, financial_reporting, portfolio, and guidance.", "Unknown topics are treated as literal fuzzy queries.", "Use match=all_terms threshold=100 for table-style queries where every meaningful query word should appear.", "Use start_char/end_char to restrict a follow-up scan to a known section or window.", "HTML matches include char offsets and match IDs that can be passed to document.window." ], "args": { "source": { "type": "string", "required": true, "aliases": [ "path", "url" ], "description": "Local path or URL." }, "query": { "type": "string", "required": false, "description": "Literal phrase or table text to find." }, "topics": { "type": "array", "items": { "type": "string" }, "required": false, "description": "Known topic names or literal queries." }, "format": { "type": "string", "required": false, "enum": [ "pdf", "html" ], "description": "Document format override." }, "match": { "type": "string", "required": false, "default": "fuzzy", "enum": [ "fuzzy", "all_terms" ], "description": "Match mode." }, "threshold": { "type": "number", "required": false, "default": 80.0, "description": "Fuzzy score threshold." }, "max_chars": { "type": "integer", "required": false, "default": 12000, "description": "Maximum text chars to read; 0 means unbounded in current readers." }, "max_pages": { "type": "integer", "required": false, "default": 5, "description": "Maximum pages for PDFs; 0 means all pages." }, "limit": { "type": "integer", "required": false, "default": 50, "description": "Maximum matches." }, "window": { "type": "integer", "required": false, "default": 0, "description": "Optional context chars per match." }, "start_char": { "type": "integer", "required": false, "description": "Start offset for a bounded scan." }, "end_char": { "type": "integer", "required": false, "description": "End offset for a bounded scan." } }, "input_schema": { "type": "object", "properties": { "source": { "type": "string", "description": "Local path or URL." }, "query": { "type": "string", "description": "Literal phrase or table text to find." }, "topics": { "type": "array", "items": { "type": "string" }, "description": "Known topic names or literal queries." }, "format": { "type": "string", "enum": [ "pdf", "html" ], "description": "Document format override." }, "match": { "type": "string", "default": "fuzzy", "enum": [ "fuzzy", "all_terms" ], "description": "Match mode." }, "threshold": { "type": "number", "default": 80.0, "description": "Fuzzy score threshold." }, "max_chars": { "type": "integer", "default": 12000, "description": "Maximum text chars to read; 0 means unbounded in current readers." }, "max_pages": { "type": "integer", "default": 5, "description": "Maximum pages for PDFs; 0 means all pages." }, "limit": { "type": "integer", "default": 50, "description": "Maximum matches." }, "window": { "type": "integer", "default": 0, "description": "Optional context chars per match." }, "start_char": { "type": "integer", "description": "Start offset for a bounded scan." }, "end_char": { "type": "integer", "description": "End offset for a bounded scan." } }, "required": [ "source" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string" }, "matches": { "type": "array", "items": { "type": "object" } }, "count": { "type": "integer" }, "char_count": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "local_or_network_read", "side_effects_description": "Reads a local path or remote URL supplied by the caller. Does not mutate files or external state.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [ "source", "url", "path", "page", "start_char", "end_char", "match_id" ], "agent": { "use_when": "Use when the user needs phrase, table, or topic discovery inside a filing or document.", "avoid_when": null, "next_steps": [ "document.window", "formula.*" ] } }, { "name": "document.tables", "namespace": "document", "description": "Extract compact table previews from text-based PDFs with Camelot", "usage": "finance document.tables SOURCE|source=PATH_OR_URL [pages=1-end flavor=stream|lattice max_tables=20 max_rows=25]", "examples": [ "finance document.tables ./report.pdf pages=10-12 flavor=stream", "finance document.tables ./filing.pdf pages=all max_tables=5 max_rows=10" ], "notes": [ "Uses the default Finance CLI table extraction stack.", "Use flavor=stream for whitespace-separated tables and flavor=lattice for ruled-line tables.", "Returns compact row previews with page, shape, accuracy, and truncation metadata." ], "args": { "source": { "type": "string", "description": "Source key, path, or URL depending on command.", "required": true }, "pages": { "type": "string", "description": "PDF page selection passed to the table extractor.", "required": false, "default": "1-end" }, "flavor": { "type": "string", "description": "PDF table extraction flavor.", "enum": [ "stream", "lattice" ], "required": false }, "max_tables": { "type": "integer", "description": "Maximum extracted tables to return.", "default": 20, "required": false }, "max_rows": { "type": "integer", "description": "Maximum rows to return.", "default": 25, "required": false } }, "input_schema": { "type": "object", "properties": { "source": { "type": "string", "description": "Source key, path, or URL depending on command." }, "pages": { "type": "string", "description": "PDF page selection passed to the table extractor.", "default": "1-end" }, "flavor": { "type": "string", "description": "PDF table extraction flavor.", "enum": [ "stream", "lattice" ] }, "max_tables": { "type": "integer", "description": "Maximum extracted tables to return.", "default": 20 }, "max_rows": { "type": "integer", "description": "Maximum rows to return.", "default": 25 } }, "required": [ "source" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Document text, blocks, matches, tables, OCR, or window metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "local_or_network_read", "side_effects_description": "Reads a local path or remote URL supplied by the caller. Does not mutate files or external state.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [ "source", "url", "path", "page", "start_char", "end_char", "match_id" ], "agent": { "use_when": "Use for table previews in text-based PDFs when text windows are not enough.", "avoid_when": null, "next_steps": [] } }, { "name": "document.window", "namespace": "document", "description": "Read a bounded text window around a document offset or scan match ID", "usage": "finance document.window SOURCE|source=PATH_OR_URL [format=pdf|html start_char=0|match_id=char_START_END chars=4000 direction=around|next|previous]", "examples": [ "finance document.window ./filing.html format=html start_char=52000 chars=4000", "finance document.window ./filing.html format=html match_id=char_52000_52200 direction=next chars=4000" ], "notes": [ "Designed for follow-up reading after document.scan.", "Use direction=next or direction=previous to move through a table or section without re-scanning." ], "args": { "source": { "type": "string", "required": true, "aliases": [ "path", "url" ], "description": "Local path or URL." }, "format": { "type": "string", "required": false, "enum": [ "pdf", "html" ], "description": "Document format override." }, "start_char": { "type": "integer", "required": false, "description": "Character offset." }, "match_id": { "type": "string", "required": false, "description": "Match id returned by document.scan." }, "chars": { "type": "integer", "required": false, "default": 4000, "description": "Window size in characters." }, "direction": { "type": "string", "required": false, "default": "around", "enum": [ "around", "next", "previous" ], "description": "Window direction." } }, "input_schema": { "type": "object", "properties": { "source": { "type": "string", "description": "Local path or URL." }, "format": { "type": "string", "enum": [ "pdf", "html" ], "description": "Document format override." }, "start_char": { "type": "integer", "description": "Character offset." }, "match_id": { "type": "string", "description": "Match id returned by document.scan." }, "chars": { "type": "integer", "default": 4000, "description": "Window size in characters." }, "direction": { "type": "string", "default": "around", "enum": [ "around", "next", "previous" ], "description": "Window direction." } }, "required": [ "source" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Document text, blocks, matches, tables, OCR, or window metadata.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "local_or_network_read", "side_effects_description": "Reads a local path or remote URL supplied by the caller. Does not mutate files or external state.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [ "source", "url", "path", "page", "start_char", "end_char", "match_id" ], "agent": { "use_when": "Use after document.scan to read around a stable char offset or match_id without re-scanning the full document.", "avoid_when": null, "next_steps": [] } }, { "name": "estimates.compare", "namespace": "estimates", "description": "Compare user assumptions against explicit consensus inputs", "usage": "finance estimates.compare [SYMBOL] revenue=2.2B consensus_revenue=2.0B eps=0.50 consensus_eps=0.45 fiscal_year=2027", "examples": [ "finance estimates.compare IOT revenue=2.2B consensus_revenue=2.0B eps=0.50 consensus_eps=0.45 fiscal_year=2027" ], "notes": [ "No network calls. Compares only values explicitly supplied by the caller." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": false }, "revenue": { "type": "string", "description": "Reported, assumed, or user-supplied revenue input.", "required": true }, "consensus_revenue": { "type": "string", "description": "Consensus revenue estimate used for comparison.", "required": true }, "eps": { "type": "number", "description": "Reported or assumed EPS value used for comparison.", "required": true }, "consensus_eps": { "type": "number", "description": "Consensus EPS estimate used for comparison.", "required": true }, "fiscal_year": { "type": "integer", "description": "Fiscal year for the reported or estimated period.", "required": true } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "revenue": { "type": "string", "description": "Reported, assumed, or user-supplied revenue input." }, "consensus_revenue": { "type": "string", "description": "Consensus revenue estimate used for comparison." }, "eps": { "type": "number", "description": "Reported or assumed EPS value used for comparison." }, "consensus_eps": { "type": "number", "description": "Consensus EPS estimate used for comparison." }, "fiscal_year": { "type": "integer", "description": "Fiscal year for the reported or estimated period." } }, "required": [ "revenue", "consensus_revenue", "eps", "consensus_eps", "fiscal_year" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Consensus estimate or comparison result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use for explicit estimate comparison math and structured consensus result shaping.", "avoid_when": null, "next_steps": [] } }, { "name": "estimates.consensus", "namespace": "estimates", "description": "Fetch FMP analyst consensus estimates when configured", "usage": "finance estimates.consensus SYMBOL [period=annual|quarter limit=10 page=0]", "examples": [ "finance estimates.consensus IOT period=annual limit=5" ], "notes": [ "Requires FMP_API_KEY. Makes one short FMP request and returns a structured configuration error when unconfigured." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "period": { "type": "string", "description": "Financial statement period, such as annual or quarterly.", "enum": [ "annual", "quarter" ], "required": false }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 10, "required": false }, "page": { "type": "integer", "description": "Page number to request from the provider.", "default": 0, "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "period": { "type": "string", "description": "Financial statement period, such as annual or quarterly.", "enum": [ "annual", "quarter" ] }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 10 }, "page": { "type": "integer", "description": "Page number to request from the provider.", "default": 0 } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Consensus estimate or comparison result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use for explicit estimate comparison math and structured consensus result shaping.", "avoid_when": null, "next_steps": [] } }, { "name": "filings.read", "namespace": "filings", "description": "Read a canonical 10-K section with edgartools", "usage": "finance filings.read [SYMBOL] [accession=ACCESSION|url=URL] [form=10-K section=business|risk_factors|mda|segments max_chars=8000]", "examples": [ "finance filings.read IOT section=business max_chars=3000", "finance filings.read accession=0001628280-26-018167 section=risk_factors max_chars=3000", "finance filings.read url=https://www.sec.gov/Archives/edgar/data/1642896/000162828026018167/iot-20260131.htm section=mda" ], "notes": [ "Uses edgartools for filing retrieval, then returns bounded text for downstream use." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": false }, "accession": { "type": "string", "description": "SEC accession number.", "required": false }, "url": { "type": "string", "format": "uri", "description": "Remote URL.", "required": false }, "form": { "type": "string", "description": "SEC form type.", "required": false, "default": "10-K" }, "section": { "type": "string", "description": "Filing section key.", "enum": [ "business", "risk_factors", "mda", "segments" ], "required": false }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 8000, "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "accession": { "type": "string", "description": "SEC accession number." }, "url": { "type": "string", "format": "uri", "description": "Remote URL." }, "form": { "type": "string", "description": "SEC form type.", "default": "10-K" }, "section": { "type": "string", "description": "Filing section key.", "enum": [ "business", "risk_factors", "mda", "segments" ] }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 8000 } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "SEC filing metadata, section text, reports, or XBRL rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "SEC/EDGAR availability and provider throttling can affect live calls.", "citation_fields": [ "symbol", "accession_no", "accession", "url", "form", "report_name", "section" ], "agent": { "use_when": "Use when the user asks for a canonical 10-K section such as business, risk factors, MD&A, or segments.", "avoid_when": null, "next_steps": [ "document.scan", "document.window" ] } }, { "name": "filings.recent", "namespace": "filings", "description": "Fetch recent SEC filings, optionally classified", "usage": "finance filings.recent SYMBOL [forms=8-K,10-Q limit=20 classify=false]", "examples": [ "finance filings.recent NVDA forms=10-Q,8-K limit=5", "finance filings.recent NVDA forms=8-K limit=10 classify=true" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "forms": { "type": "string", "description": "Comma-separated SEC form types to include.", "required": false, "default": "8-K,10-Q" }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 20, "required": false }, "classify": { "type": "boolean", "description": "Classify filing events when supported.", "default": false, "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "forms": { "type": "string", "description": "Comma-separated SEC form types to include.", "default": "8-K,10-Q" }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 20 }, "classify": { "type": "boolean", "description": "Classify filing events when supported.", "default": false } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "SEC filing metadata, section text, reports, or XBRL rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "SEC/EDGAR availability and provider throttling can affect live calls.", "citation_fields": [ "symbol", "accession_no", "accession", "url", "form", "report_name", "section" ], "agent": { "use_when": "Use first when the user names a ticker but not a filing URL or accession.", "avoid_when": null, "next_steps": [ "filings.sections", "filings.statement", "filings.report", "document.scan" ] } }, { "name": "filings.report", "namespace": "filings", "description": "Read an edgartools filing summary report", "usage": "finance filings.report [SYMBOL] [accession=ACCESSION|url=URL] name='Report Short Name' [form=10-K query=TEXT max_rows=25 (0=unlimited) max_chars=8000]", "examples": [ "finance filings.report COST name='Consolidated Balance Sheets (Parenthetical)'", "finance filings.report COST name='Leases, Supplemental Balance Sheet Information' query='operating lease liabilities'", "finance filings.report url=https://www.sec.gov/Archives/edgar/data/909832/000090983224000049/cost-20240901.htm name='Debt'" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": false }, "accession": { "type": "string", "description": "SEC accession number.", "required": false }, "url": { "type": "string", "format": "uri", "description": "Remote URL.", "required": false }, "name": { "type": "string", "description": "Report, section, or table name selected by the caller.", "required": true }, "form": { "type": "string", "description": "SEC form type.", "required": false, "default": "10-K" }, "query": { "type": "string", "description": "Search query.", "required": false }, "max_rows": { "type": "integer", "description": "Maximum rows to return.", "default": 25, "required": false }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 8000, "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "accession": { "type": "string", "description": "SEC accession number." }, "url": { "type": "string", "format": "uri", "description": "Remote URL." }, "name": { "type": "string", "description": "Report, section, or table name selected by the caller." }, "form": { "type": "string", "description": "SEC form type.", "default": "10-K" }, "query": { "type": "string", "description": "Search query." }, "max_rows": { "type": "integer", "description": "Maximum rows to return.", "default": 25 }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 8000 } }, "required": [ "name" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "SEC filing metadata, section text, reports, or XBRL rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "SEC/EDGAR availability and provider throttling can affect live calls.", "citation_fields": [ "symbol", "accession_no", "accession", "url", "form", "report_name", "section" ], "agent": { "use_when": "Use when the user already knows or discovered an edgartools report name and wants rows from that report.", "avoid_when": null, "next_steps": [] } }, { "name": "filings.reports", "namespace": "filings", "description": "List edgartools filing summary reports", "usage": "finance filings.reports [SYMBOL] [accession=ACCESSION|url=URL] [form=10-K query=lease]", "examples": [ "finance filings.reports COST form=10-K", "finance filings.reports COST form=10-K query=lease", "finance filings.reports url=https://www.sec.gov/Archives/edgar/data/909832/000090983224000049/cost-20240901.htm" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": false }, "accession": { "type": "string", "description": "SEC accession number.", "required": false }, "url": { "type": "string", "format": "uri", "description": "Remote URL.", "required": false }, "form": { "type": "string", "description": "SEC form type.", "required": false, "default": "10-K" }, "query": { "type": "string", "description": "Search query.", "required": false, "default": "lease" } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "accession": { "type": "string", "description": "SEC accession number." }, "url": { "type": "string", "format": "uri", "description": "Remote URL." }, "form": { "type": "string", "description": "SEC form type.", "default": "10-K" }, "query": { "type": "string", "description": "Search query.", "default": "lease" } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "SEC filing metadata, section text, reports, or XBRL rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "SEC/EDGAR availability and provider throttling can affect live calls.", "citation_fields": [ "symbol", "accession_no", "accession", "url", "form", "report_name", "section" ], "agent": { "use_when": "Use for SEC filing discovery, canonical section reads, XBRL statement rows, and filing summary reports.", "avoid_when": null, "next_steps": [] } }, { "name": "filings.sections", "namespace": "filings", "description": "List supported and discovered filing sections", "usage": "finance filings.sections [SYMBOL] [accession=ACCESSION|url=URL] [form=10-K]", "examples": [ "finance filings.sections IOT form=10-K", "finance filings.sections accession=0001628280-26-018167" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": false }, "accession": { "type": "string", "description": "SEC accession number.", "required": false }, "url": { "type": "string", "format": "uri", "description": "Remote URL.", "required": false }, "form": { "type": "string", "description": "SEC form type.", "required": false, "default": "10-K" } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "accession": { "type": "string", "description": "SEC accession number." }, "url": { "type": "string", "format": "uri", "description": "Remote URL." }, "form": { "type": "string", "description": "SEC form type.", "default": "10-K" } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "SEC filing metadata, section text, reports, or XBRL rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "SEC/EDGAR availability and provider throttling can affect live calls.", "citation_fields": [ "symbol", "accession_no", "accession", "url", "form", "report_name", "section" ], "agent": { "use_when": "Use for SEC filing discovery, canonical section reads, XBRL statement rows, and filing summary reports.", "avoid_when": null, "next_steps": [] } }, { "name": "filings.statement", "namespace": "filings", "description": "Read structured XBRL statement rows with edgartools", "usage": "finance filings.statement [SYMBOL] [accession=ACCESSION|url=URL] [form=10-K statement=income|balance|cashflow query=TEXT max_rows=0]", "examples": [ "finance filings.statement COST statement=balance query='Common Stock'", "finance filings.statement url=https://www.sec.gov/Archives/edgar/data/909832/000090983224000049/cost-20240901.htm statement=income max_rows=20" ], "notes": [ "Returns raw XBRL values plus reported values scaled by XBRL decimals." ], "args": { "symbol": { "type": "string", "required": false, "description": "Ticker used to locate a recent filing." }, "accession": { "type": "string", "required": false, "aliases": [ "accession_no" ], "description": "SEC accession number." }, "url": { "type": "string", "required": false, "format": "uri", "description": "Direct SEC filing URL." }, "form": { "type": "string", "required": false, "default": "10-K", "description": "SEC form used when resolving by symbol." }, "statement": { "type": "string", "required": false, "default": "income", "enum": [ "income", "balance", "cashflow" ], "description": "Statement family." }, "query": { "type": "string", "required": false, "description": "Optional row label search." }, "max_rows": { "type": "integer", "required": false, "default": 0, "description": "Maximum rows; 0 means unlimited." }, "include_abstract": { "type": "boolean", "required": false, "default": false, "description": "Include abstract rows when true." } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker used to locate a recent filing." }, "accession": { "type": "string", "description": "SEC accession number." }, "url": { "type": "string", "format": "uri", "description": "Direct SEC filing URL." }, "form": { "type": "string", "default": "10-K", "description": "SEC form used when resolving by symbol." }, "statement": { "type": "string", "default": "income", "enum": [ "income", "balance", "cashflow" ], "description": "Statement family." }, "query": { "type": "string", "description": "Optional row label search." }, "max_rows": { "type": "integer", "default": 0, "description": "Maximum rows; 0 means unlimited." }, "include_abstract": { "type": "boolean", "default": false, "description": "Include abstract rows when true." } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "properties": { "symbol": { "type": [ "string", "null" ] }, "accession_no": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "statement": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object" } }, "count": { "type": "integer" }, "source": { "type": "string" } }, "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "SEC/EDGAR availability and provider throttling can affect live calls.", "citation_fields": [ "symbol", "accession_no", "accession", "url", "form", "report_name", "section" ], "agent": { "use_when": "Use when the user asks for structured XBRL financial statement rows such as income, balance, or cashflow items.", "avoid_when": "Do not use for narrative section text or non-XBRL table discovery.", "next_steps": [ "filings.report", "document.scan", "formula.*" ] } }, { "name": "formula.adjusted_ebitda", "namespace": "formula", "description": "Calculate adjusted EBITDA from explicit addbacks", "usage": "finance formula.adjusted_ebitda ebit=9285 d_and_a=2237 addbacks=284,163", "examples": [ "finance formula.adjusted_ebitda ebit=9285 d_and_a=2237 addbacks=284,163" ], "notes": [], "args": { "ebit": { "type": "number", "required": true, "description": "Value supplied for `ebit`." }, "d_and_a": { "type": "number", "required": true, "description": "Value supplied for `d_and_a`." }, "addbacks": { "type": "array", "items": { "type": "number" }, "required": false, "default": [], "description": "Comma-separated addback values." } }, "input_schema": { "type": "object", "properties": { "ebit": { "type": "number", "description": "Value supplied for `ebit`." }, "d_and_a": { "type": "number", "description": "Value supplied for `d_and_a`." }, "addbacks": { "type": "array", "items": { "type": "number" }, "default": [], "description": "Comma-separated addback values." } }, "required": [ "ebit", "d_and_a" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.cagr", "namespace": "formula", "description": "Calculate compound annual growth rate", "usage": "finance formula.cagr start=100 end=150 periods=3", "examples": [ "finance formula.cagr start=100 end=150 periods=3" ], "notes": [], "args": { "start": { "type": "number", "required": true, "description": "Value supplied for `start`." }, "end": { "type": "number", "required": true, "description": "Value supplied for `end`." }, "periods": { "type": "number", "required": true, "description": "Value supplied for `periods`." } }, "input_schema": { "type": "object", "properties": { "start": { "type": "number", "description": "Value supplied for `start`." }, "end": { "type": "number", "description": "Value supplied for `end`." }, "periods": { "type": "number", "description": "Value supplied for `periods`." } }, "required": [ "start", "end", "periods" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.capm", "namespace": "formula", "description": "Calculate CAPM cost of equity", "usage": "finance formula.capm risk_free=4.617% beta=0.79 market_return=11%", "examples": [ "finance formula.capm risk_free=4.617% beta=0.79 market_return=11%" ], "notes": [], "args": { "risk_free": { "type": "number", "required": true, "description": "Value supplied for `risk_free`." }, "beta": { "type": "number", "required": true, "description": "Value supplied for `beta`." }, "market_return": { "type": "number", "required": true, "description": "Value supplied for `market_return`." } }, "input_schema": { "type": "object", "properties": { "risk_free": { "type": "number", "description": "Value supplied for `risk_free`." }, "beta": { "type": "number", "description": "Value supplied for `beta`." }, "market_return": { "type": "number", "description": "Value supplied for `market_return`." } }, "required": [ "risk_free", "beta", "market_return" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.days", "namespace": "formula", "description": "Calculate average-balance days", "usage": "finance formula.days current=2721 prior=2285 denominator=254453 [days=365]", "examples": [ "finance formula.days current=2721 prior=2285 denominator=254453" ], "notes": [], "args": { "current": { "type": "number", "required": true, "description": "Value supplied for `current`." }, "prior": { "type": "number", "required": true, "description": "Value supplied for `prior`." }, "denominator": { "type": "number", "required": true, "description": "Value supplied for `denominator`." }, "days": { "type": "number", "default": 365, "required": false, "description": "Value supplied for `days`." } }, "input_schema": { "type": "object", "properties": { "current": { "type": "number", "description": "Value supplied for `current`." }, "prior": { "type": "number", "description": "Value supplied for `prior`." }, "denominator": { "type": "number", "description": "Value supplied for `denominator`." }, "days": { "type": "number", "default": 365, "description": "Value supplied for `days`." } }, "required": [ "current", "prior", "denominator" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.ebitda", "namespace": "formula", "description": "Calculate EBITDA from explicit EBIT and D&A inputs", "usage": "finance formula.ebitda ebit=9285 d_and_a=2237", "examples": [ "finance formula.ebitda ebit=9285 d_and_a=2237" ], "notes": [], "args": { "ebit": { "type": "number", "required": true, "description": "Value supplied for `ebit`." }, "d_and_a": { "type": "number", "required": true, "description": "Value supplied for `d_and_a`." } }, "input_schema": { "type": "object", "properties": { "ebit": { "type": "number", "description": "Value supplied for `ebit`." }, "d_and_a": { "type": "number", "description": "Value supplied for `d_and_a`." } }, "required": [ "ebit", "d_and_a" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.enterprise_value", "namespace": "formula", "description": "Calculate enterprise value with explicit operating cash", "usage": "finance formula.enterprise_value market_equity=418856 debt=11415 cash=11144 operating_cash=5089", "examples": [ "finance formula.enterprise_value market_equity=418856 debt=11415 cash=11144 operating_cash=5089" ], "notes": [], "args": { "market_equity": { "type": "number", "required": true, "description": "Value supplied for `market_equity`." }, "debt": { "type": "number", "required": false, "default": 0, "description": "Debt value." }, "cash": { "type": "number", "required": false, "default": 0, "description": "Cash value." }, "operating_cash": { "type": "number", "required": false, "default": 0, "description": "Cash treated as operating rather than excess." } }, "input_schema": { "type": "object", "properties": { "market_equity": { "type": "number", "description": "Value supplied for `market_equity`." }, "debt": { "type": "number", "default": 0, "description": "Debt value." }, "cash": { "type": "number", "default": 0, "description": "Cash value." }, "operating_cash": { "type": "number", "default": 0, "description": "Cash treated as operating rather than excess." } }, "required": [ "market_equity" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.lease_equivalent", "namespace": "formula", "description": "Estimate lease equivalent from cost ratio", "usage": "finance formula.lease_equivalent base_liability=2554 variable_cost=163 operating_cost=284", "examples": [ "finance formula.lease_equivalent base_liability=2554 variable_cost=163 operating_cost=284" ], "notes": [], "args": { "base_liability": { "type": "number", "required": true, "description": "Value supplied for `base_liability`." }, "variable_cost": { "type": "number", "required": true, "description": "Value supplied for `variable_cost`." }, "operating_cost": { "type": "number", "required": true, "description": "Value supplied for `operating_cost`." } }, "input_schema": { "type": "object", "properties": { "base_liability": { "type": "number", "description": "Value supplied for `base_liability`." }, "variable_cost": { "type": "number", "description": "Value supplied for `variable_cost`." }, "operating_cost": { "type": "number", "description": "Value supplied for `operating_cost`." } }, "required": [ "base_liability", "variable_cost", "operating_cost" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.margin", "namespace": "formula", "description": "Calculate numerator / denominator", "usage": "finance formula.margin numerator=11969 denominator=254453", "examples": [ "finance formula.margin numerator=11969 denominator=254453" ], "notes": [], "args": { "numerator": { "type": "number", "required": true, "description": "Value supplied for `numerator`." }, "denominator": { "type": "number", "required": true, "description": "Value supplied for `denominator`." } }, "input_schema": { "type": "object", "properties": { "numerator": { "type": "number", "description": "Value supplied for `numerator`." }, "denominator": { "type": "number", "description": "Value supplied for `denominator`." } }, "required": [ "numerator", "denominator" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use for explicit numerator/denominator ratio math after cited inputs are known.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.net_debt", "namespace": "formula", "description": "Calculate net debt with explicit operating cash", "usage": "finance formula.net_debt debt=11415 cash=11144 [operating_cash=5089]", "examples": [ "finance formula.net_debt debt=11415 cash=11144 operating_cash=5089" ], "notes": [], "args": { "debt": { "type": "number", "required": true, "description": "Value supplied for `debt`." }, "cash": { "type": "number", "required": true, "description": "Value supplied for `cash`." }, "operating_cash": { "type": "number", "default": 5089, "required": false, "description": "Value supplied for `operating_cash`." } }, "input_schema": { "type": "object", "properties": { "debt": { "type": "number", "description": "Value supplied for `debt`." }, "cash": { "type": "number", "description": "Value supplied for `cash`." }, "operating_cash": { "type": "number", "default": 5089, "description": "Value supplied for `operating_cash`." } }, "required": [ "debt", "cash" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.operating_cash", "namespace": "formula", "description": "Calculate operating cash as min(percent of revenue, cash-like assets)", "usage": "finance formula.operating_cash revenue=254453 cash_like_assets=11144 [percent_revenue=2%]", "examples": [ "finance formula.operating_cash revenue=254453 cash_like_assets=11144 percent_revenue=2%" ], "notes": [], "args": { "revenue": { "type": "number", "description": "Reported, assumed, or user-supplied revenue input.", "required": true }, "cash_like_assets": { "type": "number", "required": true, "description": "Value supplied for `cash_like_assets`." }, "percent_revenue": { "type": "number", "required": false, "default": "2%", "description": "Value supplied for `percent_revenue`." } }, "input_schema": { "type": "object", "properties": { "revenue": { "type": "number", "description": "Reported, assumed, or user-supplied revenue input." }, "cash_like_assets": { "type": "number", "description": "Value supplied for `cash_like_assets`." }, "percent_revenue": { "type": "number", "default": "2%", "description": "Value supplied for `percent_revenue`." } }, "required": [ "revenue", "cash_like_assets" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.operating_current_assets", "namespace": "formula", "description": "Calculate operating current assets", "usage": "finance formula.operating_current_assets current_assets=34246 [cash_like_assets=11144 operating_cash=5089]", "examples": [ "finance formula.operating_current_assets current_assets=34246 cash_like_assets=11144 operating_cash=5089" ], "notes": [], "args": { "current_assets": { "type": "number", "required": true, "description": "Value supplied for `current_assets`." }, "cash_like_assets": { "type": "number", "default": 11144, "required": false, "description": "Value supplied for `cash_like_assets`." }, "operating_cash": { "type": "number", "default": 5089, "required": false, "description": "Value supplied for `operating_cash`." } }, "input_schema": { "type": "object", "properties": { "current_assets": { "type": "number", "description": "Value supplied for `current_assets`." }, "cash_like_assets": { "type": "number", "default": 11144, "description": "Value supplied for `cash_like_assets`." }, "operating_cash": { "type": "number", "default": 5089, "description": "Value supplied for `operating_cash`." } }, "required": [ "current_assets" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.operating_current_liabilities", "namespace": "formula", "description": "Calculate operating current liabilities", "usage": "finance formula.operating_current_liabilities current_liabilities=35464 [interest_bearing_current_debt=103]", "examples": [ "finance formula.operating_current_liabilities current_liabilities=35464 interest_bearing_current_debt=103" ], "notes": [], "args": { "current_liabilities": { "type": "number", "required": true, "description": "Value supplied for `current_liabilities`." }, "interest_bearing_current_debt": { "type": "number", "default": 103, "required": false, "description": "Value supplied for `interest_bearing_current_debt`." } }, "input_schema": { "type": "object", "properties": { "current_liabilities": { "type": "number", "description": "Value supplied for `current_liabilities`." }, "interest_bearing_current_debt": { "type": "number", "default": 103, "description": "Value supplied for `interest_bearing_current_debt`." } }, "required": [ "current_liabilities" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.roic", "namespace": "formula", "description": "Calculate ROIC from NOPAT and invested capital", "usage": "finance formula.roic nopat=7113 invested_capital=28077", "examples": [ "finance formula.roic nopat=7113 invested_capital=28077" ], "notes": [], "args": { "nopat": { "type": "number", "required": true, "description": "Value supplied for `nopat`." }, "invested_capital": { "type": "number", "required": true, "description": "Value supplied for `invested_capital`." } }, "input_schema": { "type": "object", "properties": { "nopat": { "type": "number", "description": "Value supplied for `nopat`." }, "invested_capital": { "type": "number", "description": "Value supplied for `invested_capital`." } }, "required": [ "nopat", "invested_capital" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.turnover", "namespace": "formula", "description": "Calculate turnover using average balance", "usage": "finance formula.turnover numerator=222358 current=18647 prior=16651", "examples": [ "finance formula.turnover numerator=222358 current=18647 prior=16651" ], "notes": [], "args": { "numerator": { "type": "number", "required": true, "description": "Value supplied for `numerator`." }, "current": { "type": "number", "required": true, "description": "Value supplied for `current`." }, "prior": { "type": "number", "required": true, "description": "Value supplied for `prior`." } }, "input_schema": { "type": "object", "properties": { "numerator": { "type": "number", "description": "Value supplied for `numerator`." }, "current": { "type": "number", "description": "Value supplied for `current`." }, "prior": { "type": "number", "description": "Value supplied for `prior`." } }, "required": [ "numerator", "current", "prior" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.wacc", "namespace": "formula", "description": "Calculate WACC with explicit debt tax convention", "usage": "finance formula.wacc equity_value=418856 debt_value=11415 cost_of_equity=9.66% cost_of_debt=6% tax_rate=24% debt_tax=pretax|after_tax", "examples": [ "finance formula.wacc equity_value=418856 debt_value=11415 cost_of_equity=9.66% cost_of_debt=6% tax_rate=24% debt_tax=pretax" ], "notes": [], "args": { "equity_value": { "type": "number", "description": "Equity market value used in WACC or valuation math.", "required": true }, "debt_value": { "type": "number", "description": "Debt value used in WACC or valuation math.", "required": true }, "cost_of_equity": { "type": "number", "description": "Cost of equity. CLI accepts decimal or percent.", "required": true }, "cost_of_debt": { "type": "number", "description": "Cost of debt. CLI accepts decimal or percent.", "required": true }, "tax_rate": { "type": "number", "required": false, "default": 0, "description": "Tax rate; CLI accepts decimal or percent." }, "debt_tax": { "type": "string", "required": false, "default": "after_tax", "enum": [ "pretax", "after_tax" ], "description": "Whether cost_of_debt is pretax or already after tax." } }, "input_schema": { "type": "object", "properties": { "equity_value": { "type": "number", "description": "Equity market value used in WACC or valuation math." }, "debt_value": { "type": "number", "description": "Debt value used in WACC or valuation math." }, "cost_of_equity": { "type": "number", "description": "Cost of equity. CLI accepts decimal or percent." }, "cost_of_debt": { "type": "number", "description": "Cost of debt. CLI accepts decimal or percent." }, "tax_rate": { "type": "number", "default": 0, "description": "Tax rate; CLI accepts decimal or percent." }, "debt_tax": { "type": "string", "default": "after_tax", "enum": [ "pretax", "after_tax" ], "description": "Whether cost_of_debt is pretax or already after tax." } }, "required": [ "equity_value", "debt_value", "cost_of_equity", "cost_of_debt" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "formula.working_capital", "namespace": "formula", "description": "Calculate operating working capital", "usage": "finance formula.working_capital operating_current_assets=28191 operating_current_liabilities=35035", "examples": [ "finance formula.working_capital operating_current_assets=28191 operating_current_liabilities=35035" ], "notes": [], "args": { "operating_current_assets": { "type": "number", "required": true, "description": "Value supplied for `operating_current_assets`." }, "operating_current_liabilities": { "type": "number", "required": true, "description": "Value supplied for `operating_current_liabilities`." } }, "input_schema": { "type": "object", "properties": { "operating_current_assets": { "type": "number", "description": "Value supplied for `operating_current_assets`." }, "operating_current_liabilities": { "type": "number", "description": "Value supplied for `operating_current_liabilities`." } }, "required": [ "operating_current_assets", "operating_current_liabilities" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Deterministic calculation with inputs and method.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only when all numeric inputs are explicit in the prompt or already extracted with citations.", "avoid_when": "Do not invent missing inputs. Ask for them or extract them first.", "next_steps": [] } }, { "name": "fundamentals.statement", "namespace": "fundamentals", "description": "Fetch income/balance/cashflow statement data", "usage": "finance fundamentals.statement SYMBOL [statement=income|balance|cashflow period=annual|quarterly]", "examples": [ "finance fundamentals.statement NVDA statement=income period=quarterly" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "statement": { "type": "string", "enum": [ "income", "balance", "cashflow" ], "description": "Financial statement family.", "required": false }, "period": { "type": "string", "description": "Financial statement period, such as annual or quarterly.", "enum": [ "annual", "quarterly" ], "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "statement": { "type": "string", "enum": [ "income", "balance", "cashflow" ], "description": "Financial statement family." }, "period": { "type": "string", "description": "Financial statement period, such as annual or quarterly.", "enum": [ "annual", "quarterly" ] } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Statement rows from Yahoo Finance.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo Finance responses can vary by symbol and session.", "citation_fields": [], "agent": { "use_when": "Use for Yahoo financial statement tables outside SEC filing context.", "avoid_when": null, "next_steps": [] } }, { "name": "industry.keys", "namespace": "industry", "description": "List Yahoo industry keys, optionally filtered by sector", "usage": "finance industry.keys [sector=SECTOR_KEY]", "examples": [ "finance industry.keys sector=technology" ], "notes": [], "args": { "sector": { "type": "string", "description": "Sector key or sector name to query.", "required": false } }, "input_schema": { "type": "object", "properties": { "sector": { "type": "string", "description": "Sector key or sector name to query." } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Yahoo industry key, overview, or table result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo Finance sector/industry coverage can change.", "citation_fields": [], "agent": { "use_when": "Use for Yahoo industry keys, overview data, top companies, and research-report tables.", "avoid_when": null, "next_steps": [] } }, { "name": "industry.overview", "namespace": "industry", "description": "Fetch industry overview metadata", "usage": "finance industry.overview KEY", "examples": [ "finance industry.overview software-infrastructure" ], "notes": [], "args": { "key": { "type": "string", "description": "Provider key returned by the corresponding list command.", "required": true } }, "input_schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Provider key returned by the corresponding list command." } }, "required": [ "key" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Yahoo industry key, overview, or table result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo Finance sector/industry coverage can change.", "citation_fields": [], "agent": { "use_when": "Use for Yahoo industry keys, overview data, top companies, and research-report tables.", "avoid_when": null, "next_steps": [] } }, { "name": "industry.table", "namespace": "industry", "description": "Fetch industry top companies or reports", "usage": "finance industry.table KEY [table=top_companies|top_growth_companies|top_performing_companies|research_reports limit=25]", "examples": [ "finance industry.table software-infrastructure table=top_companies limit=10", "finance industry.table software-infrastructure table=top_growth_companies limit=10" ], "notes": [], "args": { "key": { "type": "string", "description": "Provider key returned by the corresponding list command.", "required": true }, "table": { "type": "string", "description": "Provider table name to return.", "enum": [ "top_companies", "top_growth_companies", "top_performing_companies", "research_reports" ], "required": false }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 25, "required": false } }, "input_schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Provider key returned by the corresponding list command." }, "table": { "type": "string", "description": "Provider table name to return.", "enum": [ "top_companies", "top_growth_companies", "top_performing_companies", "research_reports" ] }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 25 } }, "required": [ "key" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Yahoo industry key, overview, or table result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo Finance sector/industry coverage can change.", "citation_fields": [], "agent": { "use_when": "Use for Yahoo industry keys, overview data, top companies, and research-report tables.", "avoid_when": null, "next_steps": [] } }, { "name": "ir.presentations", "namespace": "ir", "description": "Discover IR and investor day presentations from SEC 8-K Exhibit 99 filings", "usage": "finance ir.presentations SYMBOL [limit=20 source=auto|sec|company_ir|all]", "examples": [ "finance ir.presentations IOT", "finance ir.presentations IOT limit=10 source=all", "finance ir.presentations NVDA limit=5 source=sec" ], "notes": [ "Scans recent 8-K filings for Exhibit 99 files with presentation or slides keywords.", "source=auto uses SEC first, then company IR fallback when SEC finds no candidates.", "source=all combines SEC and company IR candidates.", "Press releases and earnings releases are filtered unless a distinct deck/slides signal is present.", "confidence: high = strong presentation signal, medium = weaker or conflicting signal.", "kind: investor_day | earnings_presentation | ir_presentation | exhibit_99", "Use ir.read url=URL to extract text from a candidate." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 20, "required": false }, "source": { "type": "string", "description": "Source key, path, or URL depending on command.", "enum": [ "auto", "sec", "company_ir", "all" ], "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 20 }, "source": { "type": "string", "description": "Source key, path, or URL depending on command.", "enum": [ "auto", "sec", "company_ir", "all" ] } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Investor-presentation discovery or text extraction result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "url", "filing_url", "accession_no", "source" ], "agent": { "use_when": "Use to discover or read investor presentations from SEC exhibits and company IR pages.", "avoid_when": null, "next_steps": [] } }, { "name": "ir.read", "namespace": "ir", "description": "Extract text from an IR presentation exhibit URL", "usage": "finance ir.read url=URL [max_chars=12000 ocr=off|auto|force]", "examples": [ "finance ir.read url=https://www.sec.gov/Archives/edgar/data/320193/000032019326000013/aapl-20260328.htm", "finance ir.read url=https://www.sec.gov/Archives/edgar/data/320193/000032019326000013/aapl-20260328.htm ocr=off max_chars=4000" ], "notes": [ "HTML exhibits/pages are fetched and parsed to plain text.", "PDF extraction uses pypdf and returns page-level text when possible.", "ocr=auto or ocr=force uses the default PaddleOCR/PP-StructureV3 stack.", "Pass the url from ir.presentations output." ], "args": { "url": { "type": "string", "format": "uri", "description": "Remote URL.", "required": true }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 12000, "required": false }, "ocr": { "type": "string", "description": "OCR mode for presentation or document text extraction.", "enum": [ "off", "auto", "force" ], "required": false } }, "input_schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Remote URL." }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 12000 }, "ocr": { "type": "string", "description": "OCR mode for presentation or document text extraction.", "enum": [ "off", "auto", "force" ] } }, "required": [ "url" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Investor-presentation discovery or text extraction result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "url", "filing_url", "accession_no", "source" ], "agent": { "use_when": "Use to discover or read investor presentations from SEC exhibits and company IR pages.", "avoid_when": null, "next_steps": [] } }, { "name": "kpi.extract", "namespace": "kpi", "description": "Extract KPI evidence from filings or transcripts", "usage": "finance kpi.extract SYMBOL [source=transcripts|filings|both metrics=arr,nrr limit=30 quarter=latest form=10-K]", "examples": [ "finance kpi.extract IOT source=transcripts metrics=arr,net_new_arr,large_customers,nrr", "finance kpi.extract IOT source=both metrics=arr,emerging_products,rpo limit=20" ], "notes": [ "Returns evidence rows, not investment conclusions." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "source": { "type": "string", "description": "Source key, path, or URL depending on command.", "enum": [ "transcripts", "filings", "both" ], "required": false }, "metrics": { "type": "string", "description": "Comma-separated KPI or metric names to search for.", "required": false, "default": "arr,nrr" }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 30, "required": false }, "quarter": { "type": "string", "description": "Fiscal quarter label, such as Q1 or Q4.", "required": false, "default": "latest" }, "form": { "type": "string", "description": "SEC form type.", "required": false, "default": "10-K" } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "source": { "type": "string", "description": "Source key, path, or URL depending on command.", "enum": [ "transcripts", "filings", "both" ] }, "metrics": { "type": "string", "description": "Comma-separated KPI or metric names to search for.", "default": "arr,nrr" }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 30 }, "quarter": { "type": "string", "description": "Fiscal quarter label, such as Q1 or Q4.", "default": "latest" }, "form": { "type": "string", "description": "SEC form type.", "default": "10-K" } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "KPI evidence snippets and history rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "url", "accession_no", "quarter", "metric" ], "agent": { "use_when": "Use to collect KPI evidence from transcripts and filings with source snippets.", "avoid_when": null, "next_steps": [] } }, { "name": "kpi.history", "namespace": "kpi", "description": "Extract KPI evidence across recent transcripts", "usage": "finance kpi.history SYMBOL [source=transcripts metrics=arr,nrr limit=4 per_document_limit=20]", "examples": [ "finance kpi.history IOT metrics=arr,large_customers,emerging_products limit=4" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "source": { "type": "string", "description": "Source key, path, or URL depending on command.", "required": false, "default": "transcripts" }, "metrics": { "type": "string", "description": "Comma-separated KPI or metric names to search for.", "required": false, "default": "arr,nrr" }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 4, "required": false }, "per_document_limit": { "type": "integer", "description": "Maximum KPI evidence rows per source document.", "default": 20, "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "source": { "type": "string", "description": "Source key, path, or URL depending on command.", "default": "transcripts" }, "metrics": { "type": "string", "description": "Comma-separated KPI or metric names to search for.", "default": "arr,nrr" }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 4 }, "per_document_limit": { "type": "integer", "description": "Maximum KPI evidence rows per source document.", "default": 20 } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "KPI evidence snippets and history rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "url", "accession_no", "quarter", "metric" ], "agent": { "use_when": "Use to collect KPI evidence from transcripts and filings with source snippets.", "avoid_when": null, "next_steps": [] } }, { "name": "market.ohlcv", "namespace": "market", "description": "Fetch normalized OHLCV records for one or more symbols", "usage": "finance market.ohlcv SYMBOL[,SYMBOL...] [timeframe=1d start_date=YYYY-MM-DD end_date=YYYY-MM-DD limit=200 provider=auto include_attempts=false]", "examples": [ "finance market.ohlcv NVDA timeframe=1d limit=20", "finance market.ohlcv AAPL,MSFT,NVDA timeframe=1d limit=5 provider=auto" ], "notes": [ "Arguments use key=value syntax for script-friendly CLI calls." ], "args": { "timeframe": { "type": "string", "required": false, "default": "1d", "description": "Bar interval." }, "start_date": { "type": "string", "required": false, "format": "date", "description": "Start date." }, "end_date": { "type": "string", "required": false, "format": "date", "description": "End date." }, "limit": { "type": "integer", "required": false, "default": 200, "description": "Maximum bars when date bounds are not enough." }, "provider": { "type": "string", "required": false, "default": "auto", "description": "Provider selection." }, "include_attempts": { "type": "boolean", "required": false, "default": false, "description": "Include provider-attempt diagnostics." }, "symbols": { "type": "string", "required": true, "description": "One ticker or comma-separated tickers." } }, "input_schema": { "type": "object", "properties": { "timeframe": { "type": "string", "default": "1d", "description": "Bar interval." }, "start_date": { "type": "string", "format": "date", "description": "Start date." }, "end_date": { "type": "string", "format": "date", "description": "End date." }, "limit": { "type": "integer", "default": 200, "description": "Maximum bars when date bounds are not enough." }, "provider": { "type": "string", "default": "auto", "description": "Provider selection." }, "include_attempts": { "type": "boolean", "default": false, "description": "Include provider-attempt diagnostics." }, "symbols": { "type": "string", "description": "One ticker or comma-separated tickers." } }, "required": [ "symbols" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Quote, bars, market status, regime, or sector heat data.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Market data is time-sensitive and provider-specific.", "citation_fields": [ "symbol", "date", "source", "provider" ], "agent": { "use_when": "Use for historical bars needed by backtests, event windows, and price context.", "avoid_when": null, "next_steps": [] } }, { "name": "market.quote", "namespace": "market", "description": "Fetch quote via the best available provider", "usage": "finance market.quote SYMBOL", "examples": [ "finance market.quote NVDA" ], "notes": [ "Uses Alpha Vantage when configured, with Yahoo fallback." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Quote, bars, market status, regime, or sector heat data.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Market data is time-sensitive and provider-specific.", "citation_fields": [ "symbol", "source", "provider", "timestamp" ], "agent": { "use_when": "Use for a current provider quote or compact company market snapshot.", "avoid_when": null, "next_steps": [] } }, { "name": "market.regime", "namespace": "market", "description": "Show market regime context", "usage": "finance market.regime [MARKET=US] [TIMEFRAME=swing]", "examples": [ "finance market.regime US swing" ], "notes": [], "args": { "market": { "type": "string", "description": "Market code.", "default": "US", "required": false }, "timeframe": { "type": "string", "description": "Provider-supported timeframe or research horizon.", "required": false, "default": "swing" } }, "input_schema": { "type": "object", "properties": { "market": { "type": "string", "description": "Market code.", "default": "US" }, "timeframe": { "type": "string", "description": "Provider-supported timeframe or research horizon.", "default": "swing" } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Quote, bars, market status, regime, or sector heat data.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Market data is time-sensitive and provider-specific.", "citation_fields": [], "agent": { "use_when": "Use for quotes, OHLCV, market status, broad regime, and sector heat context.", "avoid_when": null, "next_steps": [] } }, { "name": "market.sector_heat", "namespace": "market", "description": "Show sector heat rankings", "usage": "finance market.sector_heat [MARKET=US] [LOOKBACK_DAYS=20] [GROUP_BY=sector]", "examples": [ "finance market.sector_heat US 20 sector" ], "notes": [], "args": { "market": { "type": "string", "description": "Market code.", "default": "US", "required": false }, "lookback_days": { "type": "integer", "description": "Lookback window in calendar days.", "default": 20, "required": false }, "group_by": { "type": "string", "description": "Aggregation grouping for analysis output.", "required": false, "default": "sector" } }, "input_schema": { "type": "object", "properties": { "market": { "type": "string", "description": "Market code.", "default": "US" }, "lookback_days": { "type": "integer", "description": "Lookback window in calendar days.", "default": 20 }, "group_by": { "type": "string", "description": "Aggregation grouping for analysis output.", "default": "sector" } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Quote, bars, market status, regime, or sector heat data.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Market data is time-sensitive and provider-specific.", "citation_fields": [], "agent": { "use_when": "Use for quotes, OHLCV, market status, broad regime, and sector heat context.", "avoid_when": null, "next_steps": [] } }, { "name": "market.status", "namespace": "market", "description": "Show Yahoo market open/close status and index summary", "usage": "finance market.status [MARKET=US]", "examples": [ "finance market.status US" ], "notes": [], "args": { "market": { "type": "string", "description": "Market code.", "default": "US", "required": false } }, "input_schema": { "type": "object", "properties": { "market": { "type": "string", "description": "Market code.", "default": "US" } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Quote, bars, market status, regime, or sector heat data.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Market data is time-sensitive and provider-specific.", "citation_fields": [], "agent": { "use_when": "Use to check current market open/close state and major-index summary.", "avoid_when": null, "next_steps": [] } }, { "name": "news.analyze", "namespace": "news", "description": "Analyze news volume, tone, context, or geography", "usage": "finance news.analyze analysis=timeline|tone|context|geo|doc [query=TEXT | symbol=SYMBOL | sector=SECTOR] [mode=MODE max_records=50 timespan=30D|1W|1M|24H date=YYYY-MM-DD start_date=YYYY-MM-DD end_date=YYYY-MM-DD start_datetime=YYYYMMDDHHMMSS end_datetime=YYYYMMDDHHMMSS]", "examples": [ "finance news.analyze symbol=NVDA analysis=timeline timespan=1d", "finance news.analyze symbol=NVDA analysis=timeline timespan=1M", "finance news.analyze query='NVIDIA export controls' analysis=context max_records=5 timespan=24h", "finance news.analyze symbol=IOT analysis=timeline start_date=2026-03-03 end_date=2026-03-09", "finance news.analyze query=FOOD_SECURITY analysis=geo max_records=3 timespan=1h" ], "notes": [ "Use this only when you need trend, tone, context, geo, or raw DOC analysis.", "Use timespan for relative lookback from now, such as 30D, 1W, 1M, 24H, or 90min.", "date/start_date/end_date are preferred for routine use; datetime inputs provide precision controls." ], "args": { "analysis": { "type": "string", "required": true, "enum": [ "timeline", "tone", "context", "geo", "doc" ], "description": "Analysis mode." }, "query": { "type": "string", "description": "Search query.", "required": false }, "symbol": { "type": "string", "description": "Ticker symbol.", "required": false }, "sector": { "type": "string", "description": "Sector key or sector name to query.", "required": false }, "mode": { "type": "string", "description": "Analysis mode.", "required": false }, "max_records": { "type": "integer", "description": "Maximum records to return.", "default": 50, "required": false }, "timespan": { "type": "string", "description": "Relative provider lookback window such as 24H, 7D, or 1M.", "enum": [ "30D", "1W", "1M", "24H" ], "required": false }, "date": { "type": "string", "format": "date", "description": "Date.", "required": false, "default": "YYYY-MM-DD" }, "start_date": { "type": "string", "format": "date", "description": "Start date.", "required": false, "default": "YYYY-MM-DD" }, "end_date": { "type": "string", "format": "date", "description": "End date.", "required": false, "default": "YYYY-MM-DD" }, "start_datetime": { "type": "string", "description": "Inclusive start timestamp for precise provider queries.", "required": false }, "end_datetime": { "type": "string", "description": "Inclusive end timestamp for precise provider queries.", "required": false } }, "input_schema": { "type": "object", "properties": { "analysis": { "type": "string", "enum": [ "timeline", "tone", "context", "geo", "doc" ], "description": "Analysis mode." }, "query": { "type": "string", "description": "Search query." }, "symbol": { "type": "string", "description": "Ticker symbol." }, "sector": { "type": "string", "description": "Sector key or sector name to query." }, "mode": { "type": "string", "description": "Analysis mode." }, "max_records": { "type": "integer", "description": "Maximum records to return.", "default": 50 }, "timespan": { "type": "string", "description": "Relative provider lookback window such as 24H, 7D, or 1M.", "enum": [ "30D", "1W", "1M", "24H" ] }, "date": { "type": "string", "format": "date", "description": "Date.", "default": "YYYY-MM-DD" }, "start_date": { "type": "string", "format": "date", "description": "Start date.", "default": "YYYY-MM-DD" }, "end_date": { "type": "string", "format": "date", "description": "End date.", "default": "YYYY-MM-DD" }, "start_datetime": { "type": "string", "description": "Inclusive start timestamp for precise provider queries." }, "end_datetime": { "type": "string", "description": "Inclusive end timestamp for precise provider queries." } }, "required": [ "analysis" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "News records or analysis result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "News providers can rate limit and can return sparse windows.", "citation_fields": [ "url", "source", "published_at", "seendate" ], "agent": { "use_when": "Use for source-attributed news search and GDELT analysis windows.", "avoid_when": null, "next_steps": [] } }, { "name": "news.search", "namespace": "news", "description": "Search finance news through GDELT", "usage": "finance news.search [query=TEXT | symbol=SYMBOL | sector=SECTOR] [max_records=50 timespan=30D|1W|1M|24H date=YYYY-MM-DD start_date=YYYY-MM-DD end_date=YYYY-MM-DD start_datetime=YYYYMMDDHHMMSS end_datetime=YYYYMMDDHHMMSS]", "examples": [ "finance news.search symbol=NVDA max_records=5", "finance news.search symbol=NVDA timespan=30D max_records=10", "finance news.search symbol=NVDA timespan=1W max_records=10", "finance news.search query='NVIDIA export controls' timespan=24h", "finance news.search symbol=IOT date=2026-03-06 max_records=5", "finance news.search symbol=IOT start_date=2026-03-03 end_date=2026-03-09 max_records=5" ], "notes": [ "Use date for one full day, or start_date/end_date for a full-day range.", "Use timespan for relative lookback from now, such as 30D, 1W, 1M, 24H, or 90min.", "Use start_datetime/end_datetime only when you need second-level precision.", "Use either timespan or fixed date/date-time inputs, not both." ], "args": { "query": { "type": "string", "required": false, "description": "Free-text news query." }, "symbol": { "type": "string", "required": false, "description": "Ticker query." }, "sector": { "type": "string", "required": false, "description": "Sector query." }, "max_records": { "type": "integer", "description": "Maximum records to return.", "default": 50, "required": false }, "timespan": { "type": "string", "description": "Relative provider lookback window such as 24H, 7D, or 1M.", "enum": [ "30D", "1W", "1M", "24H" ], "required": false }, "date": { "type": "string", "format": "date", "description": "Date.", "required": false, "default": "YYYY-MM-DD" }, "start_date": { "type": "string", "format": "date", "description": "Start date.", "required": false, "default": "YYYY-MM-DD" }, "end_date": { "type": "string", "format": "date", "description": "End date.", "required": false, "default": "YYYY-MM-DD" }, "start_datetime": { "type": "string", "description": "Inclusive start timestamp for precise provider queries.", "required": false }, "end_datetime": { "type": "string", "description": "Inclusive end timestamp for precise provider queries.", "required": false } }, "input_schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Free-text news query." }, "symbol": { "type": "string", "description": "Ticker query." }, "sector": { "type": "string", "description": "Sector query." }, "max_records": { "type": "integer", "description": "Maximum records to return.", "default": 50 }, "timespan": { "type": "string", "description": "Relative provider lookback window such as 24H, 7D, or 1M.", "enum": [ "30D", "1W", "1M", "24H" ] }, "date": { "type": "string", "format": "date", "description": "Date.", "default": "YYYY-MM-DD" }, "start_date": { "type": "string", "format": "date", "description": "Start date.", "default": "YYYY-MM-DD" }, "end_date": { "type": "string", "format": "date", "description": "End date.", "default": "YYYY-MM-DD" }, "start_datetime": { "type": "string", "description": "Inclusive start timestamp for precise provider queries." }, "end_datetime": { "type": "string", "description": "Inclusive end timestamp for precise provider queries." } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "News records or analysis result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "News providers can rate limit and can return sparse windows.", "citation_fields": [ "url", "source", "published_at", "seendate" ], "agent": { "use_when": "Use for source-attributed news search and GDELT analysis windows.", "avoid_when": null, "next_steps": [] } }, { "name": "price.context", "namespace": "price", "description": "Return a source-linked evidence timeline around a date", "usage": "finance price.context SYMBOL date=YYYY-MM-DD [lookback=3D news_limit=5 filing_limit=80 transcript_limit=12]", "examples": [ "finance price.context IOT date=2026-03-06 lookback=3D", "finance price.context NVDA date=2025-01-27 lookback=2D news_limit=5", "finance price.context IOT date=2026-03-06 lookback=1W news_limit=5" ], "notes": [ "lookback is calendar time around date: 3D=3 calendar days before and after, 1W=7 calendar days, 1M=30 calendar days.", "Timeline roles are temporal only: before_move, same_day, after_move.", "Event/publication dates are explicit to avoid implied causal claims." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "date": { "type": "string", "format": "date", "description": "Date.", "required": true }, "lookback": { "type": "string", "description": "Lookback window around the requested date.", "required": false, "default": "3D" }, "news_limit": { "type": "integer", "description": "Maximum news records to include.", "default": 5, "required": false }, "filing_limit": { "type": "integer", "description": "Maximum filing records to include.", "default": 80, "required": false }, "transcript_limit": { "type": "integer", "description": "Maximum transcript records to include.", "default": 12, "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "date": { "type": "string", "format": "date", "description": "Date." }, "lookback": { "type": "string", "description": "Lookback window around the requested date.", "default": "3D" }, "news_limit": { "type": "integer", "description": "Maximum news records to include.", "default": 5 }, "filing_limit": { "type": "integer", "description": "Maximum filing records to include.", "default": 80 }, "transcript_limit": { "type": "integer", "description": "Maximum transcript records to include.", "default": 12 } }, "required": [ "symbol", "date" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Price moves or dated evidence timeline.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "date", "source", "url" ], "agent": { "use_when": "Use when the user asks what filings, news, or transcripts were near a dated price move.", "avoid_when": "Do not claim causality unless the evidence explicitly supports it.", "next_steps": [] } }, { "name": "price.moves", "namespace": "price", "description": "Find large deterministic close-to-close stock moves", "usage": "finance price.moves SYMBOL [window=1d|3d|1w|1m years=3 threshold=8|8% limit=20 provider=auto]", "examples": [ "finance price.moves IOT years=3 threshold=8% limit=10", "finance price.moves NVDA window=3d years=2 threshold=12%", "finance price.moves NVDA window=1w years=2 threshold=15 limit=10" ], "notes": [ "window is a trading-day window: 1d=1 trading day, 1w=5 trading days, 1m=21 trading days.", "threshold accepts decimal or percentage-point inputs: 0.08, 8, and 8% all mean 8%.", "Uses one OHLCV fetch and deterministic close-to-close math.", "Returns move dates and magnitude only; it does not infer causality." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "window": { "type": "string", "description": "Trading or text window size, depending on the command.", "enum": [ "1d", "3d", "1w", "1m" ], "required": false }, "years": { "type": "integer", "description": "Number of historical years to inspect.", "default": 3, "required": false }, "threshold": { "type": "string", "description": "Move threshold. CLI accepts decimal or percent notation.", "enum": [ 8, "8%" ], "required": false }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 20, "required": false }, "provider": { "type": "string", "description": "Provider selection.", "required": false, "default": "auto" } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "window": { "type": "string", "description": "Trading or text window size, depending on the command.", "enum": [ "1d", "3d", "1w", "1m" ] }, "years": { "type": "integer", "description": "Number of historical years to inspect.", "default": 3 }, "threshold": { "type": "string", "description": "Move threshold. CLI accepts decimal or percent notation.", "enum": [ 8, "8%" ] }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 20 }, "provider": { "type": "string", "description": "Provider selection.", "default": "auto" } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Price moves or dated evidence timeline.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "date", "source", "url" ], "agent": { "use_when": "Use for price move discovery and evidence timelines around a date.", "avoid_when": "Do not infer causality from price.context alone.", "next_steps": [] } }, { "name": "research.plan", "namespace": "research", "description": "Return a deterministic research command checklist", "usage": "finance research.plan SYMBOL [style=fundamental]", "examples": [ "finance research.plan IOT style=fundamental" ], "notes": [ "This returns suggested commands only; it does not execute research or form conclusions.", "Use this as a navigation layer for repeatable research workflows." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "style": { "type": "string", "required": false, "default": "fundamental", "description": "Value supplied for `style`." } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "style": { "type": "string", "default": "fundamental", "description": "Value supplied for `style`." } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Research checklist.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use before executing a complex public-company research workflow.", "avoid_when": null, "next_steps": [] } }, { "name": "screen.predefined", "namespace": "screen", "description": "List predefined Yahoo equity screens", "usage": "finance screen.predefined", "examples": [ "finance screen.predefined" ], "notes": [], "args": {}, "input_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Yahoo predefined screen metadata or quote rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo screen counts and membership can change intraday.", "citation_fields": [], "agent": { "use_when": "Use to list and run Yahoo predefined equity screens.", "avoid_when": null, "next_steps": [] } }, { "name": "screen.run", "namespace": "screen", "description": "Run a predefined Yahoo equity screen", "usage": "finance screen.run QUERY [count=25 offset=0 sort_field=FIELD sort_asc=false]", "examples": [ "finance screen.run day_gainers count=10" ], "notes": [ "Use screen.predefined to list available query keys.", "count is the maximum number of quotes requested." ], "args": { "query": { "type": "string", "description": "Search query.", "required": true }, "count": { "type": "integer", "description": "Maximum records requested.", "default": 25, "required": false }, "offset": { "type": "integer", "description": "Result offset.", "default": 0, "required": false }, "sort_field": { "type": "string", "description": "Field used to sort screen results.", "required": false }, "sort_asc": { "type": "boolean", "description": "Sort ascending when set.", "default": false, "required": false } }, "input_schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search query." }, "count": { "type": "integer", "description": "Maximum records requested.", "default": 25 }, "offset": { "type": "integer", "description": "Result offset.", "default": 0 }, "sort_field": { "type": "string", "description": "Field used to sort screen results." }, "sort_asc": { "type": "boolean", "description": "Sort ascending when set.", "default": false } }, "required": [ "query" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Yahoo predefined screen metadata or quote rows.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo screen counts and membership can change intraday.", "citation_fields": [], "agent": { "use_when": "Use after screen.predefined when the user asks for Yahoo predefined screen results.", "avoid_when": null, "next_steps": [] } }, { "name": "sector.industries", "namespace": "sector", "description": "List industries in a sector", "usage": "finance sector.industries KEY", "examples": [ "finance sector.industries technology" ], "notes": [], "args": { "key": { "type": "string", "description": "Provider key returned by the corresponding list command.", "required": true } }, "input_schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Provider key returned by the corresponding list command." } }, "required": [ "key" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Yahoo sector key, overview, industries, or table result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo Finance sector/industry coverage can change.", "citation_fields": [], "agent": { "use_when": "Use for Yahoo sector keys, industries, overview data, ETFs, mutual funds, and top companies.", "avoid_when": null, "next_steps": [] } }, { "name": "sector.keys", "namespace": "sector", "description": "List Yahoo sector keys", "usage": "finance sector.keys", "examples": [ "finance sector.keys" ], "notes": [], "args": {}, "input_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Yahoo sector key, overview, industries, or table result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo Finance sector/industry coverage can change.", "citation_fields": [], "agent": { "use_when": "Use for Yahoo sector keys, industries, overview data, ETFs, mutual funds, and top companies.", "avoid_when": null, "next_steps": [] } }, { "name": "sector.overview", "namespace": "sector", "description": "Fetch sector overview metadata", "usage": "finance sector.overview KEY", "examples": [ "finance sector.overview technology" ], "notes": [], "args": { "key": { "type": "string", "description": "Provider key returned by the corresponding list command.", "required": true } }, "input_schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Provider key returned by the corresponding list command." } }, "required": [ "key" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Yahoo sector key, overview, industries, or table result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo Finance sector/industry coverage can change.", "citation_fields": [], "agent": { "use_when": "Use for Yahoo sector keys, industries, overview data, ETFs, mutual funds, and top companies.", "avoid_when": null, "next_steps": [] } }, { "name": "sector.table", "namespace": "sector", "description": "Fetch sector top companies, funds, or reports", "usage": "finance sector.table KEY [table=top_companies|top_etfs|top_mutual_funds|research_reports limit=25]", "examples": [ "finance sector.table technology table=top_companies limit=10", "finance sector.table technology table=top_etfs limit=5" ], "notes": [], "args": { "key": { "type": "string", "description": "Provider key returned by the corresponding list command.", "required": true }, "table": { "type": "string", "description": "Provider table name to return.", "enum": [ "top_companies", "top_etfs", "top_mutual_funds", "research_reports" ], "required": false }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 25, "required": false } }, "input_schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Provider key returned by the corresponding list command." }, "table": { "type": "string", "description": "Provider table name to return.", "enum": [ "top_companies", "top_etfs", "top_mutual_funds", "research_reports" ] }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 25 } }, "required": [ "key" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Yahoo sector key, overview, industries, or table result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": "Yahoo Finance sector/industry coverage can change.", "citation_fields": [], "agent": { "use_when": "Use for Yahoo sector keys, industries, overview data, ETFs, mutual funds, and top companies.", "avoid_when": null, "next_steps": [] } }, { "name": "sources.list", "namespace": "sources", "description": "List finance data sources and capabilities", "usage": "finance sources.list", "examples": [ "finance sources.list" ], "notes": [ "No network calls; reports known providers and capabilities." ], "args": {}, "input_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Provider status, capability list, or test result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use to inspect configured data sources and run provider health probes.", "avoid_when": null, "next_steps": [] } }, { "name": "sources.status", "namespace": "sources", "description": "Show package and environment configuration for data sources", "usage": "finance sources.status", "examples": [ "finance sources.status" ], "notes": [ "No network calls; use sources.test for connectivity checks." ], "args": {}, "input_schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Provider status, capability list, or test result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use to report which providers are configured locally without making provider-specific claims.", "avoid_when": null, "next_steps": [] } }, { "name": "sources.test", "namespace": "sources", "description": "Run small connectivity checks against one or all data sources", "usage": "finance sources.test [SOURCE|source=SOURCE] [symbol=AAPL timeout=30]", "examples": [ "finance sources.test yfinance symbol=AAPL", "finance sources.test sec symbol=AAPL", "finance sources.test source=all symbol=AAPL timeout=30" ], "notes": [ "Returns pass/fail plus latency for configured providers." ], "args": { "source": { "type": "string", "description": "Source key, path, or URL depending on command.", "required": false }, "symbol": { "type": "string", "description": "Ticker symbol.", "required": false }, "timeout": { "type": "integer", "description": "Provider test timeout in seconds.", "default": 30, "required": false } }, "input_schema": { "type": "object", "properties": { "source": { "type": "string", "description": "Source key, path, or URL depending on command." }, "symbol": { "type": "string", "description": "Ticker symbol." }, "timeout": { "type": "integer", "description": "Provider test timeout in seconds.", "default": 30 } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Provider status, capability list, or test result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use for provider connectivity checks when debugging setup.", "avoid_when": null, "next_steps": [] } }, { "name": "symbol.profile", "namespace": "symbol", "description": "Show real quote and SEC company metadata for a symbol", "usage": "finance symbol.profile SYMBOL", "examples": [ "finance symbol.profile IOT" ], "notes": [ "Uses yfinance for market metadata and SEC ticker metadata for CIK/company identity." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Symbol profile or snapshot.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "source", "provider" ], "agent": { "use_when": "Use for a public-company profile or compact symbol snapshot.", "avoid_when": null, "next_steps": [] } }, { "name": "symbol.snapshot", "namespace": "symbol", "description": "Show real quote and company metadata for a symbol", "usage": "finance symbol.snapshot SYMBOL", "examples": [ "finance symbol.snapshot NVDA" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Symbol profile or snapshot.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "source", "provider" ], "agent": { "use_when": "Use for a public-company profile or compact symbol snapshot.", "avoid_when": null, "next_steps": [] } }, { "name": "transcripts.qa", "namespace": "transcripts", "description": "Extract analyst Q&A pairs from a transcript", "usage": "finance transcripts.qa [SYMBOL] [url=URL] [quarter=latest limit=10]", "examples": [ "finance transcripts.qa IOT quarter=latest limit=5" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": false }, "url": { "type": "string", "format": "uri", "description": "Remote URL.", "required": false }, "quarter": { "type": "string", "description": "Fiscal quarter label, such as Q1 or Q4.", "required": false, "default": "latest" }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 10, "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "url": { "type": "string", "format": "uri", "description": "Remote URL." }, "quarter": { "type": "string", "description": "Fiscal quarter label, such as Q1 or Q4.", "default": "latest" }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 10 } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Transcript search, read, or Q&A result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "url", "quarter", "speaker", "published_at" ], "agent": { "use_when": "Use for earnings-call transcript search, reading, and Q&A extraction.", "avoid_when": null, "next_steps": [] } }, { "name": "transcripts.read", "namespace": "transcripts", "description": "Read a transcript and split prepared remarks / Q&A", "usage": "finance transcripts.read [SYMBOL] [url=URL] [quarter=latest max_chars=12000 include_turns=false]", "examples": [ "finance transcripts.read IOT quarter=latest max_chars=4000", "finance transcripts.read IOT include_turns=true max_chars=2000", "finance transcripts.read url=https://www.fool.com/earnings/call-transcripts/2026/03/05/samsara-iot-q4-2026-earnings-call-transcript/" ], "notes": [], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": false }, "url": { "type": "string", "format": "uri", "description": "Remote URL.", "required": false }, "quarter": { "type": "string", "description": "Fiscal quarter label, such as Q1 or Q4.", "required": false, "default": "latest" }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 12000, "required": false }, "include_turns": { "type": "boolean", "description": "Include transcript speaker turns.", "default": false, "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "url": { "type": "string", "format": "uri", "description": "Remote URL." }, "quarter": { "type": "string", "description": "Fiscal quarter label, such as Q1 or Q4.", "default": "latest" }, "max_chars": { "type": "integer", "description": "Maximum text characters to return.", "default": 12000 }, "include_turns": { "type": "boolean", "description": "Include transcript speaker turns.", "default": false } }, "required": [], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Transcript search, read, or Q&A result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "url", "quarter", "speaker", "published_at" ], "agent": { "use_when": "Use for earnings-call transcript search, reading, and Q&A extraction.", "avoid_when": null, "next_steps": [] } }, { "name": "transcripts.search", "namespace": "transcripts", "description": "Search public earnings-call transcripts", "usage": "finance transcripts.search SYMBOL [limit=4 debug=false]", "examples": [ "finance transcripts.search IOT limit=4", "finance transcripts.search IOT debug=true" ], "notes": [ "Uses public Motley Fool transcript pages when available." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 4, "required": false }, "debug": { "type": "boolean", "description": "Include debug details.", "default": false, "required": false } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "limit": { "type": "integer", "description": "Maximum records to return.", "default": 4 }, "debug": { "type": "boolean", "description": "Include debug details.", "default": false } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Transcript search, read, or Q&A result.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "network_read_only", "side_effects_description": "Reads remote public/provider data. Does not mutate external state.", "auth_required": "optional_environment_or_public_provider", "rate_limit_notes": null, "citation_fields": [ "symbol", "url", "quarter", "speaker", "published_at" ], "agent": { "use_when": "Use for earnings-call transcript search, reading, and Q&A extraction.", "avoid_when": null, "next_steps": [] } }, { "name": "valuation.dcf", "namespace": "valuation", "description": "Calculate DCF enterprise value from forecast cash flows", "usage": "finance valuation.dcf cashflows=100M,120M,140M discount_rate=10% [terminal_growth=3%|exit_multiple=15]", "examples": [ "finance valuation.dcf cashflows=100M,120M,140M discount_rate=10% terminal_growth=3%", "finance valuation.dcf cashflows=100M,120M,140M discount_rate=10% exit_multiple=15" ], "notes": [ "Pass forecast FCF only; do not include an initial t=0 investment cash flow.", "Forecast cash flows are discounted from t=1.", "Use either terminal_growth or exit_multiple, not both." ], "args": { "cashflows": { "type": "array", "items": { "type": "number" }, "required": true, "description": "Forecast cash flows. CLI accepts K/M/B suffixes." }, "discount_rate": { "type": "number", "required": true, "description": "Discount rate; CLI accepts decimal or percent." }, "terminal_growth": { "type": "number", "required": false, "description": "Perpetuity growth rate." }, "exit_multiple": { "type": "number", "required": false, "description": "Exit multiple alternative to terminal growth." } }, "input_schema": { "type": "object", "properties": { "cashflows": { "type": "array", "items": { "type": "number" }, "description": "Forecast cash flows. CLI accepts K/M/B suffixes." }, "discount_rate": { "type": "number", "description": "Discount rate; CLI accepts decimal or percent." }, "terminal_growth": { "type": "number", "description": "Perpetuity growth rate." }, "exit_multiple": { "type": "number", "description": "Exit multiple alternative to terminal growth." } }, "required": [ "cashflows", "discount_rate" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Valuation calculation result and assumptions.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use only for deterministic DCF math from explicit cash flows and discount assumptions.", "avoid_when": "Do not use as investment advice or infer assumptions silently.", "next_steps": [] } }, { "name": "valuation.irr", "namespace": "valuation", "description": "Calculate IRR for periodic cash flows", "usage": "finance valuation.irr cashflows=-100M,30M,40M,50M", "examples": [ "finance valuation.irr cashflows=-100M,30M,40M,50M" ], "notes": [ "Cash flows are periodic; returns null with a warning when no IRR solution is bracketed." ], "args": { "cashflows": { "type": "array", "items": { "type": "number" }, "description": "Cash-flow series. CLI accepts comma-separated K/M/B suffixed values.", "required": true } }, "input_schema": { "type": "object", "properties": { "cashflows": { "type": "array", "items": { "type": "number" }, "description": "Cash-flow series. CLI accepts comma-separated K/M/B suffixed values." } }, "required": [ "cashflows" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Valuation calculation result and assumptions.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use for deterministic valuation math once assumptions are explicit.", "avoid_when": "Do not present valuation output as investment advice.", "next_steps": [] } }, { "name": "valuation.multiples", "namespace": "valuation", "description": "Calculate current sales multiples from market cap and revenue", "usage": "finance valuation.multiples SYMBOL", "examples": [ "finance valuation.multiples IOT" ], "notes": [ "Deterministic math only; does not judge whether the multiple is fair." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." } }, "required": [ "symbol" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Valuation calculation result and assumptions.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use for deterministic valuation math once assumptions are explicit.", "avoid_when": "Do not present valuation output as investment advice.", "next_steps": [] } }, { "name": "valuation.npv", "namespace": "valuation", "description": "Calculate NPV for periodic cash flows", "usage": "finance valuation.npv cashflows=-100M,30M,40M,50M discount_rate=10%", "examples": [ "finance valuation.npv cashflows=-100M,30M,40M,50M discount_rate=10%" ], "notes": [ "First cash flow is treated as t=0. Use this for project-level NPV including initial investment." ], "args": { "cashflows": { "type": "array", "items": { "type": "number" }, "description": "Cash-flow series. CLI accepts comma-separated K/M/B suffixed values.", "required": true }, "discount_rate": { "type": "number", "description": "Discount rate. CLI accepts decimal or percent.", "required": true } }, "input_schema": { "type": "object", "properties": { "cashflows": { "type": "array", "items": { "type": "number" }, "description": "Cash-flow series. CLI accepts comma-separated K/M/B suffixed values." }, "discount_rate": { "type": "number", "description": "Discount rate. CLI accepts decimal or percent." } }, "required": [ "cashflows", "discount_rate" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Valuation calculation result and assumptions.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use for deterministic valuation math once assumptions are explicit.", "avoid_when": "Do not present valuation output as investment advice.", "next_steps": [] } }, { "name": "valuation.scenario", "namespace": "valuation", "description": "Build a simple bull/base/bear sales-multiple scenario table", "usage": "finance valuation.scenario SYMBOL revenue=2.2B bear_multiple=7 base_multiple=10 bull_multiple=13 [shares=580M]", "examples": [ "finance valuation.scenario IOT revenue=2.2B bear_multiple=7 base_multiple=10 bull_multiple=13 shares=580M", "finance valuation.scenario IOT revenue=2200000000 bear_multiple=7 base_multiple=10 bull_multiple=13" ], "notes": [ "Uses current quote for price/share count when available; assumptions remain user-supplied.", "Revenue and shares accept raw numbers or K/M/B suffixes." ], "args": { "symbol": { "type": "string", "description": "Ticker symbol.", "required": true }, "revenue": { "type": "number", "description": "Reported, assumed, or user-supplied revenue input.", "required": true }, "bear_multiple": { "type": "number", "description": "Bear-case valuation multiple.", "required": true }, "base_multiple": { "type": "number", "description": "Base-case valuation multiple.", "required": true }, "bull_multiple": { "type": "number", "required": true, "description": "Value supplied for `bull_multiple`." }, "shares": { "type": "number", "description": "Share count used for per-share valuation output.", "required": false, "default": "580M" } }, "input_schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "revenue": { "type": "number", "description": "Reported, assumed, or user-supplied revenue input." }, "bear_multiple": { "type": "number", "description": "Bear-case valuation multiple." }, "base_multiple": { "type": "number", "description": "Base-case valuation multiple." }, "bull_multiple": { "type": "number", "description": "Value supplied for `bull_multiple`." }, "shares": { "type": "number", "description": "Share count used for per-share valuation output.", "default": "580M" } }, "required": [ "symbol", "revenue", "bear_multiple", "base_multiple", "bull_multiple" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Valuation calculation result and assumptions.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use for deterministic valuation math once assumptions are explicit.", "avoid_when": "Do not present valuation output as investment advice.", "next_steps": [] } }, { "name": "valuation.wacc", "namespace": "valuation", "description": "Calculate weighted average cost of capital", "usage": "finance valuation.wacc equity_value=10B debt_value=1B cost_of_equity=10% cost_of_debt=5% tax_rate=21%", "examples": [ "finance valuation.wacc equity_value=10B debt_value=1B cost_of_equity=10% cost_of_debt=5% tax_rate=21%" ], "notes": [ "Formula: E/(D+E)*Re + D/(D+E)*Rd*(1-tax). Inputs are user-supplied." ], "args": { "equity_value": { "type": "number", "description": "Equity market value used in WACC or valuation math.", "required": true }, "debt_value": { "type": "number", "description": "Debt value used in WACC or valuation math.", "required": true }, "cost_of_equity": { "type": "string", "description": "Cost of equity. CLI accepts decimal or percent.", "required": true }, "cost_of_debt": { "type": "string", "description": "Cost of debt. CLI accepts decimal or percent.", "required": true }, "tax_rate": { "type": "number", "required": false, "default": 0, "description": "Tax rate; CLI accepts decimal or percent." } }, "input_schema": { "type": "object", "properties": { "equity_value": { "type": "number", "description": "Equity market value used in WACC or valuation math." }, "debt_value": { "type": "number", "description": "Debt value used in WACC or valuation math." }, "cost_of_equity": { "type": "string", "description": "Cost of equity. CLI accepts decimal or percent." }, "cost_of_debt": { "type": "string", "description": "Cost of debt. CLI accepts decimal or percent." }, "tax_rate": { "type": "number", "default": 0, "description": "Tax rate; CLI accepts decimal or percent." } }, "required": [ "equity_value", "debt_value", "cost_of_equity", "cost_of_debt" ], "additionalProperties": false }, "output_schema": { "type": "object", "required": [ "ok", "data", "error", "warnings" ], "properties": { "ok": { "type": "boolean", "description": "True when the command completed successfully." }, "data": { "anyOf": [ { "type": "object", "description": "Valuation calculation result and assumptions.", "additionalProperties": true }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Human-readable error when ok is false." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal issues." } } }, "side_effects": "pure_calculation", "side_effects_description": "No network, no filesystem read, no mutation.", "auth_required": "none", "rate_limit_notes": null, "citation_fields": [], "agent": { "use_when": "Use for deterministic valuation math once assumptions are explicit.", "avoid_when": "Do not present valuation output as investment advice.", "next_steps": [] } } ] }