> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.alfa.boosted.ai/alfa/guides/build-with-alfa/knowledge-base/tool-calls/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alfa.boosted.ai/_mcp/server.

# Alfa Tool Examples

> Learn about Alfa's specialized tools for controlling inputs, operations, and outputs

## Understanding Alfa Tools

Alfa agents use specialized tools to execute the steps in your prompts. These tools provide fine-grained control over three key aspects of the agent's work:

1. **Inputs** - Select and retrieve data from various sources
2. **Operations** - Process and analyze the data
3. **Outputs** - Format and present the results

This guide provides examples of some of our most powerful tools and how to use them in your prompts.

> **Tip**
>
> Simply reference these tools in natural language within your prompts. For example: "Use websearch to find recent information on Apple, then use Text to Table to extract all product launches and dates."

## Input Tools

Input tools help you select and retrieve data from various sources, including financial databases, web content, news, and custom documents.

### Web Intelligence

#### Websearch

**Description:** Search the web for information on any topic.

**When to use it:** When you need general information from the web that isn't necessarily stock-specific.

**Example use case:** "Find information about recent inflation trends."

**Key parameters:**

* `queries`: List of search terms you want to look up
* `urls`: Optional specific web addresses to include in your search
* `date_range`: Optional timeframe to limit your search results

**Tips:**

* Use specific, targeted queries for better results
* Results will be automatically summarized for readability
* Can be used with or without specific URLs

#### Crawl URL

**Description:** Extract text content from specific web pages.

**When to use it:** When you want to analyze information from particular web pages you already know about.

**Example use case:** "Read the content of Apple's latest press release at \[specific URL]."

**Key parameters:**

* `urls`: Full web addresses of the pages you want to extract
* `queries`: Optional additional search terms to find related content on the same site

**Tips:**

* Always include the complete URL including domain and routing
* Use this when you want content from specific pages you already know
* Results will be automatically processed and summarized

### News & Information

#### Get All News Developments on Companies

**Description:** Retrieve news events and developments about specific companies.

**When to use it:** When you want to understand significant news events affecting particular stocks.

**Example use case:** "What major news has affected Microsoft in the past month?"

**Key parameters:**

* `stock_ids`: The companies you want news about
* `date_range`: Timeframe for the news (defaults to the last week)

**Tips:**

* Provides organized news events rather than just articles
* Use for a high-level view of important company developments
* Cannot be used for future dates - only past and present news

### Financial Data

#### Get Company Statistic Data

**Description:** Retrieve financial and statistical data for companies.

**When to use it:** When you need specific metrics or financial data for stocks.

**Example use case:** "What's the P/E ratio for Tesla compared to other automakers?"

**Key parameters:**

* `statistic_reference`: The metric to retrieve (e.g., "P/E Ratio", "Revenue")
* `stock_ids`: Stocks to analyze
* `date_range`: Optional timeframe for analysis
* `is_time_series`: Whether to return a series of values over time
* `target_currency`: Optional currency conversion

**Tips:**

* Can handle simple and complex financial metrics
* Supports time series for trend analysis
* Can calculate derived statistics (ratios, growth rates, etc.)
* Very flexible with natural language descriptions of statistics

#### Get Macro Statistic Data

**Description:** Retrieve economic and market-wide statistical data.

**When to use it:** When you need data on broad economic indicators.

**Example use case:** "Show me how interest rates have changed over the past year."

**Key parameters:**

* `statistic_reference`: The metric to retrieve (e.g., "Interest Rates", "Inflation")
* `date_range`: Optional timeframe for analysis

**Tips:**

* Works with macroeconomic indicators not tied to specific stocks
* Can show time series for trend analysis
* Useful for economic context in investment decisions
* Examples include interest rates, inflation, unemployment, GDP

#### Get Stock Real-Time Prices

**Description:** Get current market prices for stocks.

**When to use it:** When you need the most up-to-date price information.

**Example use case:** "What's the current price of Amazon stock?"

**Key parameters:**

* `stock_ids`: Stocks to get prices for

**Tips:**

* Returns the most recent available price
* Shows intraday/real-time prices during market hours
* Only shows current prices - use statistics tool for historical prices
* Cannot be used for calculations - use statistics tool for that

