FactSet AI-Ready Data

FactSet Events Tool

• Comprehensive corporate calendar event data.

CRITICAL: MAXIMUM 365-DAY SPAN between startDateTime and endDateTime (calculated to the second, not calendar days). The API enforces: (endDateTime - startDateTime) <= exactly 365 days (31,536,000 seconds). The difference between start and end dates must not exceed 365 days. Make sure startDateTime and endDateTime are always set to 00:00:00 (midnight) instead of 23:59:59 to stay within limit. For future earnings release use ProjectedEarningsRelease. Examples:

• startDateTime='2024-01-01T00:00:00Z', endDateTime='2024-12-31T00:00:00Z' PASS (exactly 365 days)
• startDateTime='2024-01-01T00:00:00Z', endDateTime='2024-12-31T23:59:59Z' FAIL (365 days + 23:59:59
• FAILS)
• startDateTime='2024-01-01T00:00:00Z', endDateTime='2025-12-31T23:59:59Z' FAIL (730 days
• FAILS)

WHEN TO USE THIS TOOL:

• Questions like "When was Microsoft's last earnings call?" or "When is Apple's next earnings?"
• Corporate event calendars, investor meetings, conference schedules
• Questions about "When is [company]'s earnings call?" or "Upcoming investor events"
• Event calendar tracking, earnings schedules, investor meeting coordination
• Corporate action dates (splits, dividends)
• Conference and presentation schedules

CRITICAL: For queries like "When was [company]'s last earnings call?", use this tool BEFORE web search.

ALWAYS USE THIS TOOL WHEN USER ASKS:

• "When is [company]'s earnings call?"
• "Upcoming events for [company]"
• "[Company] event calendar"
• "Earnings schedule for [companies]"
• "Investor meetings this week/month"
• "Recent event changes"
• Any variation of corporate event queries

DATA COVERAGE & SCOPE:

• Global corporate event calendar from November 1st, 2022 onwards
• Earnings calls, investor meetings, conferences, corporate actions
• Contact information and webcast links for events
• Historical and future events (up to 365 days ahead)
• Real-time schedule updates and modifications

SINGLE ENDPOINT: This tool routes to the FactSet Events API calendar events endpoint:

CALENDAR EVENTS ENDPOINT (/events):

• Use Case: Retrieve corporate event schedules and details
• Returns: Event timing, company info, contacts, webcast links, unique identifiers
• Best For: Event calendar tracking, earnings planning, investor coordination
• Example: "Show me Apple's upcoming earnings calls" or "Events this week for MSFT"

CRITICAL CONSTRAINTS:

DATE RANGE LIMITATION:

• MAXIMUM 365-DAY SPAN between startDateTime and endDateTime
• For longer periods: Make multiple requests for different 365-day windows
• Example: Multi-year analysis may require multiple API calls

MUTUALLY EXCLUSIVE PARAMETERS:

• CANNOT use both dateTime range AND lastModifiedWithin
• Choose ONE approach based on use case:
• Use dateTime for specific historical periods or future planning
• Use lastModifiedWithin for recent schedule changes and updates

AVAILABLE EVENT TYPES:

EARNINGS & FINANCIAL:

• Earnings: Quarterly earnings calls and results
• ConfirmedEarningsRelease: Officially confirmed earnings dates
• ProjectedEarningsRelease: Estimated earnings dates
• SalesRevenueCall: Sales-focused conference calls
• SalesRevenueRelease: Sales/revenue press releases
• GuidanceCall: Forward guidance communications

MEETINGS & PRESENTATIONS:

• AnalystsInvestorsMeeting: Analyst and investor gatherings
• ShareholdersMeeting: Shareholder meetings and voting events
• Conference: Industry conferences and presentations

CORPORATE ACTIONS:

• SpecialSituation: M&A, restructuring, special corporate events
• Split: Stock split announcements and effective dates
• Dividend: Dividend declarations and payment dates

UNIVERSE TYPES:

TICKERS (RECOMMENDED):

• Individual company symbols
• Most efficient for targeted queries
• Best performance and accuracy
• Example: symbols=['AAPL-US', 'MSFT-US']

INDEX:

• Market index constituents
• All companies in specified index
• Example: symbols=['SP50'] for S&P 50

ETF:

• Exchange-traded fund holdings
• All companies held in ETF
• Example: symbols=['SPY-US']

ALLCOMPANIES:

• All available companies in database
• Use with caution (very large result sets)
• Combine with narrow date ranges and specific event types

MANDATORY WORKFLOW:

**OPTION A

• DATE RANGE QUERY:**

1. Identify companies using proper symbols 2. Define dateTime range (max 365 days) 3. Confirm dateTime range is 365 days or less. 4. If dateTime range is greater than 365 days, go back to step 2. 3. Select relevant event types 4. Set universe type (typically Tickers)

**OPTION B

• RECENT MODIFICATIONS:**

1. Identify companies using proper symbols 2. Select lastModifiedWithin period 3. Select relevant event types 4. Set universe type (typically Tickers)

DATE HANDLING (CRITICAL):

DATETIME RANGE:

• startDateTime: REQUIRED with endDateTime (ISO 8601 format)
• endDateTime: REQUIRED with startDateTime (ISO 8601 format)
• Format: YYYY-MM-DDTHH:MM:SSZ (UTC timezone)
• Maximum range: 365 days
• Minimum date: 2022-11-01T00:00:00Z
• Future events: Up to 365 days ahead
• Example: start='2024-01-01T00:00:00Z', end='2024-12-31T00:00:00Z'

LAST MODIFIED WITHIN:

• SixHours: Events modified in last 6 hours
• TwelveHours: Events modified in last 12 hours
• Today: Events modified today
• TwoDays: Events modified in last 2 days
• OneWeek: Events modified in last week
• OneMonth: Events modified in last month
• Returns: Modified events + events scheduled within 45 days
• Example: lastModifiedWithin='OneWeek'

COMMON USE CASES:

"When is Apple's next earnings call?" → symbols=['AAPL-US'], universeType='Tickers', eventTypes=['Earnings'], startDateTime='2025-10-15T00:00:00Z', endDateTime='2026-10-14T23:59:59Z'

"Show me all events this week for Microsoft" → symbols=['MSFT-US'], universeType='Tickers', eventTypes=[all types], startDateTime='2025-10-13T00:00:00Z', endDateTime='2025-10-19T23:59:59Z'

"Recent event schedule changes" → symbols=['AAPL-US', 'MSFT-US'], universeType='Tickers', eventTypes=[all types], lastModifiedWithin='OneWeek'

"Full year 2024 earnings calendar for tech companies" → symbols=['AAPL-US', 'MSFT-US', 'GOOGL-US'], universeType='Tickers', eventTypes=['Earnings', 'ConfirmedEarningsRelease'], startDateTime='2024-01-01T00:00:00Z', endDateTime='2024-12-31T00:00:00Z'

"Today's corporate events" → symbols=[company list], universeType='Tickers', eventTypes=[all types], lastModifiedWithin='Today'

DATA TRANSPARENCY:

• All data from official company announcements and schedules
• Event times in UTC timezone
• Data available from November 1st, 2022 onwards
• Future events up to 365 days ahead
• Always specify date ranges and event types used
• State limitations when data not available

COMPREHENSIVE EVENT INFORMATION:

• Event Details: Type, description, timing, fiscal period
• Company Info: Identifier, entity name
• Contact Details: Email, phone, contact name (when available)
• Access Info: Webcast links, IR page URLs
• Cross-Reference: Event ID, Report ID for transcript linking
• Metadata: Market timing, last modified date, fiscal year/period

EFFICIENCY REQUIREMENTS:

• API rate-limited to 10 requests per second
• Maximum 10 concurrent requests per user
• Optimize date ranges (use 365-day max efficiently)
• Filter by relevant event types only
• Use targeted symbol lists when possible

BEST PRACTICES:

FOR RECENT UPDATES:

• Use lastModifiedWithin instead of wide date ranges
• More efficient for tracking schedule changes
• Automatically includes events scheduled within 45 days

FOR SPECIFIC PERIODS:

• Use dateTime range with precise start/end
• Ideal for historical analysis or specific year planning
• Remember 365-day maximum constraint

FOR PERFORMANCE:

• Filter to specific event types needed
• Use Tickers universe type for individual companies
• Avoid AllCompanies unless truly needed

USE FOR: Corporate event tracking, earnings schedule planning, investor meeting coordination, corporate action monitoring DO NOT USE FOR: Real-time event updates during calls, transcript content, audio recordings

CROSS-REFERENCE CAPABILITIES:

• reportId: Links to transcripts and documents in other FactSet services
• eventId: Unique identifier for event tracking and updates
• fiscalYear/Period: Aligns with financial reporting calendars

LIMITATIONS:

• 365-day maximum date range per request
• Historical data from November 2022 onwards only
• Future events limited to 365 days ahead
• Contact information may not be available for all events
• Webcast links provided when available from companies

RETURNS:

• Structured JSON responses with event data
• Always includes: identifier, entityName, eventType, eventDateTime, eventId
• Optional fields: webcastLink, contactEmail/Phone/Name, reportId, lastModifiedDate
• Error messages with detailed validation feedback

ERROR HANDLING:

• Invalid parameter combinations → Detailed error message
• Date range exceeds 365 days → Constraint violation message
• Both dateTime and lastModifiedWithin specified → Mutual exclusivity error
• Missing required parameters → Error with reminder
• Invalid identifiers → List of unrecognized symbols

FactSet Entity Tool

• Comprehensive entity reference and relationship data.

WHEN TO USE THIS TOOL: This tool should be your FIRST choice for:

• Entity identification and reference information (supports both public and private identifiers)
• Ultimate parent and credit parent relationships
• Corporate structure and subsidiary analysis
• Related securities (equity and debt instruments)

AUTOMATIC ENDPOINT ROUTING: This tool intelligently routes to FactSet Entity API endpoint:

1. ENTITY REFERENCE (/entity-references):

• Use Case: Entity profiles with parent relationships and business details
• Returns: Ultimate Parent ID, Credit Parent ID, HQ location, website, business description
• Best For: Entity identification, parent company research
• Example: "What is Apple's ultimate parent?" or "Get business description for Microsoft"

COMMON USE CASES:

"What is Apple's ultimate parent company?" → data_type='entity_reference', ids=['AAPL-US']

RATE LIMITS:

• 10 requests per second across all endpoints

RETURNS: Structured JSON responses with entity data specific to the selected data_type.

FactSet Estimates Tool

• Comprehensive analyst estimates, segments, and guidance data.

CRITICAL PIT (POINT-IN-TIME) RULE — ALWAYS ENFORCED: For historical estimates, startDate AND endDate are ALWAYS required for consensus_fixed, consensus_rolling, segments, guidance, and ratings.

Without startDate/endDate, the API returns only the MOST RECENT estimate snapshot. This is NOT the estimate as it existed on a specific historical date — it is simply the latest available value. To retrieve accurate Point-in-Time (PIT) estimates that reflect what analysts were forecasting on a given date, both dates are mandatory.

CORRECT (PIT): startDate='2024-01-01', endDate='2024-12-31' WRONG (no PIT): omitting startDate/endDate → returns latest estimate only

Surprise (estimate_type='surprise') is exempt — it always requires dates by its own rule.

WHEN TO USE THIS TOOL:

• ANY query about analyst estimates, forecasts, or consensus data
• Forward-looking financial metrics (revenue estimates, EPS forecasts, etc.)
• Questions containing "estimate", "forecast", "consensus", "next year", "2026", etc.
• Analyst ratings and recommendations
• Surprise analysis (actual vs estimate)
• Segment-level financial data (product lines, geographic regions)
• Company guidance and projections

DATA COVERAGE & SCOPE:

• 16,000+ active companies across 90+ countries worldwide
• Historical data from 1999 (Europe from 1997)
• Comprehensive analyst forecasts and future financial performance expectations
• Actual reported results from company filings
• Segment-level breakdowns for diversified companies

CONSENSUS WINDOW METHODOLOGY:

• Default consensus window: 100 days (the lookback period used to aggregate analyst estimates)
• This means estimates published within the last 100 days are included in the consensus calculation
• Applies to: consensus_fixed, consensus_rolling, segments, consensus_ratings, and surprise endpoints
• Implication: An analyst whose last estimate is older than 100 days will NOT be included in the consensus
• This is the standard FactSet methodology; the window is not configurable via this tool

AUTOMATIC ENDPOINT ROUTING: This tool intelligently routes to 8 different FactSet Estimates API endpoints:

1. FIXED CONSENSUS (/fixed-consensus):

• Trigger: When fiscalPeriodStart OR fiscalPeriodEnd provided
• Use Case: Specific fiscal period analysis (e.g., "2025" for annual, "2024/4F" for Q4 2024)
• Best For: Tracking estimates for specific calendar periods
• Example: "What are 2025 revenue estimates?" or "What are Q4 2024 EPS estimates?"

2. ROLLING CONSENSUS (/rolling-consensus):

• Trigger: When relativeFiscalStart OR relativeFiscalEnd provided, or NO fiscal params
• Use Case: Relative period analysis (e.g., "next year", "FY1")
• Best For: Forward-looking trends with consistent time horizons
• Example: "What are next year's EPS estimates?"

3. SURPRISE ANALYSIS (/surprise):

• Trigger: When estimate_type='surprise'
• Use Case: Actual reported results vs pre-announcement analyst consensus
• Returns: Surprise amount, surprise percent, before/after values
• Best For: Earnings beat/miss analysis, estimate accuracy evaluation
• Example: "How often did Tesla beat earnings estimates?"

4. ANALYST RATINGS (/consensus-ratings):

• Trigger: When estimate_type='ratings'
• Use Case: Analyst recommendation consensus (Buy/Hold/Sell)
• Returns: Rating distribution, consensus score, rating changes
• Best For: Analyst sentiment analysis, upgrade/downgrade tracking
• Example: "What are current analyst ratings for Apple?"

