/futuresearch-python

name: futuresearch-python
description: Use when the user wants forecasts (probabilities, dates, numbers, odds) or dataset research at scale via FutureSearch.

FutureSearch Python SDK

FutureSearch turns questions about the future into forecasts, with dataset research tools around it. Use this skill when writing Python code that needs to:

> **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)

**Operations:**

• Forecast probabilities for binary questions
• Classify rows into predefined categories
• Rank/score rows based on qualitative criteria
• Deduplicate data using semantic understanding
• Merge tables using AI-powered matching
• Run AI agents over dataframe rows

Installation

Python SDK

pip install futuresearch

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

If an MCP server is available (`futuresearch_classify`, `futuresearch_rank`, 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 (dedupe → merge → research)
• 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 18 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_agent

Run web research agents on each row.

Parameters:
- task: (required) Natural language description of research task
- artifact_id: Artifact ID (UUID) from upload_data or request_upload_url
- data: Inline data as a list of row objects
- response_schema: (optional) JSON schema for per-row agent response
- session_id: (optional) Session UUID to resume
- session_name: (optional) Name for a new session

futuresearch_single_agent

Run a single research agent on one input (no CSV needed).

Parameters:
- task: (required) Natural language task for the agent
- input_data: (optional) Context as key-value pairs (e.g. {"company": "Acme"})
- response_schema: (optional) JSON schema for the agent response
- session_id: (optional) Session UUID to resume
- session_name: (optional) Name for a new session

futuresearch_rank

Score and sort rows based on qualitative criteria.

Parameters:
- task: (required) Natural language instructions for scoring a single row
- field_name: (required) Name of the score field to add
- artifact_id: Artifact ID (UUID) from upload_data or request_upload_url
- data: Inline data as a list of row objects
- field_type: (optional) "float" (default), "int", "str", or "bool"
- ascending_order: (optional) Sort ascending (default: true)
- response_schema: (optional) JSON schema for the response model
- session_id / session_name: (optional)

futuresearch_dedupe

Remove duplicate rows using semantic equivalence.

Parameters:
- equivalence_relation: (required) Natural language description of what makes rows duplicates
- artifact_id: Artifact ID (UUID) from upload_data or request_upload_url
- data: Inline data as a list of row objects
- session_id / session_name: (optional)

futuresearch_merge

Join two tables using intelligent entity matching (LEFT JOIN semantics).

Parameters:
- task: (required) Natural language description of how to match rows
- left_artifact_id / left_data: (required, exactly one) Left table — the table being enriched (all rows kept)
- right_artifact_id / right_data: (required, exactly one) Right table — lookup/reference (columns appended to matches)
- merge_on_left: (optional) Only set if you expect exact string matches or want to draw agent attention to a column
- merge_on_right: (optional) Same as merge_on_left for right table
- relationship_type: (optional) "many_to_one" (default), "one_to_one", "one_to_many", "many_to_many"
- use_web_search: (optional) "auto" (default), "yes", or "no"
- session_id / session_name: (optional)

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) Batch-level context for all questions
- effort_level: (optional) "low" or "high" (default; required for categorical/thresholded and for any conditional forecast)
- 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