Custom Tools

Custom tools let you write your own JavaScript functions and make them available as callable tools in Agent blocks. This is useful when you need functionality that isn't covered by Sim's built-in integrations — for example, calling an internal API, performing a custom calculation, or transforming data in a specific way.

How Custom Tools Work

A custom tool has two parts:

1. Schema — A JSON definition describing the tool's name, description, and parameters (using the OpenAI function-calling format). This tells the AI agent what the tool does and what inputs it expects.
2. Code — A JavaScript function body that runs when the agent calls the tool. Parameters defined in the schema are available as variables in your code.

When an Agent block has access to a custom tool, the AI model decides when to call it based on the schema description and the conversation context — just like built-in tools.

Creating a Custom Tool

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "The city name"
        },
        "units": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"],
          "description": "Temperature units"
        }
      },
      "required": ["city"]
    }
  }
}

const response = await fetch(
  `https://api.openweathermap.org/data/2.5/weather?q=${city}&units=${units === 'celsius' ? 'metric' : 'imperial'}&appid={{OPENWEATHER_API_KEY}}`
);

const data = await response.json();

return {
  temperature: data.main.temp,
  description: data.weather[0].description,
  humidity: data.main.humidity
};

Using Custom Tools in Workflows

Once created, custom tools appear alongside built-in tools when configuring an Agent block:

1. Open an Agent block
2. Click Add Tools
3. Find your custom tool in the tool list
4. The agent will call the tool when it determines it's relevant to the task

Code Environment

Available Features

• Async/await — Your code runs in an async context, so you can use await directly
• fetch() — Make HTTP requests to external APIs
• Node.js built-ins — Access to crypto, Buffer, and other standard modules
• Environment variables — Use {{KEY}} syntax to inject secrets

Limitations

• No npm packages — External libraries like axios or lodash are not available. Use built-in APIs instead
• Parameters by name — Schema parameters are available directly as variables (e.g., city), not via a params object

Returning Results

Return a value from your code to send it back to the agent:

const result = await fetch(`https://api.example.com/data?q=${query}`);
const data = await result.json();
return data;

The returned value becomes the tool output that the agent sees and can use in its response.

Managing Custom Tools

From Settings → Custom Tools you can:

• Search tools by name, function name, or description
• Edit any tool's schema or code
• Delete tools that are no longer needed

Permissions