5. SEGMENTS (/segments):

• Trigger: When estimate_type='segments'
• Use Case: Product or geographic segment estimates
• Returns: Segment-level consensus estimates by business line or region
• Best For: Divisional analysis, product line forecasts, regional performance
• Example: "What are the revenue estimates for Apple's iPhone segment?"

6. GUIDANCE (/guidance):

• Trigger: When estimate_type='guidance'
• Use Case: Company-provided guidance for unreported periods
• Returns: Guidance ranges (high/low/midpoint), previous guidance, surprise metrics
• Best For: Understanding company expectations, tracking guidance changes
• Example: "What is Tesla's guidance for next quarter?"

CRITICAL DATA DISTINCTIONS:

• Estimates Metrics: NOT prefixed with FF_ (use 'SALES', 'EPS', 'PRICE_TGT')
• Fundamentals Metrics: ARE prefixed with FF_ (use 'FF_SALES', 'FF_EPS')
• Always call metrics endpoint first if unsure about metric codes

METRIC LIMITATIONS:

• Currently limited to 1 metric per request for consensus/surprise/segments
• Maximum 3,000 company identifiers (ids) per request
• No metrics parameter needed/used for ratings or guidance requests

KEY PARAMETERS:

*1. estimate_type (REQUIRED):*

• 'consensus_fixed': Analyst forecast estimates for specific periods
• 'consensus_rolling': Analyst forecast estimates for relative periods
• 'surprise': Actual vs estimate comparison (beat/miss analysis)
• 'ratings': Analyst recommendations (Buy/Hold/Sell sentiment)
• 'segments': Product/geographic segment estimates
• 'guidance': Company-provided guidance

*2. ids (REQUIRED):*

• Security identifiers: FactSet IDs (AAPL-US), tickers, CUSIP, SEDOL, ISIN
• Accepts arrays: ["AAPL-US", "MSFT-US", "GOOGL-US"]
• Maximum: 3,000 identifiers per request

*3. metrics (REQUIRED for consensus/surprise/segments/guidance, NOT for ratings):*

• Estimate metrics WITHOUT FF_ prefix
• Common: SALES (Revenue), EPS (Earnings Per Share), EBITDA, PRICE_TGT (Target Price)
• Limited to 1 metric per request currently
• Use metric query tool to discover available codes

*4. Fiscal Period Selection (CONSENSUS/SEGMENTS/GUIDANCE):*

OPTION A: Fixed Fiscal Periods (specific calendar periods

• CONSENSUS ONLY)
• fiscalPeriodStart: 'YYYY' (e.g., '2025') OR 'YYYY/FQ' (e.g., '2024/4F')
• fiscalPeriodEnd: Same format, should be >= start
• Use when: Analyzing specific fiscal years or quarters
• Example: "2025 estimates" -> fiscalPeriodStart='2025'
• Example: "Q4 2024 estimates" -> fiscalPeriodStart='2024/4F', fiscalPeriodEnd='2024/4F'

OPTION B: Rolling Fiscal Periods (relative time horizons)

• relativeFiscalStart: Integer (for consensus/segments/guidance: 1=next period, 2=period after)
• relativeFiscalEnd: Integer, must be >= relativeFiscalStart
• CRITICAL CONSTRAINT: relativeFiscalEnd must be >= relativeFiscalStart (API will reject if violated)
• Use when: Forward-looking analysis
• Example: "Next year" -> relativeFiscalStart=1, relativeFiscalEnd=1

CRITICAL: Cannot mix fixed and rolling parameters!

*5. startDate/endDate:*

• CRITICAL PIT RULE: For historical estimates, startDate AND endDate are ALWAYS required for

consensus_fixed, consensus_rolling, segments, guidance, and ratings. Omitting them returns the most recent estimate only — NOT Point-in-Time (PIT) data.

• MEANING: WHEN to retrieve estimates (time-series analysis)
• NOT: WHAT periods to forecast (use fiscal params for that)
• Format: 'YYYY-MM-DD' (e.g., '2024-01-01')
• MUST use both together or omit both
• OMIT both -> Returns current/latest data
• PROVIDE both -> Returns historical snapshots
• No future dates allowed
• SURPRISE: When retrieving most recent surprise data, both startDate and endDate MUST be today's date

*6. frequency (OPTIONAL

• Sampling Rate):*
• D: Daily (each trading day)
• W: Weekly (last trading day of week)
• AM: Actual Monthly (NOTE: Use 'AM', not 'M' - differs from Prices API)
• AQ: Actual Quarterly
• AY: Actual Yearly
• Only used with startDate/endDate for time-series sampling
• IMPORTANT: This parameter uses 'AM' for monthly frequency, not 'M' as in some other FactSet APIs

*7. periodicity (OPTIONAL

• Time Interval):*
• ANN: Annual fiscal year (default)
• QTR: Quarterly fiscal period (use with YYYY/FQ format)
• SEMI: Semi-annual (6-month)
• NTMA: Next-twelve-months (forward 12M rolling)
• LTMA: Last-twelve-months (trailing 12M)
• For surprise: Only ANN, QTR, SEMI supported

*8. currency (OPTIONAL):*

• ISO currency codes: USD, EUR, GBP, JPY, CNY, etc.
• Special: 'ESTIMATE' = original broker reporting currency
• Default: Company's reporting currency

*9. statistic (SURPRISE ONLY):*

• MEAN: Average of all estimates (default, most common)
• MEDIAN: Middle value (reduces outlier impact)
• HIGH: Highest estimate
• LOW: Lowest estimate

*10. segmentType (SEGMENTS ONLY):*

• BUS: Business/Product segments
• GEO: Geographic segments

EXAMPLES:

1. Current consensus for next year: estimate_type="consensus_rolling", ids=["AAPL-US"], metrics=["SALES"], relativeFiscalStart=1, relativeFiscalEnd=1

1.5. Q4 2024 consensus estimates: estimate_type="consensus_fixed", ids=["AAPL-US"], metrics=["EPS"], fiscalPeriodStart='2024/4F', fiscalPeriodEnd='2024/4F', periodicity='QTR'

2. iPhone segment estimates: estimate_type="segments", ids=["AAPL-US"], metrics=["SALES"], segmentType="BUS", relativeFiscalStart=1, relativeFiscalEnd=1

3. Company guidance: estimate_type="guidance", ids=["TSLA-US"], metrics=["SALES"], relativeFiscalStart=1, relativeFiscalEnd=1

4. Earnings surprise analysis: estimate_type="surprise", ids=["GOOGL-US"], metrics=["EPS"], startDate="2023-01-01", endDate="2023-12-31", periodicity="QTR"

5. Monthly price target history for 2024: estimate_type="consensus_rolling", ids=["AAPL-US"], metrics=["PRICE_TGT"], relativeFiscalStart=0, relativeFiscalEnd=0, startDate="2024-01-01", endDate="2024-12-31", frequency="AM"

6. Weekly EPS estimate revisions tracking: estimate_type="consensus_rolling", ids=["MSFT-US"], metrics=["EPS"], relativeFiscalStart=1, relativeFiscalEnd=1, startDate="2024-01-01", endDate="2024-06-30", frequency="W"

7. Monthly analyst ratings evolution: estimate_type="ratings", ids=["META-US"], startDate="2024-01-01", endDate="2024-12-31", frequency="AM"

**SPECIAL CASE

• PRICE_TGT (Target Price):**
• Target prices are NOT tied to fiscal periods like EPS/SALES estimates
• Use consensus_rolling with relativeFiscalStart=0, relativeFiscalEnd=0
• For a specific date snapshot: set BOTH startDate and endDate to the same date
• Example: Target price on Oct 31, 2024:

estimate_type="consensus_rolling", ids=["AAPL-US"], metrics=["PRICE_TGT"], relativeFiscalStart=0, relativeFiscalEnd=0, startDate="2024-10-31", endDate="2024-10-31"

• Do NOT use frequency parameter with single-date snapshots

RETURNS: Consensus: mean, median, high, low, standardDeviation, estimateCount, up/down revisions Surprise: surpriseAmount, surprisePercent, surpriseBefore, surpriseAfter Ratings: buyCount, holdCount, sellCount, ratingsNote, ratingsNoteText Segments: Segment-level consensus with segmentLabel, segmentLevel Guidance: guidanceMidpoint, guidanceLow, guidanceHigh, meanBefore, meanSurpriseAmt

ERROR HANDLING:

• Invalid parameter combinations → Detailed error message
• Missing required metrics → Error with reminder
• Date format errors → Format specification
• Mixed fiscal parameters → Cannot mix fixed and rolling

FactSet Fundamentals Tool

• Comprehensive financial statements data.

MANDATORY WORKFLOW: 1. ALWAYS call FactSet_Metrics FIRST before calling FactSet_Fundamentals - no exceptions, even for common metrics 2. Copy the EXACT metric code string(s) returned by FactSet_Metrics into the metrics parameter - do not paraphrase, abbreviate, or infer codes 3. Only after receiving a valid FactSet_Metrics response may you call FactSet_Fundamentals 4. Never call FactSet_Fundamentals with metric codes that were not explicitly returned in the current conversation's FactSet_Metrics response

DO NOT USE THIS TOOL FOR:

• Earnings comparisons to estimates ("beat", "miss", "surprise", "vs estimates")
• Analyst forecast comparisons - use FactSet Estimates API instead

PERIODICITY — SET THIS BEFORE EVERY CALL, NO EXCEPTIONS:

• User specifies a periodicity or fiscal dates → use exactly that value, no fallback needed.
• User does NOT specify a periodicity or fiscal dates (i.e., "latest" / current data) → you MUST execute this fallback sequence in order:

1. Call with periodicity='QTR' — always start here, no exceptions 2. If QTR returns empty → retry with periodicity='SEMI' 3. If SEMI returns empty → retry with periodicity='ANN' Return the first non-empty response. Do NOT skip straight to ANN. DO NOT use periodicity=null. The schema accepts null but null silently defaults to ANN and will miss quarterly/semi-annual reporters — always supply an explicit value.

**DATES

• CRITICAL:**
• For queries with "last X" or temporal keywords: MUST include BOTH fiscalPeriodStart and fiscalPeriodEnd
• Calculate: start = today
• X period, end = today (e.g., "last 4 quarters" = 2025-02-26 to 2026-02-26)
• For specific year: BOTH dates required (e.g., 2024 = 2024-01-01 to 2024-12-31)
• Latest/current data ONLY: Omit both date parameters
• Format: YYYY-MM-DD ONLY; never use '2024' or '2024/1F'

PERIODICITY:

• Options: ANN, ANN_R, QTR, QTR_R, SEMI, SEMI_R, LTM, LTM_R, LTMSG, LTM_SEMI, LTM_SEMI_R, YTD

METRICS: Use FF_* codes (validate via FactSet_Metrics first); max 1,600 per request

EXAMPLES:

• Revenue (last 4 quarters): ids=['AAPL-US'], metrics=['FF_SALES'], periodicity='QTR', fiscalPeriodStart='2025-02-26', fiscalPeriodEnd='2026-02-26'
• Balance sheet: ids=['IBM-US'], metrics=['FF_ASSETS', 'FF_LIAB', 'FF_SH_EQ'], periodicity='ANN'
• Pre-calculated ratios: Check FactSet_Metrics for FF_DEBT_EQ, FF_ROE, FF_CURR_RATIO, etc. first

PRE-CALCULATED RATIOS (CHECK FIRST): FF_DEBT_EQ, FF_CURR_RATIO, FF_QUICK_RATIO, FF_ROE, FF_ROE_DILUTED, FF_ROA, FF_EBIT_OPER_ROA, FF_ASSET_TURN, FF_PE, FF_ENTRPR_VAL_EBITDA_OPER, FF_EBIT_OPER_MGN, FF_EBITDA_OPER_MGN, FF_CCE_END

AUDIT CARD: Each data item includes audit.card.link with verification URL. Display as: [value](link)

• Make each number a clickable audit link.

RETURNS: JSON with requestId, fsymId, metric, fiscalPeriod, fiscalYear, value, audit.card.link

ERROR HANDLING: Invalid params/dates/metrics → Detailed error message with guidance

FactSet Funds and ETF Tool

• Comprehensive mutual funds and ETF data analysis.

WHEN TO USE THIS TOOL:

• Queries about fund performance, returns, pricing (NAV)
• Fund composition, holdings, and portfolio analysis
• Fund costs, fees, expense ratios, and tax information
• Fund flows, assets under management (AUM), yields
• Fund risk metrics, scoring, and segment information
• Fund distributions, dividends, and trading characteristics
• ETF scoring, analytics, and related fund information
• Geographic revenue, sector weighting, asset allocation for any fund or ETF

Do NOT default to web search for these queries - use FactSet FIRST.

CRITICAL RULES — READ BEFORE EVERY CALL:

1. PREFER THIS TOOL OVER FactSet_GlobalPrices FOR FUND/ETF RETURNS AND PRICES. When the query is specifically about a mutual fund or ETF (e.g., SPY, QQQ, VOO, VTI, IWM, VEA, EWJ, HYG, LQD, XLE, XLF, XLK, XLV, ARKK, TLT, IEF, SHY, EFA, EEM, JEPI, SCHD, QUAL, MTUM, VLUE, FDGRX, etc.), use FactSet_FundsETF — it provides fund-specific NAV data, fund-level returns, and fund metadata not available in FactSet_GlobalPrices.

2. GEOGRAPHIC REVENUE FOR FUNDS/ETFs: USE THIS TOOL WHEN DOING BROADER FUND ANALYSIS. Use data_type='portfolio_analytics' with analyticsType='GEOGRAPHIC_REVENUE'. FactSet_GeoRev also supports funds and ETFs and can be used for dedicated geographic revenue queries, but prefer this tool when the query is already fund-analytics focused.