#### Get Earnings Call Transcripts

**Description:** Retrieve full transcripts of company earnings calls.

**When to use it:** When you need complete, verbatim records of earnings calls.

**Example use case:** "Get me the full transcript of Tesla's latest earnings call."

**Key parameters:**

* `stock_ids`: Companies to get earnings call transcripts for
* `date_range`: Timeframe for the earnings calls

**Tips:**

* Returns complete, unabridged transcripts
* Use only when complete transcripts are explicitly requested
* Great for searching specific phrases or detailed analysis
* Cannot find documents from the future
* Defaults to last quarter if no date range specified

#### Get Earnings Call Summaries

**Description:** Retrieve condensed summaries of company earnings calls.

**When to use it:** When you need the key points from earnings calls without all the details.

**Example use case:** "Summarize Apple's last earnings call."

**Key parameters:**

* `stock_ids`: Companies to get earnings call summaries for
* `date_range`: Timeframe for the earnings calls

**Tips:**

* Returns concise summaries instead of full transcripts
* Default tool for earnings call information
* More efficient than full transcripts for general understanding
* Cannot find documents from the future
* Defaults to last quarter if no date range specified

#### Retrieve Provisioned Broker Research

**Description:** Access professional research reports about companies.

**When to use it:** When you need in-depth professional analysis from financial analysts.

**Example use case:** "Find research reports about Nvidia's AI strategy."

**Key parameters:**

* `stock_ids`: Companies to get research for
* `date_range`: Timeframe for the research

**Tips:**

* Provides access to professional broker (sell-side) research
* Contains detailed analysis beyond news or company statements
* Cannot find documents from the future
* Only use when specifically asked for research documents

#### Company Filings

**Description:** Retrieve official regulatory filings like SEC documents.

**When to use it:** When you need specific types of regulatory filings.

**Example use case:** "Find all 8-K filings for Tesla from last year."

**Key parameters:**

* `stock_ids`: Companies to get filings for
* `form_types`: Types of filings to retrieve
* `date_range`: Timeframe for the filings
* `use_full_text`: Whether to get complete documents

**Tips:**

* Must be used after Filings Type Lookup tool
* Retrieves specific filing types (10-K, 10-Q, 8-K, etc.)
* Set use\_full\_text=True for complete filing text
* Cannot find documents from the future
* Results should be summarized, not shown directly

## Operation Tools

Operation tools help you process, analyze, and extract insights from the data you've collected using input tools.

### Analysis & Comparison

#### Get Year Over Year Statistic

**Description:** Calculate the year-over-year percentage change for a specific statistic.

**When to use it:** When you need to see how a metric has changed compared to the same period last year.

**Example use case:** "What's the year-over-year revenue growth for Apple?"

**Key parameters:**

* `statistic_reference`: The metric to analyze (e.g., "Revenue")
* `stock_ids`: Stocks to analyze
* `date_range`: Optional timeframe for analysis
* `is_time_series`: Whether to return a series of values over time
* `target_currency`: Optional currency conversion

**Tips:**

* Shows percentage change from previous year's value
* Also known as YoY or year-on-year change
* Use for trend analysis and growth evaluation

#### Get Expected Revenue Growth

**Description:** Analyze future revenue growth expectations for stocks.

**When to use it:** When you want to understand analysts' expectations for future growth.

**Example use case:** "Which technology companies have the highest expected revenue growth?"

**Key parameters:**

* `stocks`: Stocks to analyze
* `num_quarters`: How many future quarters to look ahead
* `mode`: Whether to check "earnings" or "revenue" expectations

**Tips:**

* Shows expected percentage growth based on analyst forecasts
* Can analyze either revenue or earnings expectations
* Compares actual past figures with future estimates
* Useful for forward-looking investment decisions

#### Idea Brainstorm

**Description:** Generate insights, themes, or patterns from text data.

**When to use it:** When you want to identify patterns or trends in information.

**Example use case:** "What are the key themes in recent quarterly reports for tech companies?"

**Key parameters:**

* `idea_definition`: Description of the type of insights you're looking for
* `texts`: Information to analyze
* `max_ideas`: Maximum number of ideas to generate
* `format_instructions`: Optional guidance on output format

**Tips:**

