Skip to main content
Tools let agents take actions—search the web, call APIs, or query databases. You control which tools are available; the agent decides when to use them.

​
Quick Start

Add tools to any run: 
from subconscious import Subconscious
import os

client = Subconscious(api_key=os.environ.get("SUBCONSCIOUS_API_KEY"))

run = client.run(
    engine="tim-gpt",
    input={
        "instructions": "Find the latest news about SpaceX",
        "tools": [
            {"type": "platform", "id": "web_search"}
        ]
    },
    options={"await_completion": True},
)

​
Platform Tools

Built-in tools hosted by Subconscious. No setup required.
IDNameDescription
web_searchGoogle SearchSearch the web for information
webpage_understandingJina ReaderExtract and summarize webpage content
parallel_searchParallel SearchPrecision search for facts from authoritative sources
parallel_extractParallel ExtractExtract specific content from a webpage
exa_searchExa SearchSemantic search for high-quality content
exa_crawlExa CrawlRetrieve full webpage content
exa_find_similarExa SimilarFind pages similar to a given URL

​
Custom Function Tools

Call your own HTTP endpoints. You host the tool; Subconscious calls it during agent execution.

​
Tool Schema

type FunctionTool = {
  type: "function";
  name: string;
  description: string;
  url: string;
  method: "POST" | "GET";
  timeout?: number; // seconds, default 30
  parameters: {
    type: "object";
    properties: Record<string, any>;
    required?: string[];
  };
  headers?: Record<string, string>;  // HTTP headers for this tool
  defaults?: Record<string, any>;    // Hidden params injected at call time
};

​
Building a Tool Server

Your tool endpoint receives POST requests with parameters as JSON and returns JSON results. 
# server.py
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class WeatherRequest(BaseModel):
    city: str
    units: str = "celsius"

@app.post("/weather")
async def get_weather(req: WeatherRequest):
    # Your logic here - call weather API, database, etc.
    return {
        "city": req.city,
        "temperature": 22,
        "units": req.units,
        "condition": "sunny"
    }

# Run with: uvicorn server:app --host 0.0.0.0 --port 8000

​
Registering with Subconscious

Once your server is running, register the tool in your run: 
tools: [
  {
    type: "function",
    name: "get_weather",
    description: "Get current weather for a city",
    url: "https://your-server.com/weather",
    method: "POST",
    timeout: 10,
    parameters: {
      type: "object",
      properties: {
        city: { type: "string", description: "City name" },
        units: { type: "string", enum: ["celsius", "fahrenheit"] },
      },
      required: ["city"],
    },
  },
];
Your endpoint must be publicly accessible. For local development, use a tunnel like ngrok or Cloudflare Tunnel.

​
Tool Headers

Add custom HTTP headers that are sent when calling your tool’s endpoint. Useful for authentication: 
{
  type: "function",
  name: "my_api",
  description: "Call my authenticated API",
  url: "https://api.example.com/endpoint",
  method: "POST",
  parameters: {
    type: "object",
    properties: {
      query: { type: "string" }
    },
    required: ["query"]
  },
  // Headers sent only when THIS tool is called
  headers: {
    "x-api-key": "your-secret-key",
    "x-custom-header": "custom-value"
  }
}
Each tool can have its own headers—they’re only sent when that specific tool’s endpoint is called.

​
Default Arguments

Inject parameter values that are hidden from the model and automatically merged at call time. Perfect for session IDs, public API keys, or other values you don’t want the model to see or generate: 
{
  type: "function",
  name: "search_database",
  description: "Search the database",
  url: "https://api.example.com/search",
  method: "POST",
  parameters: {
    type: "object",
    properties: {
      query: { type: "string", description: "Search query" },
      // Define these for validation, but they'll be hidden from the model
      sessionId: { type: "string" },
      apiKey: { type: "string" }
    },
    required: ["query"]  // Only query is required from the model
  },
  // Hidden from model, injected at call time
  defaults: {
    sessionId: "user-session-abc123",
    apiKey: "secret-api-key"
  }
}

​
MCP Tools

Connect to Model Context Protocol servers to use their tools. 
type McpTool = {
  type: "mcp";
  server: string; // MCP server URL
  name?: string; // Specific tool (omit to use all tools from server)
  auth?: {
    type: "bearer" | "api_key";
    token?: string;
    header?: string; // Header name for api_key auth
  };
};
Example: 
tools: [
  // Use all tools from an MCP server
  { type: "mcp", server: "https://mcp.example.com" },

  // Use a specific tool with auth
  {
    type: "mcp",
    server: "https://mcp.example.com",
    name: "query_database",
    auth: { type: "bearer", token: "your-token" },
  },
];

​
Saved Tools

Don’t want to pass the full tool schema every time? Save tool configurations in the dashboard and reference them by name.
1

Create the tool

Go to subconscious.dev/platform/tools and create a new tool with your endpoint URL, parameters, and description.
2

Reference by ID

Use your saved tool’s API name in requests:
tools: [
  { type: "platform", id: "my_custom_tool" }
]
Saved tools are useful when:
  • You use the same tool across multiple agents
  • You want to update configuration without changing code
  • You’re sharing tools with your team

​
Combining Tools

Agents can use multiple tools together. Give them what they need: 
tools: [
  // Platform tools for web research
  { type: "platform", id: "web_search" },
  { type: "platform", id: "webpage_understanding" },

  // Your custom API
  {
    type: "function",
    name: "save_to_database",
    description: "Save research findings to our database",
    url: "https://api.example.com/save",
    method: "POST",
    parameters: {
      type: "object",
      properties: {
        title: { type: "string" },
        content: { type: "string" },
        tags: { type: "array", items: { type: "string" } },
      },
      required: ["title", "content"],
    },
  },
];

Runs

See how tools are executed in runs

Quickstart

Build your first agent with tools