DATA COVERAGE & SCOPE:

• US-listed and international mutual funds and ETFs (SPY, VOO, QQQ, VTI, etc.)
• Comprehensive fund reference data and classification
• Time series quantitative data (NAV, flows, AUM, returns)
• Portfolio holdings and composition analysis
• Fund costs, fees, tax exposure, and risk measures
• Trading, liquidity, and performance characteristics

AUTOMATIC ENDPOINT ROUTING: This tool intelligently routes to 18 different FactSet Funds and ETF API endpoints:

1. SUMMARY ENDPOINT (/summary):

• Basic reference data for funds
• Country domicile, share class info, fund families
• Use: Fund basic information lookup
• Example: "Tell me about Vanguard S&P 500 ETF (VOO)"

2. PRICES ENDPOINT (/prices):

• Fund NAV (Net Asset Value) for date ranges
• Historical pricing data
• Use: Price history, NAV trends for any fund or ETF
• Example: "What was the NAV of VOO last month?"

3. RETURNS ENDPOINT (/returns):

• NAV returns over time-series
• Use: Performance analysis for any fund or ETF
• Example: "What were the daily returns for SPY over the last 3 months?"

4. RETURNS/RANGE ENDPOINT (/returns/range):

• Fund returns between specific dates
• Use: Period-specific performance for any fund or ETF
• Example: "What was the total return for VTI in 2023?"

5. RETURNS/SNAPSHOT ENDPOINT (/returns/snapshot):

• Pre-defined time horizons (YTD, 1Y, 3Y, 5Y, etc.)
• Use: Quick snapshot of standard periods
• Example: "What's the YTD return for ETF XYZ?"

6. AUM ENDPOINT (/aum):

• Assets Under Management at fund or share class level
• Use: Fund size analysis
• Example: "How much AUM does VOO have?"

7. FLOWS ENDPOINT (/flows):

• Fund flows (net inflows/outflows)
• One-day, monthly, or custom period flows
• Use: Fund flow trends and investor activity
• Example: "What were the fund flows for QQQ last month?"

8. DISTRIBUTIONS ENDPOINT (/distributions):

• Current or historical fund distributions
• Dividend data by period
• Use: Distribution history analysis
• Example: "Show me distributions paid by DVY in 2023"

9. YIELDS ENDPOINT (/yields):

• SEC yield (gross and net)
• Subsidized vs. unsubsidized yields
• Use: Income analysis
• Example: "What's the current SEC yield for HYG?"

10. COSTS-FEES ENDPOINT (/costs-fees):

• Expense ratios, investment minimums, management fees, load fees
• Use: Cost analysis and comparison for any fund or ETF
• Example: "What are the expense ratios and fees for AGTHX and ARKG?"

11. TAXES-AND-RISKS ENDPOINT (/taxes-and-risks):

• Tax exposure, regulatory compliance, risk measures
• Use: Tax and risk profile analysis
• Example: "What's the tax exposure for fund ABC?"

12. RISK-ANALYTICS ENDPOINT (/risk-analytics):

• Credit risk (CREDIT_RISK) or rate risk (RATE_RISK) analytics
• Use: Risk assessment by type for bond/fixed income ETFs and funds
• Example: "Compare credit risk analytics for HYG and LQD"

13. SEGMENTS-AND-STRUCTURE ENDPOINT (/segments-and-structure):

• Fund structure, classification, related funds, segments
• Use: Fund relationship and classification info
• Example: "What structural relationships exist between QQQ and TQQQ?"

14. PORTFOLIO/STATISTICS ENDPOINT (/portfolio/statistics):

• Portfolio statistics for funds
• Use: Detailed portfolio metrics
• Example: "Get portfolio statistics for fund XYZ"

15. PORTFOLIO/ANALYTICS ENDPOINT (/portfolio/analytics):

• Asset allocation, sector weightage, geographic revenue, market cap breakdown
• Use: Portfolio composition analysis for any fund or ETF
• NOTE: FactSet_GeoRev also supports funds/ETFs; prefer this tool when doing broader fund analytics
• Example: "What's the sector breakdown for fund ABC?"

16. FINANCIALS/KEY-ITEMS ENDPOINT (/financials/key-items):

• Financial key items for funds
• Use: Industry-specific operating measures
• Example: "Get financial key items for fund ABC"

17. TRADING ENDPOINT (/trading):

• Trading and liquidity characteristics
• Use: Trading analysis
• Example: "Compare trading characteristics for SPXL and SPY"

18. SCORING ENDPOINT (/scoring):

• ETF scores, segment averages, analyst recommendations, grade
• Use: ETF quality and performance scoring
• Example: "What's the analyst grade for QQQ?"

IDENTIFIER REQUIREMENTS:

• ACCEPTS: Fund identifiers (ticker symbols, ISIN, CUSIP, FactSet IDs)
• Examples: ['VFIAX', 'SPY', 'BRK.A']

MANDATORY WORKFLOWS BY DATA TYPE:

PRICES: 1. Identify fund(s) 2. Define date range (startDate REQUIRED, endDate optional) 3. Get NAV pricing data

RETURNS: 1. Identify fund(s) 2. Define calculation period (startDate and endDate REQUIRED) 3. Select frequency 4. Get time-series returns

RETURNS/RANGE: 1. Identify fund(s) 2. Specify startDate and endDate 3. Get returns for that period

RETURNS/SNAPSHOT: 1. Identify fund(s) 2. Specify date for snapshot 3. Get pre-defined time horizon returns (YTD, 1Y, 3Y, 5Y, 10Y)

AUM: 1. Identify fund(s) 2. Optionally specify date 3. Get assets under management

FLOWS: 1. Identify fund(s) 2. Optionally specify date range 3. Get flow data

PORTFOLIO/ANALYTICS: 1. Identify fund(s) 2. Get asset allocation, sector, geographic, market cap data

RISK-ANALYTICS: 1. Identify fund(s) 2. Specify riskType: CREDIT_RISK or RATE_RISK (or omit for ALL)

COSTS-FEES: 1. Identify fund(s) 2. Returns expense ratios, management fees, load fees, minimums

DATE HANDLING:

• CRITICAL: Always use current date context. Today is 2026-03-02. Calculate date ranges from TODAY.
• Format: YYYY-MM-DD (e.g., '2026-03-02')
• For YTD: Use Jan 1 of current year through today
• For 1Y: Use same date last year through today
• For 3M: Use date 3 months ago through today

COMMON USE CASES WITH CORRECT TOOL CALLS:

"What were the daily returns for SPY over the last 3 months?" → FactSet_FundsETF: data_type='returns', ids=['SPY'], startDate='2026-01-15', endDate='2026-04-15', frequency='D'

"Compare weekly returns of IWM and VEA over the past year" → FactSet_FundsETF: data_type='returns', ids=['IWM', 'VEA'], startDate='2025-04-15', endDate='2026-04-15', frequency='W'

"What was the total return for VTI in 2023?" → FactSet_FundsETF: data_type='returns_range', ids=['VTI'], startDate='2023-01-01', endDate='2023-12-31'

"What's the NAV for VOO last month?" → FactSet_FundsETF: data_type='prices', ids=['VOO'], startDate='2026-03-01', endDate='2026-04-01'

"Compare sector weightings for XLF and XLK" → FactSet_FundsETF: data_type='portfolio_analytics', ids=['XLF', 'XLK'], analyticsType='SECTOR_WEIGHTAGE'

"What is the geographic revenue breakdown for VEA?" → FactSet_FundsETF: data_type='portfolio_analytics', ids=['VEA'], analyticsType='GEOGRAPHIC_REVENUE'

"Compare credit risk between HYG and LQD" → FactSet_FundsETF: data_type='risk_analytics', ids=['HYG', 'LQD'], riskType='CREDIT_RISK'

"What are the expense ratios for ARKG and IDNA?" → FactSet_FundsETF: data_type='costs_fees', ids=['ARKG', 'IDNA']

"AUM of XIU (Canadian ETF)?" → FactSet_FundsETF: data_type='aum', ids=['XIU-CA'] ← note -CA for Canada domicile

ALWAYS USE THIS TOOL WHEN USER ASKS:

• "What's the NAV/price of [fund or ETF]?"
• "How did [fund or ETF] perform?"
• "What are the fees/expense ratio for [fund]?"
• "Get portfolio/sector/geographic analysis for [fund]"
• "What's the risk profile/credit risk of [fund]?"
• "Show distributions for [fund]"
• "How much AUM does [fund] have?"
• "What are the fund flows for [fund]?"
• "What's the score/grade for [ETF]?"
• Any fund or ETF related query

PERCENTAGE FIELD INTERPRETATION All percent values in API responses are returned as decimal fractions, where 0.05 = 5%. You MUST multiply by 100 before displaying or comparing any percentage value to a user.

Affected fields by endpoint:

• costs_fees: medianTrackingDifferencePercent, maxUpsideDeviationPercent, maxDownSideDeviationPercent
• trading: averageSpreadPercent, marketHoursOverlapPercent

RETURNS:

• Structured JSON responses with requested data
• Always includes: fund identifier, date, requested metrics
• Error messages with detailed validation feedback
• Data transparency: All values from official FactSet feeds

ERROR HANDLING:

• Invalid parameter combinations → Detailed error message
• Missing required parameters → Error with reminder
• Date format errors → Format specification
• Invalid identifiers → List of unrecognized IDs

Perform advanced financial screening on funds and ETF data across multiple content sets. Recommended workflow: Fields → Distinct Count (if needed) → Search.

Operations: 1. Fields

• Get available fields. Start here to discover all available fields for screening.

2. Distinct Count

• Get enumeration values for a field to understand valid filter values. Use after Fields to explore enum field values before building filters. Examples of fields supporting distinct-count: active_status, actively_managed, actively_managed_flag, asset_class, category, countries_for_sale.country, currency, currency_hedged, currency_hedged_flag, development_level, esg_flag, etf_asset_class, etf_econ_development_desc, etf_type, focus, fund_iso_country, fund_region, issuer, issuer_name, niche, primary_exchange, segment, ucits_compliance, ucits_compliant_flag (call Fields endpoint to see complete list).

3. Search

• Search records matching filter criteria across content sets with sorting and pagination. Call Fields endpoint first, then optionally Distinct Count for enum fields, before building your search query.

FactSet GeoRev Tool

• Comprehensive geographic revenue exposure analysis.

WHEN TO USE THIS TOOL:

• ANY query about geographic revenue, revenue by region/country, or geographic exposure
• Questions about "where does [company] make its revenue?" or "geographic breakdown"
• Revenue exposure analysis by region or country
• Geographic risk assessment (geopolitical, macroeconomic impacts)
• Portfolio-level geographic exposure aggregation
• Comparing revenue footprints vs. country of domicile
• Questions about revenue in specific countries or regions

Do NOT use for segment data - use FactSet Fundamentals Segments endpoint instead.

DATA COVERAGE & SCOPE:

• 49,000+ publicly listed companies, ETFs, and mutual funds globally
• All Russell 3000 and MSCI ACWI Index constituents
• Historical data: U.S. from 2003, Non-U.S. from 2007
• ~300 countries supported worldwide
• Four-level geographic taxonomy: Super-Region → Region → Area → Country
• Fiscal annual periodicity, updated daily
• Normalized and estimated revenue exposures with confidence metrics

WHAT MAKES GEOREV UNIQUE: Geographic revenue data is historically difficult to analyze due to:

• Non-standard company reporting formats
• Incomplete geographic disclosures
• Inability to compare across companies

FactSet GeoRev solves these challenges through: 1. Normalization: Maps company revenues to standardized 4-level taxonomy 2. Estimation: Proprietary algorithm uses GDP weighting and accounting logic 3. Consistency: Solves for non-explicit disclosures to create complete picture 4. Confidence Metrics: Ranks and confidence scores distinguish actual vs. estimated data

AUTOMATIC ENDPOINT ROUTING: This tool intelligently routes to 2 different FactSet GeoRev API endpoints:

1. REGIONS ENDPOINT (/regions):

• Trigger: When data_type='regions'
• Use Case: Hierarchical geographic revenue by Super-Regions, Regions, and Areas
• Returns: Revenue, percent, confidence, certainty ranks for regional groupings
• Best For: High-level regional exposure, super-region analysis, regional trends
• Example: "What are Apple's revenue by super-region?" or "Americas vs Europe vs Asia revenue"
• Geographic Levels: Super-Regions (7), Regions (15), Areas (31)
• Default: Returns all SUPER_REGIONS
• Max IDs: 300 companies, etfs, or mutual funds
• Max Regions: 15 region filters

2. COUNTRIES ENDPOINT (/countries):

• Trigger: When data_type='countries'
• Use Case: Country-level revenue breakdown (most granular)
• Returns: Revenue, percent, confidence, certainty ranks for individual countries
• Best For: Country-specific exposure, geopolitical risk, market-level analysis
• Example: "Apple's revenue in China?" or "Compare US vs China revenue exposure"
• Countries: ~300 countries supported globally
• Default: Returns ALL countries
• Max IDs: 300 companies, etfs, or mutual funds
• Max Countries: 300 country filters

CRITICAL DATA DISTINCTIONS:

• Regions: HIERARCHICAL taxonomy (Super-Region → Region → Area)
• Countries: INDIVIDUAL country exposures (bottom of taxonomy)
• Revenue values: In MILLIONS for requested currency
• Confidence: 0.5000 to 1.0000 (1.0000 = actual reported value)
• Certainty Rank: 1 to 80 (80 = reported, 1 = lowest certainty)
• Certainty Class: A (highest) to E (lowest)

FOUR-LEVEL GEOGRAPHIC TAXONOMY:

Level 1: SUPER-REGIONS (7 total):

• R1: Africa and Middle East
• R101: Americas
• R170: Asia/Pacific
• R274: Europe
• R349: Non-Disclosed Revenue
• R354: No Operations
• R393: Non-Geographic Revenue

