DFin MCP Agent Guide
Use this guide to choose the right DFin MCP tool. Prefer MCP tools for agent workflows because they expose a simpler interface over the public DFin data capabilities.
On this page
1.0 Overview
| Documentation map | dfin://docs |
|---|---|
| MCP reference | dfin://docs/mcp |
| Agent guide resource | dfin://docs/mcp/agent-guide |
| Methodology resource | dfin://docs/methodology |
| REST API reference | dfin://docs/api/v1 |
Start with the documentation map when discovering resources. Use MCP resource URIs directly when possible. If your client requires a server filter before listing resources, use the configured server id shown by that client, or list all resources and select the DFin entries. Do not infer the resource server id from a normalized tool namespace such as mcp__dfin_pro, because clients may use different labels for tool namespaces and resource server ids. Use the MCP reference for authentication, resource discovery, and response conventions. Use the methodology resource for financial-analysis workflow and verification discipline.
2.0 Tool Guide
Use this table to choose MCP tools directly. REST API contracts are supporting detail, not the primary agent workflow.
| Area | MCP tool | Use it when | First step |
|---|---|---|---|
| Securities search | search_securities |
Look up stocks or ETFs by company, fund, security name, or partial/bare ticker, and return matching securities with full ticker.exchange identifiers. | Use before ticker-specific tools when the user provides a company name, fund name, ambiguous symbol, or bare ticker such as MSFT. Pass the resolved ticker.exchange value, such as MSFT.US, to subsequent ticker-specific tool calls. |
| Filing search | search_filings |
Search company filings with up to 12 natural-language queries; optionally narrow by ticker, fiscal period, fiscal year, filing type, and search type. | Use for source-text evidence from structured company filings. |
| Filing search | search_transcripts |
Search call transcripts with up to 12 natural-language queries; optionally narrow by ticker, fiscal period, fiscal year, transcript call-date range, and search type. Use date_from/date_to for inclusive YYYY-MM-DD call-date bounds; if a date range is too broad, narrow by ticker or fiscal period. | Use for source-text evidence from transcript documents. |
| Filing search | search_reports |
Search stock analysis reports generated by dfin.pro with up to 12 natural-language queries; optionally narrow by ticker, fiscal period, fiscal year, report published-date range, and search type. Use date_from/date_to for inclusive YYYY-MM-DD published-date bounds; if a date range is too broad, narrow by ticker or fiscal period. These reports are similar to company analyst reports; check them early so subsequent analysis can build on existing research. Use include_references=true only when references are needed for every search result; otherwise call get_report_details for one selected report. | Use for evidence from DFin stock analysis reports, similar to analyst reports on companies; check early to build on existing DFin analysis. Keep searches lean by default, set include_references=true when provenance is needed for every result, or call get_report_details for one report. |
| Filing search | get_report_details |
Return one stock analysis report's identifiers, browser URL, and source-reference metadata. Use this to inspect one report's sources for follow-up searches. Provide exactly one identifier: either doc_uuid from a search_reports result or public_id from a dfin.pro report URL. Do not provide both. | Use after a lean search_reports result when one report's public_id, view_url, doc_uuid, and references are needed. References show provenance and follow-up context for already source-grounded reports; do not re-check every source unless asked or doing source verification. |
| Document browsing | get_document_content |
Return full raw text content for one document UUID, without metadata. A document UUID corresponds to one full document such as a filing, transcript, or report. Use this after selecting a doc_uuid returned by search_filings, search_transcripts, search_reports, list_latest_transcripts, or list_latest_reports. The response may be long; use search tools for broad discovery before fetching full content. | Use only after a search or latest-document tool returns the specific doc_uuid whose full text is needed. This returns content only, not metadata. |
| Document browsing | list_latest_transcripts |
List latest call transcripts without searching transcript text. Use this when the user asks for recent/latest transcripts, last N transcripts, or transcripts from the last N days. Use search_transcripts instead when the user asks a content question requiring natural-language evidence search. | Use for recency browsing. Omit ticker for global latest transcripts, or pass ticker.exchange such as MSFT.US. Omit limit for the default 10, and use days only when the user asks for a recent day window. |
| Document browsing | list_latest_reports |
List latest stock analysis reports generated by dfin.pro. Use this when the user asks to identify recent/latest reports, last N reports, or reports from the last N days. Use search_reports instead when the user asks a content question requiring natural-language evidence search. | Use for recency browsing. Omit ticker for global latest reports, or pass ticker.exchange such as MSFT.US. Omit limit for the default 10, and use days only when the user asks for a recent day window. |
| Screener | get_screener_options |
Return the current public screener contract; use this as the source of truth for filters, option values, sort fields, output fields, and result formats. Defaults to the compact basic contract; use mode="all" for the full public screener contract. | Call before constructing any non-trivial screener request. The default basic contract is compact; use mode="all" when the needed filter is not listed. |
| Screener | run_screener |
Run a stock screen using filters from get_screener_options. | Use filter keys, option values, sort fields, and output fields from get_screener_options. |
| Financials | get_financial_single_statement |
Return one financial statement for a ticker and fiscal year. Use canonical statement names income_statement, balance_sheet, or cash_flow. Current public data supports period="FY" only. source may be standardized or as_reported; standardized supports field_map or rows, while as_reported requires rows. | Use for one exact fiscal year and statement family. |
| Financials | get_financial_stitched_statements |
Return latest-N financial statement time series. Use canonical statement names income_statement, balance_sheet, or cash_flow. Current public data supports period_type="annual" only. source may be standardized or as_reported; standardized supports field_map or rows, while as_reported requires rows. | Use for latest-N statement time series. |
| Financials | get_financial_ratios |
Return annual FY financial ratios for one ticker.exchange stock ticker and fiscal year from 2000 through 2050; optional fields accept canonical camelCase ratio keys such as returnOnEquity or grossProfitMargin. | Use for annual FY ratio metrics. |
| Stock context | get_stock_context |
Call this first when the user wants structured Markdown stock context for a specific stock in detail; requires ticker in ticker.exchange format, for example MSFT.US or BRK-B.US. If the user gave a company name or bare/ambiguous symbol, call search_securities first and pass the resolved ticker. Use financial statement and ratio tools for exact financial data. | Call first for detailed discussion of one specific stock; ticker format is ticker.exchange, for example MSFT.US. |
| Fund analytics | get_fund_movers |
Return fund movers for one fund ticker; omit delta for daily movers or set delta to a period such as mtd, 52w, or 3y. | Returns fund movers and may report a processing status. |
| Fund analytics | get_fund_highlow |
Return fund high/low analytics for one fund ticker; delta is required and margin is optional. | Returns fund high/low analytics and may report a processing status. |
3.0 Supporting Docs
For non-trivial financial analysis, read dfin://docs/methodology before answering. It explains ticker resolution, evidence gathering, verification, and source citation.
For MCP setup, authentication, public resources, and response wrapper behavior, read dfin://docs/mcp.
For detailed REST request and response contracts, read dfin://docs/api/v1. Treat REST as supporting contract detail for MCP workflows, not the first interface to call from an agent.
