Custom Tools

What Are Custom Tools?

Custom tools are user-defined functions that agents can call during a task. Unlike skill prompts, which guide the AI model's reasoning, custom tools execute actual code or call external APIs and return structured results. They bridge OpenAnalyst's agents with your own internal systems, proprietary algorithms, and external data sources.

A custom tool is defined by its name, a description the agent uses to decide when to call it, an input schema, an execution endpoint (a URL that OpenAnalyst calls with the tool inputs), and an output schema.

Tool Definition Format

Tools are defined using a JSON schema-based format. The definition is submitted via the API or through the custom tools editor inSettings > Custom Tools.

{
  "name": "calculate_ltv",
  "description": "Calculate the predicted lifetime value for a customer segment based on cohort data. Call this when the user asks about LTV, customer value, or retention economics.",
  "input_schema": {
    "type": "object",
    "properties": {
      "segment_id": {
        "type": "string",
        "description": "The identifier of the customer segment."
      },
      "time_horizon_months": {
        "type": "integer",
        "description": "Number of months to project LTV over.",
        "default": 24
      }
    },
    "required": ["segment_id"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "ltv": { "type": "number" },
      "confidence_interval": {
        "type": "object",
        "properties": {
          "lower": { "type": "number" },
          "upper": { "type": "number" }
        }
      }
    }
  },
  "endpoint": "https://your-service.internal/api/ltv",
  "auth": {
    "type": "bearer",
    "token_secret": "YOUR_SECRET_NAME"
  }
}

Input and Output Schemas

Schemas use JSON Schema (Draft 7). Input schemas define the parameters the agent will populate when calling the tool. Output schemas tell OpenAnalyst how to interpret the response and how to present it to the agent for further reasoning.

Keep output schemas as flat and typed as possible. Agents handle structured outputs (numbers, strings, arrays of objects) more reliably than deeply nested or loosely typed responses.

Registering Tools with Agents

Once a tool is saved, it must be explicitly enabled on the agents that should have access to it. This prevents tools from being invoked in contexts where they are not appropriate and limits the blast radius of misconfigured tools.

1. Open the agent editor for the agent that should use the tool.
2. Navigate to the Custom Tools tab.
3. Find the tool in the list and toggle it on.
4. Optionally set a maximum number of calls per conversation to limit tool usage in single sessions.
5. Save the agent configuration.

Sharing Tools Across the Workspace

Custom tools are workspace-scoped by default — any Admin or Owner can see and manage them. You can mark a tool as private to restrict visibility to yourself, or as shared to make it available for other workspace members to attach to their own agents.

Shared tools include a usage log showing which agents called the tool, when, and what inputs were passed (subject to data retention settings). This log is useful for debugging and for auditing tool usage patterns.

Tool Versioning

OpenAnalyst tracks versions of tool definitions. When you update a tool's input schema, endpoint, or description, a new version is created and the previous version is archived. Agents pin to the tool version that was active when they were last saved, so updates to a tool do not automatically propagate to all agents — you must update each agent's tool reference to use the new version.

// Referencing a specific tool version via API
GET /api/v1/tools/calculate_ltv?version=3

// Updating an agent to use the latest version
PATCH /api/v1/agents/agent_abc123
{
  "tools": [
    { "tool_id": "calculate_ltv", "version": "latest" }
  ]
}