Skip to main content
Custom tools let Duckie call HTTP endpoints that you define. Use them for internal services, third-party APIs, or any API action that is not already covered by a connected integration.

​
Create a Custom Tool

1

Navigate to Tools

Go to Build → Tools, then open the Custom Tools tab.
2

Create the tool

Click Tool to open the custom tool dialog.
3

Add basic details

Enter a name and description. The description helps the agent understand when to use the tool.
4

Configure the endpoint

Choose a method and enter the endpoint URL.Supported methods are GET, POST, PUT, PATCH, and DELETE.
5

Choose authentication

Select an OAuth credential for OAuth 2.0 client credentials, or leave No OAuth and add authentication headers manually.
6

Add headers

Add any non-OAuth headers the endpoint requires, such as API keys, vendor headers, content type headers, or request-specific values the agent should generate.
7

Define parameters

Add the inputs the tool accepts. Parameters can be AI-generated or fixed values.
8

Test the tool

Use Test Tool with sample values before enabling the tool for an agent or assistant.

​
Enable a Custom Tool

After creating a custom tool, choose where it can be used:

​
Endpoint Safety

Custom tool endpoint URLs must use http or https. Duckie blocks local, private, and internal network addresses before making server-side requests.

​
Authentication

Custom tools can call endpoints with no authentication, fixed headers, AI-generated headers, or OAuth 2.0 client credentials.

​
Header value sources

Each custom header can use one of two value sources: Use fixed headers when the API expects a constant value. Bearer token:
API key header:
Basic auth:
For Basic auth, enter the final encoded Authorization value. Use AI-generated headers when the header value should be inferred from the current request instead of stored in the tool configuration or sent as a body/query parameter. Request-specific routing header:
When a tool has AI-generated headers, Duckie exposes those headers to the agent as api_headers, sends only the header names configured on the tool, and merges the generated values into the outbound request. Do not add a normal parameter named api_headers to a custom tool that also has AI-generated headers; that name is reserved for header values.

​
OAuth 2.0 client credentials

Use OAuth credentials when the API requires Duckie to request an access token before calling the endpoint. To create a credential, click New credential in the custom tool dialog and enter: Duckie requests tokens with grant_type=client_credentials, caches valid access tokens, and sends the resolved token as an Authorization header when the custom tool runs. If the token response does not include a token type, Duckie uses Bearer. The OAuth token URL must use https, cannot contain org variables, and must not resolve to a local, private, or internal network address.
If you select an OAuth credential, remove any manual Authorization header before saving the custom tool.

​
Parameters

Parameters describe the values Duckie can send to your endpoint. Each parameter can use one of two value sources: Parameters can be required or optional. Parameters referenced in endpoint or header templates are automatically required.

​
Template Placeholders

Use {{param}} syntax in URLs and headers when a parameter should be inserted into the request target or header value. URL with parameter:
Header with parameter:
Duckie automatically creates required parameters for placeholders it finds in the URL or headers. For POST, PUT, and PATCH requests, non-placeholder parameters are sent in the request body. For GET and DELETE requests, non-placeholder parameters are sent as query parameters.

​
Org Variables

Org variables can be used in URL paths, URL query strings, headers, and fixed values with {{org.variable_name}} syntax. Keep the endpoint scheme and hostname literal, such as https://api.example.com. Duckie validates the endpoint host before resolving org variables, then resolves org variables in the path, query string, and headers before making the request. URL path with org variable:
Header with org variable:
Fixed parameter value with org variable:
When using an org variable as a fixed parameter value, make the whole value the org variable reference. Duckie does not expand org variables embedded inside longer AI-generated parameter values.

​
Context Variables

Context variables let a custom tool use values from the run’s metadata. Use {{context.variable_name}} as the full fixed value for a parameter. For example, if a run has metadata with a phone field, set the custom tool parameter to:
Duckie resolves the fixed value before calling the tool, so the agent does not need to generate that parameter. Context variables also support nested metadata paths:
To use a context variable in a URL path, query string, or header, route it through a fixed parameter and reference that parameter with normal {{param}} placeholders. URL path using a context-backed parameter:
Header using a context-backed parameter:
When using a context variable as a fixed parameter value, make the whole value the context variable reference. Duckie does not expand context variables embedded inside longer AI-generated parameter values.

​
Write Actions and Approvals

Use Write Action for tools that change external state, such as updating an account, issuing a refund, creating a ticket, or sending a message. Use Requires Approval when a human should approve the tool call before it runs. When approval is enabled, you can notify specific Slack users or a Slack channel. Leave the notification field empty to use the org-wide default.

​
HTTP Timeout

You can set a custom HTTP timeout from 1 to 300 seconds. Leave it blank to use Duckie’s default timeout.

Agent Configuration

Enable custom tools for agents

Workflow Actions

Call custom tools from workflows

Duckie as an External Subagent

Send a focused Duckie agent’s result back to a customer-owned orchestrator.