* Can identify patterns, themes, trends, events, policies, etc.
* Provides descriptions and supporting evidence for each idea
* Useful for thematic analysis and trend identification
* Great for brainstorming investment themes or macroeconomic patterns

#### Answer Question with Text Data

**Description:** Extract specific answers from text information.

**When to use it:** When you have a specific question that can be answered from text data.

**Example use case:** "What countries does Coca-Cola operate in according to their latest annual report?"

**Key parameters:**

* `question`: The specific question to answer
* `texts`: Information to search for the answer

**Tips:**

* Focuses on finding precise answers rather than summarizing
* Good for factual questions with definitive answers
* More targeted than general summarization
* Uses relevance filtering to find pertinent information

### Data Transformation

#### Transform Table

**Description:** Perform custom operations on tables of data.

**When to use it:** When you need to sort, filter, rank, or aggregate table data.

**Example use case:** "Rank these stocks by market cap and show only those above \$10 billion."

**Key parameters:**

* `input_table`: The table to transform
* `transformation_description`: Detailed description of the transformation to perform

**Tips:**

* Can perform sorting, filtering, ranking, and aggregation
* Uses natural language descriptions for transformations
* Great for complex data manipulations
* Not for time-based calculations (use statistical tools instead)

### Filter & Ranking

#### Filter Earnings: Beat or Miss

**Description:** Filter stocks based on whether they beat or missed earnings expectations.

**When to use it:** When you want to find stocks that exceeded or fell short of analyst estimates.

**Example use case:** "Show me S\&P 500 companies that beat earnings expectations last quarter."

**Key parameters:**

* `stocks`: List of stocks to filter
* `miss`: Whether to find misses (True) or beats (False)
* `quarters`: Number of quarters or specific quarters to check
* `mode`: Whether to check "earnings" or "revenue" expectations
* `filter`: Whether to filter the list or just provide beat/miss information

**Tips:**

* Can check either earnings or revenue expectations
* Can look at specific quarters or a number of recent quarters
* Provides actual figures, expected figures, and surprise percentages
* Set filter=False for analysis of specific stocks without filtering

#### Filter Stocks by Profile

**Description:** Filter and rank stocks based on their relevance to a theme or profile.

**When to use it:** When you want to find stocks related to a specific concept or theme.

**Example use case:** "Find companies that are leaders in sustainable manufacturing."

**Key parameters:**

* `stocks`: Stocks to filter
* `stock_texts`: Information about the stocks
* `profile`: Description of what you're looking for
* `complete_ranking`: Whether to fully rank the stocks
* `score_threshold`: Minimum score for inclusion
* `top_n`: Optional limit to just the top N results
* `bottom_m`: Optional inclusion of the bottom M results
* `no_filter`: Whether to include all stocks with any relevance

**Tips:**

* Provides detailed scoring and explanations for matches
* Can be used with simple string profiles or complex profiles from Generate Profiles
* Set complete\_ranking=True for "best" or "worst" matching
* Set score\_threshold to control quality cutoff (0-5 scale)
* Results include reasoning for each stock's inclusion

### Summarization

#### Summarize Text Per Idea

**Description:** Create separate summaries for each idea in a list.

**When to use it:** When you need individual text summaries for multiple ideas or themes.

**Example use case:** "For each macroeconomic trend identified, summarize how it affects tech stocks."

**Key parameters:**

* `ideas`: List of ideas to create summaries for
* `texts`: Information related to the ideas
* `topic_template`: Template for what to summarize about each idea
* `column_header`: Header for the summary column

**Tips:**

* Creates focused summaries for each idea from a brainstorming session
* Must use "IDEA" as a placeholder in the topic template
* Builds on the output of the Idea Brainstorm tool
* Results appear as a column in the ideas table

#### Get Commentary Inputs

**Description:** Collect and prepare information needed for writing market commentary.

**When to use it:** When you want to gather data for a comprehensive market analysis.

**Example use case:** "Prepare to write a commentary on recent tech sector performance."

**Key parameters:**

* `stock_ids`: Specific companies to include
* `topics`: Subjects to focus on
* `universe_name`: Market index or ETF to analyze
* `date_range`: Timeframe to analyze
* `portfolio_id`: Optional portfolio to analyze
* `macroeconomic`: Whether to include macroeconomic trends
* `theme_num`: Number of top themes to identify
* `top_n_stocks`: Number of top contributors to highlight

