/futuresearch-python

name: futuresearch-python
description: Use when the user wants a FutureSearch forecast: the probability, date or number for a question about the future, or the outcomes of a decision they, their company, or someone else is facing (pricing, hiring, funding, launch timing, policy). Also covers web research across the rows of a table.

FutureSearch Python SDK

FutureSearch forecasts questions about the future, including the outcomes of decisions. Use this skill when writing Python code or calling MCP tools that need to:

**Operations:**

• Forecast the outcomes of a decision, yours or someone else's: the same outcome under each option
• Forecast probabilities, numbers, dates, and categories for questions about the future
• Research one question with a team of parallel agents
• Run AI agents over dataframe rows

> **Documentation**: For detailed guides, case studies, and API reference, see: > - Docs site: [futuresearch.ai/docs](https://futuresearch.ai/docs) > - GitHub: [github.com/futuresearch/futuresearch-python](https://github.com/futuresearch/futuresearch-python)

Installation

Python SDK

pip install futuresearch

MCP Server (for Claude Code, Claude Desktop, Cursor, etc.)

If an MCP server is available (`futuresearch_forecast`, `futuresearch_decision`, etc. tools), you can use it directly without writing Python code. The MCP server operates on uploaded data (via artifact IDs or inline JSON).

To install the MCP server, add to your MCP config:

{
  "mcpServers": {
    "futuresearch": {
      "type": "http",
      "url": "https://mcp.futuresearch.ai/mcp"
    }
  }
}

Config file locations:

• **Claude Code**: `~/.claude.json` (user) or `.mcp.json` (project)
• **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
• **Cursor**: `~/.cursor/mcp.json`

When to Use SDK vs MCP

**Use MCP tools** when:

• Quick one-off operations on CSV files
• User wants direct results without writing code
• Simple lookups and enrichments

**Use Python SDK** when:

• Complex multi-step workflows (research → forecast → decision)
• Custom data transformations
• Integration with existing Python scripts
• Full control over execution and intermediate results

---

MCP Server Tools

If you have the FutureSearch MCP server configured, these tools are available. All data processing tools accept input via `artifact_id` (from upload_data or request_upload_url) or `data` (inline JSON rows). Provide exactly one.

Core Operations

futuresearch_forecast

Forecast questions about the future. Five outcome types: binary probabilities, numeric percentiles, date percentiles, categorical (one probability per listed outcome), and thresholded (one probability per listed threshold condition). Any of them can be made conditional on a stated intervention by supplying a condition (see "Conditional forecasting" below).

Parameters:
- artifact_id: Artifact ID (UUID) from upload_data or request_upload_url
- data: Inline data as a list of row objects (must include "question" column)
- forecast_type: "binary", "numeric", "date", "categorical", or "thresholded" (always the OUTCOME type)
- context: (optional) What is true for the whole call: facts about who is deciding
  and their situation, and any instructions that apply to every row
- effort_level: (optional) "low" or "high" (default; required for categorical/thresholded and for any conditional forecast)
- batch_size: (optional) Rows researched together per forecasting agent — see "Batching related questions" below
- output_field: Name of the forecast quantity (required for numeric/date)
- units: Units of the forecast quantity (required for numeric)
- categories_field: Column with each row's outcomes as a JSON array of strings (required for categorical)
- thresholds_field: Column with each row's threshold conditions as a JSON array (required for thresholded)
- condition: (optional) Single shared condition string mapped over every row, making the forecast conditional on it
- condition_field: (optional) Name of a per-row column holding each row's own condition (mutually exclusive with condition)
- session_id / session_name: (optional)

**Batching related questions.** Decide by research overlap, not row count. When the rows are variants of one subject — the same entity, product, market, or scenario asked across several horizons, metrics, or cases (e.g. three games x {first-month revenue, year-one revenue}) — the research is shared, so set `batch_size` to the number of rows (max 8 at high effort): the forecasting agents research the batch once and still forecast and refine each row independently, at roughly half the cost of unbatched research. When the rows are independent subjects (six unrelated geopolitics questions), leave `batch_size` unset so each row earns its own research pass — batching unrelated rows saves money but starves each question of research depth. For a mixed table, split it and submit the related cluster batched and the rest per-row. At high effort, batching requires a plain unconditional binary/numeric/date forecast (categorical/thresholded, decision, and conditional forecasts always run per-row). Tell the user which mode you chose and roughly what it changes in cost, so an expensive per-row run is a choice they saw, not a surprise.

futuresearch_decision

Forecast the outcomes of a decision somebody is facing: the user's, their company's, a competitor's, a regulator's, a government's. Each option gets the same outcome forecast. Use this whenever the "if" is something someone chooses to do, rather than something that happens to the world. Include not acting as an option unless it is ruled out, and prefer a date or a quantity to a cutoff: ask "when does it ship" rather than "does it ship by June".

The outcome under each alternative can be a probability, a number, or a date (`forecast_type` `binary` / `numeric` / `date`, as in futuresearch_forecast).

Parameters:
- artifact_