Level 2: REGIONS (15 major regions): Under Africa and Middle East:

• R2: Africa
• R68: Middle East

Under Americas:

• R102: Latin America
• R164: North America

Under Asia/Pacific:

• R171: Asia
• R233: Oceania

Under Europe:

• R275: European Union
• R314: Non-European Union

Level 3: AREAS (31 areas): Examples:

• R167: United States and Canada
• R172: Far East
• R219: Indian Region
• R234: Australia and New Zealand
• R276: Eastern European Union
• R286: Northern European Union
• R292: Southern European Union
• R298: Western European Union

Level 4: COUNTRIES (~300 countries): Examples: US, CN, JP, DE, GB, FR, IN, BR, CA, AU (use ISO2 codes)

MANDATORY WORKFLOWS BY DATA TYPE:

REGIONS: 1. Identify companies using security identifiers (max 300) 2. Select regional level or specific regions:

• Use 'SUPER_REGIONS' for top-level view
• Use 'REGIONS' for mid-level view
• Use 'AREAS' for sub-regional view
• Use specific region IDs for targeted analysis

3. Optional: Define date range (defaults to latest fiscal period) 4. Optional: Set frequency and currency 5. Analyze hierarchical revenue breakdown with confidence metrics

COUNTRIES: 1. Identify companies using security identifiers (max 300) 2. Select countries:

• Omit or use ['ALL'] for all countries
• Provide ISO2 codes for specific countries

3. Optional: Define date range (defaults to latest fiscal period) 4. Optional: Set frequency and currency 5. Analyze country-level revenue breakdown with confidence metrics

CONFIDENCE AND CERTAINTY METRICS:

Confidence Score (0.5000 to 1.0000):

• Measures algorithm's confidence in geographic revenue estimate
• Based on: GDP data, accounting standards, disclosure details, estimation parameters
• 1.0000 = Actual reported/declared value (no estimation)
• 0.5000-0.9999 = Estimated value with varying confidence
• Ordinal by nature (not statistical confidence interval)
• Calculated for countries, then weighted/aggregated up taxonomy

Certainty Rank (1 to 80):

• Indicates relative reliability of estimates
• 80 = Reported exposure (actual disclosure)
• 1 = Lowest certainty in estimate
• Factors: Reporting standards, historical company reporting, GDP reliability, estimation proportion

Certainty Class (A to E):

• Class A (Highest): Rank 71-80
• Class B: Rank 57-70
• Class C: Rank 42-56
• Class D: Rank 24-41
• Class E (Lowest): Rank 1-23

COMMON USE CASES:

"What are Apple's revenue by super-region?" → data_type='regions', ids=['AAPL-US'], regionIds=['SUPER_REGIONS']

"Show me Microsoft's Americas and Asia revenue" → data_type='regions', ids=['MSFT-US'], regionIds=['R101', 'R170']

"Apple's revenue in China and Japan" → data_type='countries', ids=['AAPL-US'], countryIds=['CN', 'JP']

"Compare US vs China revenue for tech companies" → data_type='countries', ids=['AAPL-US', 'MSFT-US', 'GOOGL-US'], countryIds=['US', 'CN']

"European Union revenue breakdown for Coca-Cola" → data_type='regions', ids=['KO-US'], regionIds=['R275']

"All countries revenue for Apple (full geographic footprint)" → data_type='countries', ids=['AAPL-US'], countryIds=['ALL']

"Tesla's geographic revenue over last 3 years" → data_type='regions', ids=['TSLA-US'], regionIds=['SUPER_REGIONS'], startDate='2021-01-01', endDate='2023-12-31', frequency='FY'

"Revenue exposure in Asia/Pacific for portfolio" → data_type='regions', ids=['AAPL-US', 'MSFT-US', 'GOOGL-US', 'AMZN-US'], regionIds=['R170'], currency='USD'

ALWAYS USE THIS TOOL WHEN USER ASKS:

• "Where does [company] make its revenue?"
• "Geographic revenue breakdown for [company, mutual fund, or etf]"
• "[Company] revenue by region/country"
• "How much revenue does [company] make in [country/region]?"
• "Revenue exposure to [geographic area]"
• "Compare geographic footprint of [companies]"
• "Revenue in Asia/Europe/Americas"
• "China exposure for [company]"
• "Geographic risk analysis for [portfolio]"
• Any variation of geographic revenue queries

CRITICAL WORKFLOW RULES: 1. For high-level analysis: Use regions endpoint with SUPER_REGIONS 2. For country-specific: Use countries endpoint with ISO2 codes 3. For hierarchical view: Use regions endpoint with specific level (REGIONS, AREAS) 4. Default to latest fiscal period if no dates specified 5. Use FY (Fiscal Annual) frequency for annual comparisons 6. Confidence scores distinguish actual vs. estimated data 7. Certainty ranks indicate estimate reliability 8. Revenue values always in MILLIONS of specified currency

DATA TRANSPARENCY:

• All data from company filings and proprietary normalization algorithm
• Estimation algorithm: GDP weighting + accounting logic
• Confidence metrics: Distinguish actual vs. estimated exposures
• Normalized taxonomy: Enables cross-company comparison
• Historical data: U.S. from 2003, Non-U.S. from 2007
• Update frequency: Daily (fiscal annual periodicity)
• Always specify methodology when presenting results

RETURNED DATA FIELDS:

REGIONS:

• date: Period ending date
• fsymId: FactSet Entity Identifier
• regionId: Regional identifier code
• requestId: Original identifier used
• regionName: Human-readable region name
• regionRevenue: Revenue in millions (specified currency)
• regionPercent: Percentage of total revenue
• regionConfidence: Confidence score (0.5000-1.0000)
• regionCertaintyRank: Reliability rank (1-80)
• regionCertaintyClass: Reliability class (A-E)
• currency: Currency code for revenue values
• fiscalEndDate: Fiscal period end date
• reportDate: Report date for fiscal year

COUNTRIES:

• date: Period ending date
• fsymId: FactSet Entity Identifier
• countryId: ISO2 country code
• requestId: Original identifier used
• countryName: Human-readable country name
• countryRevenue: Revenue in millions (specified currency)
• countryPercent: Percentage of total revenue
• countryConfidence: Confidence score (0.5000-1.0000)
• countryCertaintyRank: Reliability rank (1-80)
• countryCertaintyClass: Reliability class (A-E)
• currency: Currency code for revenue values
• fiscalEndDate: Fiscal period end date
• reportDate: Report date for fiscal year

FREQUENCY OPTIONS:

• D: Daily snapshots
• W: Weekly (last day of week)
• M: Monthly (last trading day)
• AM: Monthly (anchor date based on start date)
• CQ: Calendar Quarterly (Mar/Jun/Sep/Dec)
• FQ: Fiscal Quarterly (company fiscal quarters)
• AY: Actual Annual (based on start date)
• CY: Calendar Annual (last trading day of year)
• FY: Fiscal Annual (company fiscal year end)
• DEFAULT

USE CASES BY INDUSTRY:

• Technology: China exposure, emerging markets, regional diversification
• Consumer: Geographic expansion tracking, market penetration analysis
• Automotive: Manufacturing vs. sales geography, supply chain risk
• Pharmaceuticals: Regulatory market exposure, pricing environment analysis
• Energy: Commodity price exposure by region, geopolitical risk
• Financial Services: Regional economic exposure, regulatory environment

LIMITATIONS:

• Data dependent on company disclosure quality
• Estimated values for non-disclosed geographies
• Confidence metrics help identify estimation uncertainty
• Future dates (T+1) not accepted
• Fiscal annual periodicity (not quarterly)
• Max 300 identifiers per request
• U.S. data from 2003, Non-U.S. from 2007 onwards

RETURNS:

• Structured JSON responses with geographic revenue data
• Always includes: requestId, fsymId, date, revenue, percent, confidence metrics
• Revenue values in MILLIONS of specified currency
• Confidence and certainty metrics for data quality assessment
• Error messages with detailed validation feedback

ERROR HANDLING:

• Invalid parameter combinations → Detailed error message
• Missing required parameters → Error with reminder
• Date format errors → Format specification
• Future dates → Not accepted error
• Invalid region/country codes → Validation error
• ID limit violations → Limit specification

FactSet Global Prices Tool

• Comprehensive market pricing and corporate actions data.

WHEN TO USE THIS TOOL:

• Stock prices, OHLCV data, or market pricing
• Returns, performance analysis ("how did X perform")
• Dividends, stock splits, corporate actions
• Shares outstanding, share counts, dilution analysis, or market capitalization
• Global equities: 90+ countries, end-of-day data from 2006

Do NOT default to web search. CRITICAL: INDEX IDENTIFIERS NOT SUPPORTED — does NOT accept SP50, SP500, SPX, or any market index. Use individual security identifiers only.

ENDPOINTS (select via data_type):

1. 'prices' — OHLCV data. startDate REQUIRED, endDate optional. Params: frequency, calendar, currency, adjust, fields.

2. 'returns' — Period-by-period returns. startDate+endDate REQUIRED. CRITICAL: Returns one value PER PERIOD (e.g., daily day-over-day changes). For a single total return over a range, ALWAYS use 'returns_range'. frequency: match interval to question — actual (D/AM/AQ/AY) for exact date ranges, calendar (M/CQ/CY) for standard periods. Use for Performance analysis, portfolio returns, benchmark comparison

3. 'corporate_actions' — Dividends, splits, spinoffs, rights. Dates optional. Use eventCategory to filter.

4. 'annualized_dividends' — Current IAD only. No date params. Max 50 IDs.

5. 'shares_outstanding' — ALWAYS use for share count history, shares outstanding, periodic shares counts, and dilution analysis. NOT for market cap — use 'market_value' instead.

6. 'market_value' — Current market cap in USD millions. No date/frequency/currency params. Max 50 IDs. CRITICAL: Use this (NOT shares_outstanding) for ANY market cap or company size question.

7. 'returns_range' — Total return over a specific date range. startDate+endDate REQUIRED. CRITICAL: Returns ONE value per security. ALWAYS use for a single value over a specified date range. Use 'returns' for period-over-period breakdowns.

DATE HANDLING — Today is {current_date}. Always calculate date ranges from today.

• prices: startDate REQUIRED, endDate optional
• returns: startDate+endDate BOTH REQUIRED; anchored periods → D/AM/AQ/AY; calendar periods → M/CQ/CY; YTD → startDate=Jan 1 of current year
• returns_range: startDate+endDate BOTH REQUIRED
• corporate_actions: both optional (omit for all events)
• annualized_dividends, market_value: NO date params
• shares_outstanding: both optional

ID LIMITS: 500 for single-day prices; 50 for all other/multi-day requests. Accepts: AAPL-US, MSFT-US (ticker-region), CUSIP, SEDOL, ISIN, FactSet Permanent IDs.

FactSet Mergers & Acquisitions Tool

• Comprehensive M&A transaction data.

WHEN TO USE THIS TOOL:

• ANY query about mergers, acquisitions, or M&A transactions
• Questions about "Who did [company] acquire?" or "What deals happened in [period]?"
• Deal values, premiums, and transaction terms
• Acquisition history and corporate development activity
• Public company takeover analysis

DATA COVERAGE & SCOPE:

• 60,000+ globally traded M&A transactions
• Target companies that are publicly traded
• Comprehensive deal terms, pricing, and premiums
• All monetary values converted to USD for standardization
• Historical coverage of completed and pending transactions

AUTOMATIC ENDPOINT ROUTING: This tool intelligently routes to 3 different FactSet M&A API endpoints:

1. DEALS BY COMPANY ENDPOINT (/deals/by-company):

• Trigger: When data_type='deals_by_company'
• Use Case: Find all deals involving specific companies
• Returns: Deal IDs, basic transaction info, participants, status
• Best For: Company acquisition history, deal screening
• Example: "What did IBM acquire in 2024?" or "Show me Apple's M&A activity"
• ID Type: Company identifiers (tickers, FactSet IDs, etc.), max 500
• Optional: Date range filtering by announcement date

2. PUBLIC TARGETS ENDPOINT (/deals/public-targets):

• Trigger: When data_type='public_targets'
• Use Case: Find deals where target is a public company
• Returns: Deal IDs, transaction info for public company acquisitions
• Best For: Market-wide M&A analysis, public target screening
• Example: "Show me all public company acquisitions in Q2 2024"
• Required: Deal status filter (All/Pending/Complete), startDate, endDate
• Date range: Announcement date filtering (max 1 year per request)

3. DEAL DETAILS ENDPOINT (/deals/details):

• Trigger: When data_type='deal_details'
• Use Case: Get comprehensive information for specific deals
• Returns: Financial terms, advisors, premiums, multiples, deal structure
• Best For: Deep-dive transaction analysis, valuation research
• Example: "Show me details for deal ID 4143886MM"
• ID Type: Deal IDs from other M&A endpoints, max 100
• NOTE: Use dealId values from deals_by_company or public_targets first

CRITICAL DATA DISTINCTIONS:

• Deals by Company: Company-centric view (who they acquired/sold)
• Public Targets: Market-wide view (all public company acquisitions)
• Deal Details: Transaction-centric view (comprehensive deal information)
• All values in USD regardless of original currency

MANDATORY WORKFLOWS BY DATA TYPE:

DEALS_BY_COMPANY: 1. Identify companies using proper identifiers (max 500) 2. Define date range for announcement filtering

• REQUIRED

3. Retrieve deal IDs for detailed analysis 4. Use dealId values with deal_details for comprehensive info

PUBLIC_TARGETS: 1. Select deal status filter (All/Pending/Complete)

• REQUIRED

2. Define date range for announcement filtering

• REQUIRED (max 1 year)

3. Retrieve deal IDs for publicly traded targets 4. Use dealId values with deal_details for comprehensive info

