Custom Tools

Tools extend what your agents can do — call external APIs, reference documentation, or run code in a secure sandbox. This guide covers each tool type, how to configure them, and best practices.

Tool Types

Cognova supports three types of custom tools:

Every agent also has access to built-in tools (tasks, memory, files, code execution) which are always available without configuration.

HTTP Tools

HTTP tools let your agent call external APIs. You define the endpoint, and Cognova handles authentication, input mapping, and response parsing.

Definition

Input Interpolation

Use {{input.fieldName}} in your URL, headers, or body to inject values from the agent's tool call. The field names must match your inputSchema.

https://api.example.com/search?q={{input.query}}&limit={{input.limit}}

Secret References

Use {{secret:NAME}} to reference encrypted workspace secrets. Secrets are resolved at execution time and never exposed in exports.

Authorization: Bearer {{secret:API_KEY}}

Add secrets in Settings → Secrets before using them in tools. The tool detail page will warn you if any referenced secrets are missing.

Response Transform

Extract a specific value from the API response using dot-path notation:

• data.results — returns the results array from { data: { results: [...] } }
• items[0].name — returns the first item's name
• Leave empty to return the full response

Example: Weather API

Name: get_weatherMethod: GETURL: https://api.weatherapi.com/v1/current.json?key={{secret:WEATHER_KEY}}&q={{input.location}}Response Transform: currentInput Schema:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "City name or coordinates"
    }
  },
  "required": ["location"]
}

Security

• URLs are validated against private IP ranges (10.x, 172.x, 192.168.x, localhost) to prevent SSRF attacks
• Requests have a 30-second timeout
• Response bodies are truncated at 50 KB

Knowledge Tools

Knowledge tools provide agents with reference documentation they can look up during conversations. Unlike knowledge files (which are searched automatically), knowledge tools are invoked explicitly by the agent when it needs specific information.

Definition

When to Use Knowledge vs Knowledge Files

• Knowledge files (uploaded in the Knowledge section) are automatically searched based on conversation context
• Knowledge tools are explicitly invoked by the agent and return the full content — useful for structured reference material like API specs, coding standards, or step-by-step procedures

Example: Code Style Guide

Name: code_style_guideContent:

# Code Style Rules

## Naming
- Use camelCase for variables and functions
- Use PascalCase for classes and components
- Use UPPER_SNAKE_CASE for constants

## Formatting
- 2-space indentation
- No semicolons
- Single quotes for strings

E2B Sandbox Tools

Sandbox tools execute custom code in a secure, isolated E2B environment. The code runs in a container with network access and can install packages.

Definition

Accessing Input

Your code receives agent input via the TOOL_INPUT variable, which is a parsed dictionary/object:

Python:

# TOOL_INPUT is automatically available as a dict
name = TOOL_INPUT.get("name", "World")
print(f"Hello, {name}!")

JavaScript:

// TOOL_INPUT is automatically available as an object
const name = TOOL_INPUT.name || "World";
console.log(`Hello, ${name}!`);

Output

• Whatever your code prints to stdout is returned to the agent
• stderr is included if present
• Output is truncated at 50 KB
• Execution cost is logged at $0.0001 per second

Example: CSV Analyzer

Name: analyze_csvLanguage: pythonPackages: pandasCode:

import pandas as pd
import io

csv_data = TOOL_INPUT.get("csv_data", "")
df = pd.read_csv(io.StringIO(csv_data))

print(f"Rows: {df.shape[0]}, Columns: {df.shape[1]}")
print(f"\nColumns: {', '.join(df.columns)}")
print(f"\nSummary:\n{df.describe()}")

Input Schema:

{
  "type": "object",
  "properties": {
    "csv_data": {
      "type": "string",
      "description": "Raw CSV data to analyze"
    }
  },
  "required": ["csv_data"]
}

Input Schema

Every tool requires an inputSchema that tells the agent what parameters to provide. This is a standard JSON Schema object.

Structure

{
  "type": "object",
  "properties": {
    "paramName": {
      "type": "string",
      "description": "What this parameter is for"
    },
    "count": {
      "type": "number",
      "description": "How many results to return"
    }
  },
  "required": ["paramName"]
}

Supported types: string, number, integer, boolean, array, object.

The description field is important — it tells the AI model what to put in each parameter. Be specific.

Import & Export

Tools can be exported as JSON and imported into other workspaces.

Export

Click Export on any custom tool's detail page. The exported JSON contains the full tool definition with secret references preserved as {{secret:NAME}} placeholders (actual secret values are never included).

Import

Click Import on the tools list page and select a .json file. If the tool references secrets that don't exist in your workspace, you'll see a warning listing the missing secrets.

Export Format

{
  "toolType": "http",
  "name": "get_weather",
  "description": "Fetch current weather for a location",
  "version": "1.0",
  "definition": {
    "method": "GET",
    "url": "https://api.weatherapi.com/v1/current.json?key={{secret:WEATHER_KEY}}&q={{input.location}}",
    "responseTransform": "current",
    "inputSchema": {
      "type": "object",
      "properties": {
        "location": { "type": "string", "description": "City name" }
      },
      "required": ["location"]
    }
  }
}

Attaching Tools to Agents

After creating a tool, attach it to one or more agents:

1. Go to Agents → select an agent
2. Scroll to the Tools section
3. Click Add Tool and select from your workspace tools
4. Save the agent

Each agent only uses tools explicitly attached to it (plus built-in tools which are always available).

Built-in Tools

Every agent automatically has access to these tools without any configuration:

Built-in tools cannot be disabled, edited, or exported. They appear in the Built-in tab on the Tools page.