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},
)

​
Simple Search Tools

Use these tools to get started quickly in our playground or with our API. For example, pass in the tools input: { type: 'platform', id: 'fast_search' }.
Tool NameAPI NameDescription
Fast Searchfast_searchExtremely fast search for simple factual lookups
Web Searchweb_searchComprehensive web search for detailed research
Fresh Searchfresh_searchSearch the web for content from the last 7 days
Page Readerpage_readerExtract content from a specific webpage URL
Find Similarfind_similarFind similar links to a given URL
People Searchpeople_searchSearch for people, profiles, and bios
Company Searchcompany_searchSearch for companies, funding info, and business details
News Searchnews_searchSearch for news articles and press coverage
Tweet Searchtweet_searchSearch for tweets and Twitter/X discussions
Research Paper Searchresearch_paper_searchSearch for academic research papers and studies
Google Searchgoogle_searchSearch the web using Google

​
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: "page_reader" },

  // 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