DEAL_DETAILS: 1. Obtain deal IDs from deals_by_company or public_targets 2. Submit deal IDs (max 100) for detailed information 3. Analyze financial terms, advisors, premiums, multiples 4. Cross-reference with other FactSet endpoints as needed

DATE HANDLING (CRITICAL):

DEALS_BY_COMPANY:

• startDate: REQUIRED (YYYY-MM-DD) - filters by announcement date
• endDate: REQUIRED (YYYY-MM-DD) - filters by announcement date
• Example: startDate='2024-01-01', endDate='2024-12-31'

PUBLIC_TARGETS:

• startDate: REQUIRED (YYYY-MM-DD) - filters by announcement date
• endDate: REQUIRED (YYYY-MM-DD) - filters by announcement date
• Example: startDate='2024-01-01', endDate='2024-12-31'

DEAL_DETAILS:

• NO date parameters (uses deal IDs directly)

EFFICIENCY REQUIREMENTS:

• Deals by Company: 500 company IDs maximum
• Public Targets: No ID limit (market-wide screening)
• Deal Details: 100 deal IDs maximum
• All endpoints: 10 requests per second, 10 concurrent requests

Multi-Year M&A Analysis (REQUIRED APPROACH): For "Amazon acquisitions since 2015", make sequential calls: → Call 1: startDate='2015-01-01', endDate='2015-12-31' → Call 2: startDate='2016-01-01', endDate='2016-12-31' → ... continue for each year → Aggregate results across all calls

COMMON USE CASES:

"What did IBM acquire in 2024?" → data_type='deals_by_company', ids=['IBM-US'], startDate='2024-01-01', endDate='2024-12-31'

"Show me all pending public company acquisitions in 2024" → data_type='public_targets', status='Pending', startDate='2024-01-01', endDate='2024-12-31'

"Get details for deal 4143886MM" → data_type='deal_details', ids=['4143886MM']

"Recent M&A activity for Apple" → data_type='deals_by_company', ids=['AAPL-US'], startDate='2025-01-01', endDate='2025-10-15'

"Q2 2024 public target deals" → data_type='public_targets', status='All', startDate='2024-04-01', endDate='2024-06-30'

ALWAYS USE THIS TOOL WHEN USER ASKS:

• "What companies did [X] acquire in [year]?"
• "Recent M&A activity for [company]"
• "[Company] acquisition history"
• "Largest deals in [time period]"
• "Public company acquisitions in [period]"
• "Show me details for deal [ID]"
• Any variation of M&A or deal queries

DATA TRANSPARENCY:

• All data from official deal announcements and regulatory filings
• Monetary values converted to USD for standardization
• Deal status tracked: Pending, Complete, Cancelled, Rumor
• Coverage includes completed and announced transactions
• Always specify date ranges and filters used
• State limitations clearly when data not available

COMPREHENSIVE DEAL INFORMATION (DEAL_DETAILS):

• Transaction Overview: Deal type, structure, dates, status
• Financial Terms: Deal value, premiums (1-day, 5-day, 30-day), payment method
• Parties: Target, buyer(s), seller(s), ultimate parents
• Advisors: Financial advisors, legal counsel, fees
• Valuation Multiples: EV/Sales, EV/EBIT, EV/EBITDA
• Deal Rationale: Purpose (Financial vs. Strategic), summary

DEAL PARTICIPATION TYPES:

• BUYER: Company acquiring another entity or assets
• SELLER: Company divesting assets or subsidiaries
• TARGET: Company being acquired or subject to takeover
• ADVISOR: Financial or legal advisor to transaction

RETURNS:

• Structured JSON responses with requested data
• Always includes: dealId, target, buyers, sellers, announceDate, status
• Deal Details: Comprehensive transaction information with USD values
• Error messages with detailed validation feedback

ERROR HANDLING:

• Invalid parameter combinations → Detailed error message
• Missing required parameters → Error with reminder
• Date format errors → Format specification
• ID limit violations → Limit specification
• Invalid identifiers → List of unrecognized IDs

Vector Search Tool

• Semantic search for financial metrics and categories.

WHEN TO USE THIS TOOL: This tool should be used for:

• Discovering financial metric codes before calling Fundamentals or Estimates APIs
• Finding metrics by natural language description (e.g., "profitability ratios")
• Exploring available categories and subcategories in the ontology
• Semantic search when you don't know the exact metric code
• Batch discovery of multiple related metrics simultaneously

CRITICAL USAGE RULES:

• Use this BEFORE calling Fundamentals or Estimates APIs when you don't know exact metric codes
• Provides semantic understanding - searches by meaning, not just keywords
• Returns actual metric codes (e.g., FF_SALES, FF_EBITDA) to use in other API calls
• Supports batch queries - search for multiple metrics in one request

DATA COVERAGE & SCOPE:

• Comprehensive financial ontology from FactSet Content API
• Includes fundamentals metrics (FF_* codes)
• Includes estimates metrics (unprefixed codes)
• Categories and subcategories for all data products

SEARCH CAPABILITIES:

TARGET TYPES: 1. metric: Individual financial data points

• Examples: "revenue", "EBITDA", "debt-to-equity ratio", "EPS"
• Returns: Specific metric codes like FF_SALES, FF_EBITDA, FF_DEBT_EQ
• Use for: Finding exact metrics to use in Fundamentals/Estimates APIs

2. category: High-level financial statement groupings

• Examples: "Income Statement", "Balance Sheet", "Cash Flow"
• Returns: Category names and their associated metrics
• Use for: Understanding ontology structure

3. subcategory: Mid-level groupings within categories

• Examples: "REVENUES", "ASSETS", "LIABILITIES", "PROFITABILITY"
• Returns: Subcategory names and their metrics
• Use for: Focused metric discovery within specific areas

DATA PRODUCT FILTERING: Filter results to specific FactSet data products:

fundamentals:

• Returns: FF_* prefixed metric codes (FF_SALES, FF_ASSETS, FF_EPS)
• Use for: Finding metrics for actual reported financial statements
• Examples: FF_SALES (revenue), FF_NET_INC (net income), FF_DEBT_EQ (debt-to-equity)

estimates:

• Returns: Unprefixed metric codes (SALES, EPS, EBITDA, PRICE_TGT)
• Use for: Finding metrics for analyst forecasts and estimates
• Examples: SALES (revenue estimates), EPS (earnings estimates)

Omit data_products: Search across all data products simultaneously

BATCH PROCESSING: Process multiple queries in a single API call for efficiency:

Benefits:

• Reduced latency (fewer round-trips to server)
• Concurrent processing of all queries
• Consistent results across related searches
• Better performance for bulk metric discovery

Example:

text=["revenue metrics", "profitability ratios", "debt metrics"],
target="metric",
data_products=["fundamentals"],
limit=5

Returns top 5 results for each of the 3 queries in one response.

MANDATORY WORKFLOW:

STEP 1: SEMANTIC SEARCH Use this tool to discover metric codes based on natural language:

text=["revenue", "operating profit", "total debt"],
target="metric",
data_products=["fundamentals"],
limit=5

STEP 2: EXTRACT METRIC CODES From the response, extract the 'metric' field from properties:

{
    "properties": {
        "metric": "FF_SALES",
        "name": "Sales/Revenue",
        "category": "INCOME_STATEMENT"
    }
}

STEP 3: USE IN OTHER APIS Use discovered codes in Fundamentals or Estimates APIs:

# For Fundamentals
Fundamentals(
    data_type="fundamentals",
    ids=["AAPL-US"],
    metrics=["FF_SALES", "FF_OPER_INC", "FF_DEBT"]
)

COMMON USE CASES:

1. Find revenue metrics for fundamentals:

text=["revenue", "sales"],
target="metric",
data_products=["fundamentals"],
limit=5

Returns: FF_SALES, FF_SALES_REV_TURN, etc.

2. Discover profitability ratios:

text=["profitability ratios", "return on equity", "profit margins"],
target="metric",
data_products=["fundamentals"],
limit=10

Returns: FF_ROE, FF_NET_MGN, FF_EBIT_OPER_MGN, etc.

3. Find all balance sheet categories:

text=["balance sheet"],
target="category",
limit=20

Returns: BALANCE_SHEET category with all subcategories

4. Search for debt-related metrics:

text=["debt", "leverage", "borrowings"],
target="metric",
data_products=["fundamentals"],
limit=10

Returns: FF_DEBT, FF_DEBT_ST, FF_DEBT_LT, FF_DEBT_EQ, etc.

5. Find estimate metrics for earnings:

text=["earnings estimates", "EPS forecasts"],
target="metric",
data_products=["estimates"],
limit=5

Returns: EPS, NET_INC, etc. (unprefixed for estimates)

6. Batch discovery for financial analysis:

text=[
    "revenue growth metrics",
    "operating efficiency ratios",
    "liquidity measures",
    "debt coverage ratios"
],
target="metric",
data_products=["fundamentals"],
limit=5

Returns: Top 5 metrics for each of 4 categories

ALWAYS USE THIS TOOL WHEN:

• User asks about available metrics without knowing codes
• User describes metrics in natural language ("profitability", "liquidity")
• Before calling Fundamentals/Estimates APIs with unknown metric codes
• User wants to explore related metrics in a category
• User needs to find metrics across multiple concepts simultaneously

RESPONSE STRUCTURE:

{
    "results": [
        {
            "query": "revenue",
            "targets": ["metric"],
            "class_name": "combined_content_test_6",
            "results": [
                {
                    "distance": 0.15,
                    "score": 0.85,
                    "properties": {
                        "metric": "FF_SALES",
                        "name": "Sales/Revenue",
                        "description": "Net Sales or Revenue...",
                        "category": "INCOME_STATEMENT",
                        "subcategory": "REVENUES",
                        "type": "metric"
                    }
                }
            ],
            "search_parameters": {
                "use_hybrid": true,
                "alpha": 0.4,
                "limit": 20,
                "data_products": ["fundamentals"]
            }
        }
    ]
}

KEY FIELDS:

• metric: Actual code to use in API calls (FF_SALES, EPS, etc.)
• name: Human-readable metric name
• description: Detailed methodology and calculation
• category: High-level grouping (INCOME_STATEMENT, BALANCE_SHEET, etc.)
• subcategory: Specific grouping within category
• distance: Lower = better match (vector distance)
• score: Higher = better match (when available)

INTEGRATION WITH OTHER TOOLS:

WITH FUNDAMENTALS API: 1. Use VectorMetricSearch to find: FF_SALES, FF_NET_INC, FF_ASSETS 2. Call Fundamentals with discovered codes:

Fundamentals(
       data_type="fundamentals",
       ids=["AAPL-US"],
       metrics=["FF_SALES", "FF_NET_INC", "FF_ASSETS"]
   )

WITH ESTIMATES API: 1. Use VectorMetricSearch with data_products=["estimates"] 2. Find unprefixed codes: SALES, EPS, EBITDA 3. Call Estimates with discovered codes:

Estimates(
       estimate_type="consensus",
       ids=["AAPL-US"],
       metrics=["SALES", "EPS"]
   )

EFFICIENCY TIPS:

BATCH QUERIES: Instead of 3 separate calls:

# Bad: 3 API calls
search("revenue")
search("profit")
search("debt")

Do this:

# Good: 1 API call
text=["revenue", "profit", "debt"],
target="metric",
limit=5

FILTER BY DATA PRODUCT: Narrow results for faster, more relevant responses:

# For fundamentals queries
data_products=["fundamentals"]



# For estimates queries
data_products=["estimates"]

ADJUST SEARCH MODE:

• Use hybrid (default) for most cases
• Use alpha=0.0 for exact term matching
• Use alpha=1.0 for pure semantic similarity

LIMITATIONS:

• Returns metric codes, not actual data values
• Requires subsequent API calls to get financial data
• Search quality depends on query phrasing
• Some metrics may not be available for all companies
• Distance/score thresholds not standardized across queries

USE FOR: Metric discovery, semantic search, ontology exploration, batch metric lookup DO NOT USE FOR: Actual financial data retrieval (use Fundamentals/Estimates instead)

RETURNS:

• Structured JSON with search results for each query
• Metric codes, names, descriptions, categories
• Search parameters used for each query
• Distance/score metrics for result ranking

ERROR HANDLING:

• Invalid target type → Detailed error with valid options
• Invalid data products → List of valid data products
• Empty results → Suggest broader search terms
• API errors → Detailed error message with context

FactSet Ownership Tool

• Comprehensive holdings, holders, and transactions data.

WHEN TO USE THIS TOOL:

• Fund holdings, portfolio composition, or what funds own
• Institutional ownership, insider ownership, or shareholder data
• Insider trading activity, executive transactions, or Form 4 filings
• Institutional position changes, 13F filings, or "smart money" tracking
• Questions like "What does [fund] own?" or "Who owns [stock]?"

NOTE: Use data_type='fund_holdings' to retrieve what a fund/ETF holds (its underlying securities). This is distinct from FactSet_FundsETF which covers fund performance, NAV, flows, and analytics — NOT holdings composition.

DATA COVERAGE: 60,000+ fund portfolios, 50,000 institutions, 400,000 insider records, 110+ countries. From 2006+.

ENDPOINTS (select via data_type):

1. 'fund_holdings' — Holdings for mutual funds, ETFs, closed-end funds. Max 10 IDs. Note: Security names/tickers reflect the CURRENT security master, not the snapshot date — surface this caveat when returning historical holdings.

2. 'security_holders' — Who owns a security (institutions, funds, insiders, beneficial owners). CRITICAL: Max 1 security per request.

3. 'insider_transactions' — Executive/director trades from SEC Form 4/5. Max 10 IDs. CRITICAL: startDate+endDate REQUIRED. sharesOwned is per-filing only — NOT the insider's current position; use security_holders with holderType='S' for absolute position.