**Tips:**

* Essential preparation step before Write Commentary
* Gathers relevant data for comprehensive analysis
* Can focus on specific companies, sectors, markets, or portfolios
* Can include macroeconomic context when relevant

## Output Tools

Output tools help you format and present your results in the most useful way.

### Data Formatting

#### Text to Table

**Description:** Extract structured table data from text information.

**When to use it:** When you need to convert unstructured text into organized table format.

**Example use case:** "Extract a table of product launches and dates from these press releases."

**Key parameters:**

* `texts`: Information to convert to a table
* `table_description`: Description of the table to create
* `table_schema`: Column definitions for the table
* `from_description_only`: Whether to create the table purely from description

**Tips:**

* Converts unstructured information into structured tables
* Requires defining columns and their data types
* Great for extracting comparable data points from text
* Must not be used on already summarized text - use original sources

### Visualization

#### Line Graph

**Description:** Create a line chart from tabular data.

**When to use it:** When you want to visualize trends over time or continuous relationships.

**Example use case:** "Show me a graph of Apple's stock price over the past year."

**Key parameters:**

* `input_table`: Table data to visualize

**Tips:**

* Best for time series data or continuous relationships
* Good for price trends, performance metrics over time, etc.
* Requires at least 7-14 data points for a meaningful visualization
* Input must be a properly structured table

#### Pie Graph

**Description:** Create a pie chart from tabular data.

**When to use it:** When you want to show proportions of a whole.

**Example use case:** "Show the sector breakdown of my portfolio as a pie chart."

**Key parameters:**

* `input_table`: Table data to visualize

**Tips:**

* Best for showing parts of a whole
* Good for portfolio allocations, market share, etc.
* Works best with a single dimension of categorical data
* Not suitable for time series or multiple periods

#### Bar Graph

**Description:** Create a bar chart from tabular data.

**When to use it:** When you want to compare discrete categories.

**Example use case:** "Create a bar chart showing revenue by product category."

**Key parameters:**

* `input_table`: Table data to visualize

**Tips:**

* Best for comparing discrete categories
* Good for performance across categories, rankings, etc.
* Works well with multi-dimensional data in discrete buckets
* Not ideal for continuous time series data

#### Get Stock Recommendations

**Description:** Get buy/sell recommendations and analysis for stocks.

**When to use it:** When you want investment recommendations with supporting rationales.

**Example use case:** "Which tech stocks look most promising right now?"

**Key parameters:**

* `stock_ids`: Stocks to analyze
* `filter`: Whether to filter the list to recommended stocks
* `buy`: For buy (True) or sell (False) recommendations, or None for neutral analysis
* `horizon, delta_horizon, news_horizon`: Time frames for analysis
* `news_only`: Whether to focus solely on news sentiment
* `num_stocks_to_return`: Optional limit on results
* `star_rating_threshold`: Minimum rating for inclusion
* `investment_style`: Optional investment approach to consider
* `date`: Optional date for historical analysis
* `bullets`: Whether to format reasoning as bullet points

**Tips:**

* Provides scores, ratings, and detailed rationales
* Can filter to just buy or sell recommendations
* Can focus on news sentiment or include quantitative metrics
* Set filter=False for analysis without filtering
* Star ratings are on a 5-point scale

#### Competitive Analysis

**Description:** Evaluate and compare companies competing in a specific market.

**When to use it:** When you need detailed competitive positioning of companies.

**Example use case:** "Is Amazon the leader in cloud computing compared to Microsoft and Google?"

**Key parameters:**

* `prompt`: The competitive question to analyze
* `criteria`: Evaluation criteria (from Get Criteria for Competitive Analysis)
* `stocks`: Companies to compare
* `all_text_data`: Information about the companies
* `target_stock`: Optional focal company for the analysis

**Tips:**

* Provides detailed scoring and analysis across multiple criteria
* Evaluates relative market positioning
* Requires criteria, stocks, and comprehensive text data
* Best for qualitative market leadership questions
* Not for simple quantitative comparisons

> Learn about Alfa's specialized tools for controlling inputs, operations, and outputs