Creating custom tools

Write JavaScript, TypeScript, or Python code that Agents can execute during a run. Use custom tools for validation, transforms, and business logic that don’t need an external API.

Create a custom tool

1. Click Tools in the sidebar
2. Click Create Tool
3. Select Custom Code
4. Configure the tool:
   • Name: Unique identifier (e.g., calculate_discount)
   • Description: What the tool does and when to use it
   • Sandbox: Execution environment — see below
   • Parameters: Define the input schema
   • Code: Your implementation
5. Click Create

Pick a sandbox

Runtype runs your code in an isolated environment. Choose the one that matches your needs:

Cloudflare Worker runs in-process inside Runtype’s edge workers. It is the fastest option and requires no setup.

Daytona is useful when you need Python, TypeScript, or a containerized environment with configurable outbound access. To use Daytona, add your API key in Settings → Integrations. If Daytona is not configured, tool execution fails and the Agent receives a null result.

QuickJS is still available for backwards compatibility but is not recommended for new tools.

Writing tool code

Your code receives input via an injected parameters object. The shape is determined by the parameter schema you define.

JavaScript (Cloudflare Worker / QuickJS)

1
const { orderAmount, customerTier } = parameters
2
3
let discount = 0
4
if (customerTier === 'premium') {
5
  discount = orderAmount > 1000 ? 0.20 : 0.15
6
} else if (customerTier === 'standard') {
7
  discount = orderAmount > 1000 ? 0.10 : 0.05
8
}
9
10
const discountedAmount = orderAmount * (1 - discount)
11
12
return {
13
  originalAmount: orderAmount,
14
  discount: discount * 100,
15
  finalAmount: discountedAmount
16
}

Python (Daytona)

1
import json, statistics
2
3
data = parameters['numbers']
4
5
result = {
6
    'sum': sum(data),
7
    'mean': statistics.mean(data),
8
    'median': statistics.median(data),
9
    'min': min(data),
10
    'max': max(data)
11
}
12
13
print(json.dumps(result))

In Python, write the result to stdout as JSON. Runtype captures the output and parses it.

Runtime behavior

Return values. In JavaScript, the returned object is passed directly to the Agent. In Python, the last line of stdout must be valid JSON.

Exceptions. Unhandled exceptions fail the tool and return an error to the Agent. Use structured error returns (see below) if you want the Agent to recover.

Secrets and network. Cloudflare Worker tools have no network access and cannot read managed secrets. Daytona tools inherit network and secret policy from your container configuration.

Available features

Cloudflare Worker / QuickJS:

• Standard JS built-ins (Array, Object, Math, Date, JSON)
• async/await, arrow functions, destructuring, template literals
• Regex and string manipulation
• Helper utilities via the helpers namespace (see below)
• console.log output is captured in tool execution logs

Helper functions are accessed as helpers.<name>():

Daytona:

• Standard library modules available in your Daytona container image
• pip packages (Python) or npm packages (JS/TS) — availability depends on your Daytona configuration
• fetch and outbound network calls — allowed or blocked based on your Daytona sandbox policy

Defining parameters

Click + Add Parameter and configure each field:

Example:

Execution limits

Set timeout and memory per tool:

• Timeout: 1,000 ms to 300,000 ms. Default is 30,000 ms (30 s).
• Memory: 8 MB, 16 MB, or 32 MB. Default is 16 MB.If your code exceeds memory, the tool fails and returns an error. Cloudflare Workers return a timeout error to the Agent when the limit is exceeded. Daytona behavior depends on your container policy—typically a hard kill.

Code validation

Runtype runs a static AST check before saving any custom tool.

Errors (block save):

• eval() — error code USE_OF_EVAL
• new Function() — error code USE_OF_FUNCTION_CTOR
• Syntax errors

Warnings (surfaced in the dashboard, do not block save):

• Unbounded while (true) loops without a break or await — warning code INFINITE_LOOP
• Dynamic import() expressions — warning code DYNAMIC_IMPORT
• Missing return statement in JavaScript/TypeScript (Cloudflare Worker and QuickJS only) — warning code RETURN_UNDEFINED

The check runs again on every update.

Error handling

Return structured errors so the Agent can recover:

1
const { email } = parameters
2
3
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
4
if (!emailRegex.test(email)) {
5
  return { success: false, error: 'Invalid email format' }
6
}
7
8
return { success: true, isValid: true, email }

Testing tools

Use the Test panel on the tool page:

1. Enter sample values for your parameters
2. Click Run Test
3. Review the output, execution time, and console logs
4. Iterate until correctTest output includes the returned value and any console.log calls.

Best practices

• Single responsibility. Each tool should do one thing well.
• Validate inputs. Check parameter values before processing.
• Clear naming. calculate_shipping_cost is better than process.
• Return structured data. Objects are easier for Agents to work with than raw strings.
• Handle errors gracefully. Return { success: false, error: "..." } instead of throwing.
• One operation per tool. Agents struggle to debug multi-step logic inside a single tool call.
• Write explicit descriptions. Agents use the tool and parameter descriptions to decide when to invoke the tool and what values to pass.

Examples

Email validator

1
const { email } = parameters
2
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
3
return {
4
  isValid: emailRegex.test(email),
5
  email
6
}

Parameters: email (string, required)

Date formatter

1
const { isoDate, format } = parameters
2
const date = new Date(isoDate)
3
4
if (format === 'short') {
5
  return { formatted: date.toLocaleDateString() }
6
} else if (format === 'long') {
7
  return {
8
    formatted: date.toLocaleDateString('en-US', {
9
      weekday: 'long', year: 'numeric', month: 'long', day: 'numeric'
10
    })
11
  }
12
}
13
14
return { formatted: date.toISOString() }

Parameters: isoDate (string, required), format (string, default: "iso")

Array aggregator (Python)

1
import json, statistics
2
3
numbers = parameters['numbers']
4
5
result = {
6
    'sum': sum(numbers),
7
    'average': statistics.mean(numbers),
8
    'min': min(numbers),
9
    'max': max(numbers),
10
    'count': len(numbers)
11
}
12
13
print(json.dumps(result))

Parameters: numbers (array of numbers, required)

Next steps

• Creating external tools — for HTTP API integrations
• Agent tools — how Agents select and invoke tools
• Built-in tools — ready-to-use integrations (Exa, Firecrawl, GPT Image 2)
• What are Tools? — conceptual background