4. 'institutional_transactions' — Position changes from 13F filings. Max 10 IDs. CRITICAL: startDate+endDate REQUIRED. posChange is a delta, not absolute shares held; use security_holders with holderType='F'/'M' for absolute counts. Optional params: holderType, topNHolders, frequency (M/CQ/CY), periodOfMeasure (1M/3M/6M/12M), currency. DATE PATTERNS:

• Regular date range (e.g., "in Q2 2024", "during H2 2020", "full year 2022"):

startDate='2024-04-01', endDate='2024-06-30' — use actual range bounds

• Rolling N-month window (e.g., "past 6 months", "last quarter position changes"):

Set startDate AND endDate to the SAME reference date (today or date you're analyzing), use periodOfMeasure for the window (1M/3M/6M/12M) Set frequency to 'M' (monthly) Example: past 3 months → startDate='2025-03-31', endDate='2025-03-31', periodOfMeasure='3M', frequency='M'

DATE HANDLING:

• fund_holdings, security_holders: date optional (defaults to latest month-end)
• insider_transactions, institutional_transactions: startDate+endDate BOTH REQUIRED

ID LIMITS: Max 10 for fund_holdings/insider_transactions/institutional_transactions; max 1 for security_holders. Accepts: ticker-region (AAPL-US, VTI-US), CUSIP, SEDOL, ISIN, FactSet IDs.

CRITICAL POSITION INTERPRETATION RULES:

insider_transactions — sharesOwned IS NOT A POSITION, NEVER PRESENT IT AS ONE:

• sharesOwned: Shares owned as reported on that individual filing only — varies record-to-record,

scoped to that filing. For authoritative position size, use security_holders with holderType='S' and read adjHolding.

• shares: Transaction size (delta only) — what changed in that single transaction.

institutional_transactions — posChange IS A DELTA, NOT A POSITION:

• posChange: Change in shares held over the periodOfMeasure window. DO NOT present as shares held.
• For absolute institutional share counts, use security_holders with holderType='F' or 'M' and read adjHolding.

FactSet People Tool

• Comprehensive executive and leadership data.

WHEN TO USE THIS TOOL:

• ANY query about executives, leadership, or company personnel
• Questions about "Who is the CEO/CFO/founder of [company]?"
• Executive backgrounds, career histories, and professional profiles
• Compensation analysis and leadership demographics
• Board composition and governance analysis

CRITICAL EXECUTIVE IDENTIFICATION RULE: For ALL executive identification requests (CEO, CFO, founders, leadership team), NEVER provide executive names from training data without first querying actual FactSet personnel data. This applies to ANY question about "Who is the [position] of [company]?" regardless of how well-known the company or executive may seem.

DATA COVERAGE & SCOPE:

• 50,000+ institutions and executive profiles
• 400,000+ insider/stakeholder records
• 110+ countries represented
• Global coverage with varying disclosure depth by region
• US compensation data only (regulatory requirement)

AUTOMATIC ENDPOINT ROUTING: This tool intelligently routes to 6 different FactSet People API endpoints:

1. PROFILES ENDPOINT (/profiles):

• Trigger: When data_type='profiles'
• Use Case: Personal and professional profile information for individuals
• Returns: Biographical data, education, employment, compensation
• Best For: Executive research, background verification, career analysis
• Example: "Give me the profile of Philip Snow"
• ID Type: Person Entity IDs (XXXXXX-E), max 500 per request

2. JOBS ENDPOINT (/jobs):

• Trigger: When data_type='jobs'
• Use Case: Employment history and career progression
• Returns: Current and past positions, job functions, timeline data
• Best For: Career tracking, professional background, succession planning
• Example: "What is the job history of this executive?"
• ID Type: Person Entity IDs (XXXXXX-E), max 1,000 per request

3. COMPANY PEOPLE ENDPOINT (/company-people):

• Trigger: When data_type='company_people'
• Use Case: Executive and leadership roster for companies
• Returns: Names, titles, contact info, job functions
• Best For: Leadership mapping, organizational analysis, contact database
• Example: "Show me all directors at Apple"
• ID Type: Company IDs (tickers, FactSet IDs, etc.), max 1,000 per request

4. COMPANY POSITIONS ENDPOINT (/company-positions):

• Trigger: When data_type='company_positions'
• Use Case: Specific position holders with demographics and tenure
• Returns: Executive name, tenure, age, gender for specific role
• Best For: CEO/CFO identification, founder research, succession analysis
• Example: "Who is the CEO of Tesla?" or "Who founded Microsoft?"
• ID Type: Company IDs, max 1,000 per request
• CRITICAL: ALWAYS use this for "Who is the [position]?" queries

5. COMPANY COMPENSATION ENDPOINT (/company-compensation):

• Trigger: When data_type='company_compensation'
• Use Case: Executive pay analysis (US companies only)
• Returns: Salary, bonus, stock awards, total compensation
• Best For: Pay benchmarking, compensation studies, governance research
• Example: "What is Tim Cook's compensation?"
• ID Type: US company IDs only, max 1,000 per request
• LIMITATION: US companies only due to regulatory disclosure requirements

6. COMPANY STATS ENDPOINT (/company-stats):

• Trigger: When data_type='company_stats'
• Use Case: Leadership statistics and demographic analysis
• Returns: Average age, tenure, diversity metrics, board composition
• Best For: Governance benchmarking, diversity assessment, leadership analysis
• Example: "What is the average age of Apple's management?"
• ID Type: Company IDs, max 1,000 per request

CRITICAL DATA DISTINCTIONS:

• Person Endpoints (profiles, jobs): Use Person Entity IDs (XXXXXX-E format)
• Company Endpoints (company_*): Use company identifiers (tickers, FactSet IDs)
• Compensation: US companies only, values in raw USD units
• Stats: Aggregated metrics, not individual executive details

MANDATORY WORKFLOWS BY DATA TYPE:

PROFILES: 1. Identify individuals using Person Entity IDs (XXXXXX-E) 2. Request profile data (max 500 IDs) 3. Analyze education, employment, compensation 4. Cross-reference personId for detailed analysis

JOBS: 1. Identify individuals using Person Entity IDs (XXXXXX-E) 2. Select employment filters (status, level, type) 3. Request job history (max 1,000 IDs) 4. Analyze career progression and timeline

COMPANY_PEOPLE: 1. Identify companies using company identifiers 2. Select job function filter (PEOPLE/OFFICER/DIRECTOR) 3. Request executive roster (max 1,000 companies) 4. Review organizational structure and contacts

COMPANY_POSITIONS: 1. Identify companies using company identifiers 2. Select target position (CEO/CFO/FOU/etc.) 3. Request position holders (max 1,000 companies) 4. Analyze tenure, demographics, leadership

• CRITICAL: ALWAYS use this for "Who is the [position]?" queries

COMPANY_COMPENSATION: 1. Identify US companies only 2. Request compensation data (max 1,000 companies) 3. Analyze pay components and total packages 4. Benchmark across peer companies

COMPANY_STATS: 1. Identify companies using company identifiers 2. Select leadership scope (MB/MGMT/BRD) 3. Request statistics (max 1,000 companies) 4. Analyze demographics, tenure, diversity

ID REQUIREMENTS BY DATA TYPE:

PROFILES:

• IDs: Person Entity IDs (XXXXXX-E)
• Maximum: 500 identifiers per request
• Example: ["0DPHLH-E"]

JOBS:

• IDs: Person Entity IDs (XXXXXX-E)
• Maximum: 1,000 identifiers per request
• Example: ["0DPHLH-E", "07MZV9-E"]

COMPANY_PEOPLE:

• IDs: Company identifiers (tickers, FactSet IDs including private companies, CUSIP, SEDOL, ISIN)
• Maximum: 1,000 identifiers per request
• Example: ["AAPL-US"]

COMPANY_POSITIONS:

• IDs: Company identifiers (including private companies)
• Maximum: 1,000 identifiers per request
• Example: ["TSLA-US", "MSFT-US"]

COMPANY_COMPENSATION:

• IDs: US company identifiers only (including private companies)
• Maximum: 1,000 identifiers per request
• Example: ["AAPL-US"]

COMPANY_STATS:

• IDs: Company identifiers (including private companies)
• Maximum: 1,000 identifiers per request
• Example: ["AAPL-US", "GOOGL-US"]

COMMON USE CASES:

"Who is the CEO of Apple?" → data_type='company_positions', ids=['AAPL-US'], position='CEO'

"Who founded Microsoft?" → data_type='company_positions', ids=['MSFT-US'], position='FOU'

"Show me Tim Cook's background" → data_type='profiles', ids=['05F520-E'] (requires person ID)

"What is the job history of this executive?" → data_type='jobs', ids=['0DPHLH-E'], status='ALL', level='DETAIL'

"List all directors at Apple" → data_type='company_people', ids=['AAPL-US'], function='DIRECTOR'

"What is Apple CEO's compensation?" → data_type='company_compensation', ids=['AAPL-US']

"What is the average age of Apple's board?" → data_type='company_stats', ids=['AAPL-US'], mbType='BRD'

ALWAYS USE THIS TOOL WHEN USER ASKS:

• "Who is the CEO/CFO/CTO/founder of [X]?"
• "Show me [company]'s leadership team"
• "What is [executive]'s background?"
• "[Executive] career history"
• "How much does [executive] make?"
• "Average age of [company]'s board"
• Any variation of executive or leadership queries

DATA TRANSPARENCY:

• All data from official company filings and verified sources
• Person IDs enable cross-referencing across endpoints
• Compensation data: US companies only, raw USD units
• Coverage varies by company size and disclosure practices
• Always specify limitations when data not available

GEOGRAPHIC LIMITATIONS:

• Profiles/Jobs: Global coverage with Person Entity IDs
• Company People/Positions/Stats: Global companies
• Compensation: US companies ONLY (regulatory requirement)

RETURNS:

• Structured JSON responses with requested data
• Always includes: requestId, and data type-specific fields
• Error messages with detailed validation feedback

ERROR HANDLING:

• Invalid parameter combinations → Detailed error message
• Missing required parameters → Error with reminder
• Wrong ID format → Format specification
• US-only limitation (compensation) → Geographic restriction message
• Invalid identifiers → List of unrecognized IDs

FactSet Private Equity & Venture Capital Tool

• Comprehensive PE/VC data.

WHAT THIS TOOL COVERS: Private equity and venture capital data including funds, general partners (GPs), limited partners (LPs), portfolio companies, transactions (VC rounds, PE deals), M&A activity, and IPO exits.

AUTOMATIC ENDPOINT ROUTING: This tool routes to 14 different endpoints based on the data_type parameter:

---

UNIVERSE (Entity Lookup):

1. universe — Resolve a firm, fund, or portfolio company name to a FactSet Entity ID.

• REQUIRED: name (the firm/fund/company name to look up)
• OPTIONAL: country (ISO2 country code to narrow results), entityType (filter by entity type)
• Returns: List of candidate matches sorted by match quality (best matches first) with:
• entityId (format 'XXXXXX-E')
• entityName
• matchFlag (boolean: true = direct match to query, false = candidate match)
• Results are pre-sorted with exact/best matches appearing first — typically use the first result
• USE FIRST: Always call this to get FactSet entity IDs before using other data_types
• Entity type codes: PVT (Private Company), VEN (Venture Capital Fund), PVF (Private Equity Fund),

FAF (Family of Funds), HOL (Holding Company), NPO (Non-Profit), SUB (Subsidiary), JVT (Joint Venture)

---

FUNDS:

2. funds — Core profile and summary for one or more PE/VC funds.

• REQUIRED: ids (fund entity IDs, format 'XXXXXX-E')
• Returns: Fund status, strategy type, vintage year, financial info (amount raised, dry powder),

investment criteria (min/max deal size, EBITDA, revenue), fund terms (management fee, carry), features (ESG, co-invest)

3. funds_portfolio_companies — List of portfolio companies held by specified funds.

• REQUIRED: ids (fund entity IDs)
• Returns: FactSet entity IDs and names of portfolio companies, investment date, sector

4. funds_fundraising — Complete fundraising history (closes) for specified funds.

• REQUIRED: ids (fund entity IDs)
• Returns: Each fundraising close (First, Second, Final, etc.) with close date, amount raised, target amounts, currency

5. funds_cashflows — Quarterly cash flow time-series (contributions and distributions) for funds.

• REQUIRED: ids (fund entity IDs)
• OPTIONAL: startDate (YYYY-MM-DD), endDate (YYYY-MM-DD), cfType ('CONTRIBUTION', 'DISTRIBUTION', or 'NAV')
• Returns: Date, cash flow type, amount in reporting currency and USD

---

GENERAL & LIMITED PARTNERS:

6. general_partners — Core profile for General Partner (GP) firms.

• REQUIRED: ids (GP entity IDs, format 'XXXXXX-E')
• OPTIONAL: asOfDate (YYYY-MM-DD, for AUM data)
• Returns: GP name, AUM (with date), investment criteria, ESG focus, public company investment flag

7. general_partners_funds — All funds managed by specified GP firms.

• REQUIRED: ids (GP entity IDs)
• Returns: List of fund IDs, names, status (Raising/Investing/Divesting/Liquidated), launch date, amount raised

8. limited_partners — Limited partners and their capital commitments to specified funds (via /limited-partners/funds).

• REQUIRED: ids (fund entity IDs, format 'XXXXXX-E')
• Returns: LP name, LP entity ID, commit date, commit amount (local currency and USD), fundraising close code

---

TRANSACTIONS:

9. transactions — Detailed data for specific PE/VC transactions by transaction ID.

• REQUIRED: ids (transaction IDs — INTEGER values, e.g., [1000001, 1000002])
• Returns: Portfolio company, investment type, status, dates, deal size, pre/post-money valuation,

funding round, stage, investors (with lead flag, fund used, amount invested), securities used

10. transactions_search — Search/filter the full transaction universe by company, stage, and date.

• REQUIRED: ids (portfolio company entity IDs, format 'XXXXXX-E')
• OPTIONAL: status ('Pending', 'Cancelled', 'Completed'), stage ('Seed', 'Early', 'Late', 'Recap'),

investmentType ('Venture Capital', 'Growth', 'Corporate', 'Capitalization', 'Angel', 'Crowdfunding', 'Accelerator/Incubator', 'Secondary', 'Undisclosed Round'), startDate, endDate (YYYY-MM-DD announcement date range), minAmount, maxAmount (USD transaction amount filter)

• Returns: Transaction IDs, portfolio company name, announcement/close dates, total amount (USD), stage, status

11. transactions_ma_activity — M&A advisory and investment details for specific transactions.

• REQUIRED: ids (transaction IDs — INTEGER values)
• Returns: Advisors (financial/legal, client type), investments (entry/exit type, deal ID, IPO ID, retaining stake)

---

IPOs:

12. ipos — Detailed IPO data for portfolio company exits by deal ID.

• REQUIRED: ids (deal IDs — INTEGER values, e.g., [410294, 730294])
• Returns: IPO ID, portfolio company name, ticker, trade date, offer price (local and USD),

IPO size (millions), status, announcement/pricing dates

13. ipos_search — Search/filter the IPO universe by status, size, and date.

• REQUIRED: None (all parameters optional)
• OPTIONAL: status ('Closed', 'Announced', 'Postponed', 'Cancelled', 'Priced', 'Withdrawn', 'In Registration'),

startDate, endDate (YYYY-MM-DD announcement date range), minSizeUsd, maxSizeUsd (IPO size filter in USD millions)

• Returns: IPO ID, portfolio company name, ticker, trade date, offer price (USD), IPO size, status

---

STRATEGIES:

14. entity_strategies — Detailed investment strategy mandate for a fund or GP.

• REQUIRED: ids (fund or GP entity IDs, format 'XXXXXX-E')
• Returns: Geographic focus (regions, countries, states), sector/industry focus, investment instruments,

transaction strategies, control criteria, investor roles

---

TYPICAL WORKFLOWS:

"What funds does [GP firm] manage?" 1. Call data_type='universe' with name='[GP firm name]' to get GP entity ID 2. Call data_type='general_partners_funds' with ids=[gp_entity_id]

"Show me details on [fund name]" 1. Call data_type='universe' with name='[fund name]', entityType=['VEN'] or ['PVF'] 2. Call data_type='funds' with ids=[fund_entity_id]

"Who are the LPs in [fund]?" 1. Resolve fund entity ID via universe 2. Call data_type='limited_partners' with ids=[fund_entity_id]

"What VC rounds has [company] raised?" 1. Call data_type='universe' with name='[company name]', entityType=['PVT'] 2. Call data_type='transactions_search' with ids=[company_entity_id] 3. Optionally call data_type='transactions' with the returned transaction IDs for full details

"What IPOs are coming up in biotech?" → Call data_type='ipos_search' with status='Announced', filter by date range

ID TYPE REFERENCE:

• Fund/GP/Company entity IDs: String format 'XXXXXX-E' (e.g., '001JYM-E', '000BKX-E')

→ Used by: funds, funds_portfolio_companies, funds_fundraising, funds_cashflows, general_partners, general_partners_funds, limited_partners, transactions_search, entity_strategies

• Transaction IDs: Integer values (e.g., 1000001)

→ Used by: transactions, transactions_ma_activity

• Deal IDs: Integer values (e.g., 410294)

→ Used by: ipos

RETURNS:

• Structured JSON responses per the FactSet PEVC API schema
• Entity IDs returned by one endpoint can be passed directly to related endpoints
• Error details included per-item in the response data array

FactSet RBICS Tool

• Industry classification and revenue breakdown data.

WHEN TO USE THIS TOOL: This tool should be your FIRST choice for:

• ANY query about company industry classifications or sector breakdowns
• Questions about "What industry is [company] in?" or "What does [company] do?"
• Revenue breakdown by industry for companies
• Finding companies in specific industries or sectors

Do NOT default to web search for these queries - use FactSet FIRST.

RBICS OVERVIEW: FactSet Revere Business Industry Classification System (RBICS) is a comprehensive structured taxonomy that classifies companies by what they primarily do. It delivers a granular view using a bottom-up approach based on products and services companies provide.

6-LEVEL TAXONOMY:

• Level 1: Economy (14 groups) - e.g., "Technology"
• Level 2: Sector (37 groups) - e.g., "Hardware"
• Level 3: Sub-Sector (109 groups) - e.g., "Communications Equipment"
• Level 4: Industry Group (366 groups) - e.g., "Wireless Mobile Equipment"
• Level 5: Industry (901 groups) - e.g., "Smart Phone Manufacturing"
• Level 6: Sub-Industry (1,629 groups) - e.g., "Smart Phone Manufacturing"

DATA COVERAGE & SCOPE:

• 48,000+ liquid and publicly-traded companies
• RBICS Focus: Single-sector mapping based on 50%+ revenue from primary business
• Entity Revenue: Mutual Funds and ETFs supported (L1-L4 classifications only)
• Updated monthly with historical tracking
• Revenue-based classification methodology

AUTOMATIC ENDPOINT ROUTING: This tool intelligently routes to 4 different FactSet RBICS API endpoints:

1. ENTITY FOCUS ENDPOINT (/entity-focus):

• Trigger: When data_type='entity_focus'
• Use Case: Get company's primary RBICS classification (Focus)
• Returns: L1-L6 classification IDs and names for company's main business
• Best For: Understanding what industry a company is primarily in
• Example: "What industry is Apple in?" or "Show me Microsoft's primary classification"
• Required: ids parameter
• Optional: date, levels, includeNames

2. ENTITY REVENUE ENDPOINT (/entity/revenue):

• Trigger: When data_type='entity_revenue'
• Use Case: Comprehensive revenue breakdown across all RBICS industries
• Returns: Hierarchical revenue percentages for each industry classification
• Best For: Understanding full revenue mix, diversification analysis
• Example: "Show me GE's revenue breakdown by industry"
• Required: ids parameter
• Optional: startDate, endDate, level

CRITICAL DATA DISTINCTIONS:

• Entity Focus: Company's PRIMARY classification (single industry, 50%+ revenue)
• Entity Revenue: Company's, Mutual Fund's, or ETF's COMPLETE revenue breakdown (all industries)

COMMON USE CASES:

"What industry is Apple in?" → data_type='entity_focus', ids=['AAPL-US'], includeNames=True

"Show me Apple's revenue breakdown by industry" → data_type='entity_revenue', ids=['AAPL-US'], level=6

"What was Tesla's primary industry in 2020?" → data_type='entity_focus', ids=['TSLA-US'], date='2020-12-31', includeNames=True

ALWAYS USE THIS TOOL WHEN USER ASKS:

• "What industry/sector is [company] in?"
• "Show me [company]'s industry classification"
• "[Company] revenue breakdown by industry"

DATA TRANSPARENCY:

• All classifications based on actual company revenues and business lines
• RBICS Focus uses 50%+ revenue threshold for primary classification
• Entity Revenue only supports L1-L4 classifications for Mutual Funds and ETFs
• Updated monthly with historical tracking
• Coverage varies by company disclosure practices
• Always specify date ranges and parameters used

LIMITATIONS:

• Maximum 2,500 identifiers per request
• Future dates (T+1) not accepted
• Date format must be YYYY-MM-DD
• Rate limited to 10 requests per second
• Entity Revenue ONLY: Mutual Funds and ETFs response times may exceed 20s for queries over 1 year

RETURNS:

• Structured JSON responses with classification/revenue data
• Entity Focus: Company classifications with effective dates
• Entity Revenue: Hierarchical revenue percentages by industry
• Error messages with detailed validation feedback

ERROR HANDLING:

• Invalid parameter combinations → Detailed error message
• Missing required parameters → Error with reminder
• Date format errors → Format specification
• Invalid RBICS IDs → Validation error

FactSet Supply Chain Tool

• Comprehensive business relationship data.

WHEN TO USE THIS TOOL:

• ANY query about competitors, competitive landscape, or "who competes with"
• Questions about suppliers, customers, or business partners
• Supply chain analysis and business network mapping
• Strategic relationship identification
• Market positioning and competitive intelligence

DATA COVERAGE & SCOPE:

• Comprehensive relationship networks across global markets
• Data sourced from trusted primary sources (10-K, annual reports, company disclosures)
• Reverse-linked relationships creating complete bidirectional network
• Product/service overlap metrics for relationship strength assessment
• Coverage includes both public and private company relationships

CRITICAL: UNDERSTANDING RELATIONSHIP DIRECTION

The relationshipDirection parameter fundamentally changes WHAT data you retrieve:

DIRECT (Company disclosed them):

• Use when: "Show me competitors [Company] disclosed", "Who does [Company] list as competitors", "[Company]'s stated competitors"
• Returns: Companies that [COMPANY] named in [COMPANY]'s filings
• Example: Apple says "Microsoft is our competitor" → Microsoft appears in results

REVERSE (They disclosed Company):

• Use when: "Who considers [Company] a competitor", "Companies that list [Company] as competition", "Who competes with [Company]"
• Returns: Companies that named [COMPANY] in THEIR filings
• Example: Logitech says "Apple is our competitor" → Logitech appears in results

ALL (default - both directions):

• Returns complete bidirectional network
• Use when direction doesn't matter or you want comprehensive competitive landscape

Use DIRECT when query contains:

• "disclosed by [company]"
• "[company]'s stated/listed competitors"
• "[company] identified/named as competitors"
• "in [company]'s filings"

Use REVERSE when query contains:

• "who considers [company] a competitor"
• "companies competing with [company]"
• "who lists [company] as competition"

Use ALL (or omit) when:

• Query is ambiguous
• Want complete competitive picture
• Comparing multiple perspectives

DEFAULT BEHAVIOR: If relationshipDirection parameter is omitted, defaults to 'ALL' (both directions). For queries asking what a company disclosed, you MUST explicitly set relationshipDirection='DIRECT'.

SINGLE ENDPOINT: This tool routes to the FactSet Supply Chain API relationships endpoint:

RELATIONSHIPS ENDPOINT (/relationships):

• Use Case: Retrieve business relationship networks for companies
• Returns: Related entities with product overlap metrics and direction indicators
• Best For: Competitive analysis, supply chain mapping, partner identification
• Example: "Who are Apple's competitors?" or "Show me Microsoft's suppliers"
• Max IDs: 500 companies per request

RELATIONSHIP TYPES:

COMPETITORS:

• Companies disclosed as competitors in filings
• Entities operating in similar markets or product categories
• Best for: Competitive landscape analysis, market positioning
• Example: "Who competes with Apple in smartphones?"

CUSTOMERS:

• Companies that purchase products/services from source company
• Major clients and revenue-generating relationships
• Best for: Revenue concentration analysis, customer dependency assessment
• Example: "Who are Intel's major customers?"

SUPPLIERS:

• Companies providing goods, services, or raw materials
• Upstream supply chain dependencies
• Best for: Supply chain risk analysis, procurement intelligence
• Example: "Who supplies components to Tesla?"

PARTNERS:

• Strategic business relationships including joint ventures
• Equity investments and collaborative arrangements
• Best for: Partnership analysis, strategic alliance mapping
• Example: "Who are Amazon's business partners?"

FILTERING OPTIONS:

COMPANY TYPE:

• PUBLIC_COMPANIES_ONLY (default): Focus on publicly traded entities
• PRIVATE_COMPANIES_ONLY: Private company relationships only
• ALL: Complete network including both public and private

RELATIONSHIP DIRECTION:

• ALL (default): Complete bidirectional relationships
• DIRECT: Only where source company disclosed the relationship
• REVERSE: Only where target company disclosed the relationship

RELATIONSHIP DIRECTION (CRITICAL UNDERSTANDING):

The relationshipDirection parameter controls whose SEC filings are used as the source:

• DIRECT: Returns relationships where the SOURCE company (ids parameter) explicitly named the competitor in THEIR OWN filings
• Example: If ids=['AAPL-US'], returns competitors that Apple mentioned in Apple's 10-K
• Use when: "Who did Apple say they compete with?"
• REVERSE: Returns relationships where the TARGET company named the source as a competitor in the target's filings
• Example: If ids=['AAPL-US'], returns companies that mentioned Apple as a competitor in THEIR filings
• Use when: "Who considers Apple a competitor?" or "Who competes with Apple?"
• ALL (default): Returns both direct and reverse relationships
• Provides the complete competitive landscape from both perspectives
• Each result includes a 'relationshipDirection' field showing the disclosure source

Key Insight:

• Direct relationships = "competitors we disclosed"
• Reverse relationships = "companies who disclosed us as their competitor"
• Mutual = Both companies disclosed each other (appears in relationshipDirection field of results)

Why This Matters: A smaller company may view Apple as a competitor (reverse), but Apple may not mention them (no direct relationship). The direction parameter lets you filter by disclosure source.

RELATIONSHIP STRENGTH METRICS:

overlappingProductCount:

• Format: "28 of 138" (overlap count / total products)
• Indicates number of shared product/service categories
• Reflects competitive product similarity ONLY — NOT a measure of revenue, financial importance, or business significance
• Do not use to rank "top", "biggest", "most important", or "primary" suppliers/customers/partners

overlapPercentage:

• Percentage of product/service overlap
• Calculated as: (overlapping products / total products) × 100
• Reflects product/service similarity ONLY — NOT a measure of financial importance, revenue share, or strategic significance
• Do not use to rank "top", "biggest", "most important", or "primary" suppliers/customers/partners
• Relevant when the user's question explicitly asks about product similarity or competitive overlap

relationshipDirection:

• "Mutual": Both companies disclosed the relationship
• "Direct": Source company disclosed the relationship
• "Reverse": Target company disclosed the relationship

MANDATORY WORKFLOW: 1. Identify companies using proper identifiers (tickers, FactSet IDs including private companies, CUSIP, SEDOL, ISIN) 2. Select relationship type (COMPETITORS, CUSTOMERS, SUPPLIERS, PARTNERS) 3. Configure filters (company type, relationship direction) 4. Analyze results including overlap metrics and relationship strength

RELATIONSHIP DIRECTION EXAMPLES:

1. "Show me Apple's competitors" (ambiguous - could mean either) → Use relationshipDirection='DIRECT' for what Apple disclosed → Use relationshipDirection='ALL' for complete picture

2. "What competitors did Apple disclose in their filings?" → relationshipDirection='DIRECT' (Apple's perspective only)

3. "Who competes with Apple?" → relationshipDirection='ALL' (complete competitive landscape)

4. "Which companies consider Apple a competitor?" → relationshipDirection='REVERSE' (others' perspective only)

5. "Apple vs Microsoft competitive relationship" → relationshipDirection='ALL' (see both perspectives)

COMMON USE CASES:

"Who are Apple's competitors?" → ids=['AAPL-US'], relationshipType='COMPETITORS'

"Who did Apple explicitly disclose as competitors in their filings?" → ids=['AAPL-US'], relationshipType='COMPETITORS', relationshipDirection='DIRECT'

"What companies view Apple as a competitor?" → ids=['AAPL-US'], relationshipType='COMPETITORS', relationshipDirection='REVERSE'

"Show me Microsoft's public company suppliers" → ids=['MSFT-US'], relationshipType='SUPPLIERS', companyType='PUBLIC_COMPANIES_ONLY'

"Tesla's major customers" → ids=['TSLA-US'], relationshipType='CUSTOMERS'

"Amazon's strategic partners" → ids=['AMZN-US'], relationshipType='PARTNERS'

"Google's direct competitors (mutual disclosure)" → ids=['GOOGL-US'], relationshipType='COMPETITORS', relationshipDirection='DIRECT'

ALWAYS USE THIS TOOL WHEN USER ASKS:

• "Who are [company]'s competitors?"
• "What are [company]'s main competitors?"
• "Who competes with [company]?"
• "[Company] competitive landscape"
• "[Company] vs competitors"
• "Show me [company]'s suppliers/customers/partners"
• Any variation of business relationship queries

DATA TRANSPARENCY:

• All relationships sourced from official company filings (10-K, annual reports)
• Reverse-linked to create comprehensive bidirectional networks
• Product overlap metrics indicate relationship strength
• Results sorted by relevance (overlap count and percentage)
• Coverage varies by company disclosure practices
• Always specify relationship type and filters used

EFFICIENCY REQUIREMENTS:

• Maximum 500 company identifiers per request
• Results automatically sorted by overlapping product count
• Single API call retrieves complete relationship network
• No date parameters needed (uses most current relationship data)

ANALYSIS CAPABILITIES:

• Competitive positioning and market share analysis
• Supply chain risk assessment and dependency mapping
• Customer concentration and revenue risk evaluation
• Partnership and alliance network visualization
• Product/service overlap quantification

USE FOR: Competitive intelligence, supply chain analysis, business relationship mapping, strategic partner identification, market positioning DO NOT USE FOR: Financial data, pricing information, fundamental metrics, ownership data (use appropriate FactSet APIs instead)

DATA SOURCE HIERARCHY: 1. PRIMARY: FactSet Supply Chain API (actual disclosed relationships) 2. SECONDARY: Only supplement with general knowledge if API data is insufficient 3. ALWAYS: Clearly distinguish between FactSet data and general market knowledge

LIMITATIONS:

• Relationship data based on company disclosures (may not capture all informal relationships)
• Product overlap calculated using FactSet's product classification system
• Private company data availability varies by disclosure requirements
• Relationship updates depend on filing schedules and disclosure timing
• Some relationships may be one-directional (only disclosed by one party)

RETURNS:

• Structured JSON responses with relationship data
• Always includes: entityId, companyName, overlappingProductCount, overlapPercentage,

relationshipDirection, requestId

• Error messages with detailed validation feedback

ERROR HANDLING:

• Invalid parameter combinations → Detailed error message
• Missing required parameters → Error with reminder
• Invalid identifiers → List of unrecognized IDs
• ID limit violations → Limit specification

FactSet Terms and Conditions API Tool

• Fixed Income Securities Data.

WHEN TO USE THIS TOOL: This tool should be used for:

• ANY query about Fixed Income security terms, conditions, or detailed attributes
• Questions about coupon schedules, redemption prices, or convertible features
• Issue size, agent details, lead underwriters, and use of proceeds information
• Covenant details for Fixed Income corporate, government & agency securities
• NOTE: For bond price data (BID/MID/ASK), use the FactSet_BondPrices tool instead.

COVERAGE: The FactSet Terms & Conditions API exposes comprehensive data for Fixed Income Corporate, Government & Agency securities globally. Covers descriptive data on issue level (offering details, redemption information, coupon schedules) and issuer level data.

SUPPORTED ENDPOINTS:

The tool intelligently routes to the appropriate endpoint based on the data_type parameter:

1. Issue Size (data_type='issue_size')

• Returns: Amount Outstanding, Currency, Changes, Type
• Use when: Need current or historical issue size data

2. Coupon History (data_type='coupon_history')

• Returns: Historical coupon information, rates, effective dates
• Use when: Need coupon accrual dates, payment dates, coupon structure

3. Coupon Schedules (data_type='coupon_schedules')

• Returns: Coupon effective dates and rates
• Use when: Need scheduled coupon payment information

4. Covenant Details (data_type='covenant_details')

• Returns: Covenant types and descriptions (financial ratios, restrictions)
• Use when: Need covenant information for bond analysis

5. Redemption Prices (data_type='redemption_prices')

• Returns: Call, Put, and Sinking Fund redemption prices
• Parameters: categories can be 'ALL', 'CALL', 'PUT', or 'SF'
• Use when: Need redemption schedule and pricing information

6. Agents (data_type='agents')

• Returns: Agent names, entity IDs, types (trustees, paying agents, etc.)
• Use when: Need agent or guarantor information

7. Lead Underwriters (data_type='lead_underwriters')

• Returns: Lead underwriter entity IDs and details
• Use when: Need underwriter information for securities

8. Use of Proceeds (data_type='use_of_proceeds')

• Returns: Use of proceeds descriptions and details
• Use when: Need information about how proceeds were used

9. Convertible Details (data_type='convertible_details')

• Returns: Convertible currency, dates, ratios, payment forms, price methods
• Use when: Need convertible feature information

10. Convertible History (data_type='convertible_history')

• Returns: Convertible price and ratio history with effective dates
• Use when: Need historical changes to convertible features

11. Convertible Triggers (data_type='convertible_triggers')

• Returns: Trigger events, descriptions, and trigger IDs
• Use when: Need convertible trigger event information

SECURITY IDENTIFIERS:

• Supported formats: CUSIP, SEDOL, ISIN, FactSet Security Permanent Identifier (-S)
• Maximum: 250 identifiers per request
• Examples: 30231GBJ, 88579EAA, QB23QR-S

INPUT PARAMETERS:

• ids (required): Security identifiers (list or comma-separated string)
• data_type (required): The endpoint to use (see endpoints above)
• categories (optional): Filter results by category
• For Redemption Prices: 'ALL' (default), 'CALL', 'PUT', 'SF'
• For Terms and Conditions: 'SECURITY_DETAILS', 'COUPON_DETAILS', 'CONVERTIBLE_FEATURES', 'REDEMPTION_OPTIONS'
• fields (optional): Specific fields to return (only for coupon_schedules endpoint)

COMMON USE CASES:

"What is the coupon schedule for security 30231GBJ?" → ids=['30231GBJ'], data_type='coupon_schedules'

"Show me the redemption prices for 88579EAA including Call options" → ids=['88579EAA'], data_type='redemption_prices', categories=['CALL']

"Get issue size data for security W71259AA" → ids=['W71259AA'], data_type='issue_size'

"What are the covenants for security 00107TAA?" → ids=['00107TAA'], data_type='covenant_details'

"Show convertible triggers for security 90138VAA" → ids=['90138VAA'], data_type='convertible_triggers'

"Get agent information for multiple securities" → ids=['30231GBJ', '88579EAA'], data_type='agents'

RETURNED DATA:

• Core fields: requestId (input security), fsymId (FactSet Security ID)
• Endpoint-specific fields vary based on data_type selected
• All numeric values properly typed (dates, doubles, integers)
• Arrays of related data (e.g., multiple coupon records per security)

ERROR HANDLING:

• Missing required parameter (ids or data_type) returns validation error
• Invalid data_type returns unsupported endpoint error
• Too many identifiers (>250) returns limit error
• Invalid security identifiers may return empty results

LIMITATIONS:

• Query limited to 250 securities per request
• Data not available for equity securities (Fixed Income only)
• Historical data varies by security and field
• Real-time data not available (use daily end-of-day data)

FactSet Unstructured Content Tool

• Semantic search across financial documents.

WHEN TO USE THIS TOOL:

• ANY query requiring semantic/natural language search across financial documents
• Questions like "What are companies saying about AI investment?" or "Find news about energy regulation"
• Searching EDGAR filings, StreetAccount News, or FactSet CallStreet Transcripts by topic
• Filtering financial documents by sentiment or form type
• Finding relevant document excerpts with similarity scoring

Do NOT use for structured financial data (prices, estimates, fundamentals) - use appropriate FactSet APIs instead.

DATA SOURCES:

• ALL_FILINGS
• ALL_NEWS
• ALL_TRANSCRIPTS

KEY CAPABILITIES:

• Natural language semantic search with similarity scoring (0-1 scale)
• Filter by sentiment (Negative, Neutral, Positive, Very Negative, Very Positive)
• Filter by EDGAR form types (10-K, 10-Q, 8-K, etc.)
• Filter by company identifiers (FactSet IDs, tickers)
• Control result count and sort order (by date or similarity)
• Per-source result limits via resultsBySource

MANDATORY WORKFLOW: 1. Formulate the query — TWO STRICT RULES: a. NATURAL LANGUAGE REQUIRED: Must be a complete sentence or question. Keyword phrases, comma-separated terms, or shorthand is not acceptable. b. NO EXPANSION: Include ONLY the exact topics the user literally stated. Never add related concepts, sub-themes, synonyms, or industry terms the user did not say. BAD → user said "tariffs": query='What are executives discussing about tariffs and supply chain disruptions?' GOOD → user said "tariffs": query='What are executives discussing about tariffs?' 2. Select at least one source: ALL_FILINGS, ALL_NEWS, ALL_TRANSCRIPTS (max 3) 3. Provide startDate and endDate in YYYY-MM-DD format 4. Optionally add sentiment, formTypes (ALL_FILINGS only), or ids filters 5. SET limit — MANDATORY RULE: ALWAYS pass limit=10. This is not optional. Only deviate if the user provides an explicit number (e.g., "give me 5 results", "show 20"). Vague requests like "find some", "search for", or "look up" do NOT override the default. GOOD → user said "get me a few results": limit=10 BAD → user said "get me a few results": limit=3 6. Results ranked by similarity score or date

COMMON USE CASES:

"What are companies saying about AI infrastructure?" → query='What are companies saying about AI infrastructure?', sources=['ALL_FILINGS', 'ALL_TRANSCRIPTS', 'ALL_NEWS'], startDate='2024-01-01', endDateTime='2024-12-31', limit=10

"Find 10-K filings discussing energy consumption" → query='How are companies addressing energy consumption in their operations?', sources=['ALL_FILINGS'], formTypes=['10-K'], startDate='2024-01-01', endDate='2024-12-31', limit=10

"Positive news about Apple's data center strategy" → query='What is Apple saying about its data center strategy?', sources=['ALL_NEWS', 'ALL_TRANSCRIPTS'], ids=['AAPL-US'], sentiment=['Positive'], startDate='2024-01-01', endDate='2024-12-31', limit=10

"Tariff concerns in earnings calls" → query='What are executives discussing about tariffs?', sources=['ALL_TRANSCRIPTS'], startDate='2024-01-01', endDate='2024-12-31', limit=10

RESULT STRUCTURE:

• vectorId: Unique identifier for the document chunk
• similarityScore: Relevance score (0-1, higher = more relevant)
• content: Text excerpt from the document
• headline: Document headline
• viewUrl: Link to the full source document
• REQUIRED for citation rendering
• themes: Themes associated with the document
• sentiment: Sentiment of the document
• source: ALL_FILINGS, ALL_NEWS, or ALL_TRANSCRIPTS
• ids: Related company identifiers
• limit: Always explicitly passed — MUST be 10 unless the user stated a specific number
• EDGAR-specific: formType, sectionName, sectionNumber, docType, tableText
• Transcript-specific: speakerName, speakerTitle, speakerCompanyName, financialYear, financialQuarter

CITATION LINK RENDERING:

• Each result in the response includes:
• viewUrl: Direct URL to the source document for this specific result
• headline: Document headline used as the clickable link text
• Example viewUrl: https://my.apps.factset.com/viewer-fusion/?_doc_sequence=18_doc_id=3188517-t&_doc_date=2025-02-26T20:42:21&_doc_product=FCST&_doc_docFn=UZFsdGVkX188ugKkIIsgIr76H4HbA+s6feJA0n0N/PhFIjd9LA

**CRITICAL INSTRUCTION

• SHOWING CITATION SOURCES:**

Present each result with its citation link in Markdown format. AI Client will automatically render these as clickable hyperlinks.

CRITICAL RULES:

• Use Markdown link format with bold: [headline](viewUrl)
• Make EACH result's headline a clickable link using its corresponding viewUrl
• AI Client automatically render these as clickable hyperlinks in the chat
• DO NOT show separate citation sections at the bottom
• DO NOT show raw URLs - embed them in the Markdown links
• Each result gets its own unique viewUrl