Skip to main content
Agents rely on two key inputs: goals and tools. Tools are APIs you expose to the system to accomplish specific tasks, anything from querying a database to triggering a workflow. You host and manage the tool, and give our system permission to call it. Our runtime handles the rest. It routes tool calls intelligently during agent execution, manages inputs and outputs, and ensures the agent learns how and when to use each tool effectively. You just define the interface, we take care of integrating it into the agent’s reasoning process. Use these docs to make sure you’re hosting your tools correctly and using them properly with our API.

​
Tool Definition

All tools in Subconscious follow a consistent structure defined by these types: 
export type Tool = {
  type: 'function'; // 'mcp' coming soon;
  name: string;
  description: string;
  url: string;
  method: 'POST' | 'GET';
  timeout: number;
  parameters: Parameters;
};

export type Parameters = {
  type: 'object';
  properties: Record<string, any>;
  required: string[];
  additionalProperties: boolean;
};

​
Tool Properties

  • type: Either 'function' for custom tools or 'mcp' for Model Context Protocol tools
  • name: Unique identifier for the tool
  • description: Human-readable description of what the tool does
  • url: Endpoint URL where the tool is hosted
  • method: HTTP method used to call the tool ('POST' or 'GET')
  • timeout: Maximum time in milliseconds to wait for tool execution
  • parameters: JSON Schema definition of the tool’s input parameters

​
Three Ways to Use Tools with Subconscious

Subconscious provides three flexible approaches to integrate tools with your AI agents.
  • Schema Defined Tools: Sent complete tool schema during an API request
  • Saved Tools: Save tool schemas in the platform tools dashboard for simpler API calls
  • Hosted Tools: Two tools from Subconscious to get you started

​
1. Schema Defined Tools

Pass tool schemas directly to the API for every interaction. This approach gives you complete control but requires you to self-host these tools. Best for: Custom tools, one-off integrations, or when you need full control over tool implementation. 

tools: [
  {
    "type": "function",
    "name": "MyTool",
    "description": "A custom tool for specific functionality",
    "url": "http://your-host/call_tool",
    "method": "POST",
    "timeout": 10,
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "The input query"
        }
      },
      "required": ["query"],
      "additionalProperties": false
    }
  }
]

​
2. Saved Tools

Save your tool specifications to simplify API calls. Once saved, you can reference tools by name in your requests. Best for: Frequently used tools, team collaboration, or when you want to reduce API payload size. 
// First, save your tool specification
// Then use it in subsequent calls
tools: [
  {
    type: "your_tool_name"
  }
]

​
3. Subconscious Hosted Tools

We host these tools for you and they’re available to use freely with your models.
Tool NameAPI NameDescription
Web Searchweb_searchSearch the web for information.
Webpage Understandingwebpage_understandingSummarizes key information on web pages and suggests how to use in further searches (use with Web Search).
Best for: Common use cases, rapid prototyping, or when you don’t want to manage tool infrastructure. 
// Web search tool
tools: [
  {
    type: "web_search"
  }
]

// Webpage understanding tool
tools: [
  {
    type: "webpage_understanding"
  }
]

// Use both tools together for comprehensive web research
tools: [
  {
    type: "web_search"
  },
  {
    type: "webpage_understanding"
  }
]

​
Getting Started

Choose the approach that best fits your needs:
  • Schema Defined Tools: For complete customization and control
  • Saved Tools: For simplified, reusable tool management
  • Subconscious Hosted Tools: For quick setup with common functionality
Each approach integrates seamlessly with Subconscious’s AI agents, providing the tools your agents need to perform complex tasks and access external data sources.
⌘I