Skip to main content
Use a custom tool when your assistant needs an action that the existing Tool Kit does not provide. For contact updates, notes, tasks, calendar booking, web search, and web page reading, start with the platform tools.

​
Before you start

Have access to the assistant and its account, an endpoint you are authorized to use, and the endpoint’s request and response specification. Obtain any required credentials from the service owner. A BuildShip workflow is one optional way to host an endpoint; it is not required for native platform tools. Decide what success looks like outside the conversation: an order retrieved, a task created, or a record updated. Use test records for actions that change data.

​
Create the tool

  1. Open Assistants, select your assistant, and open Tool Kit → Tools & APIs.
  2. Select New tool → Custom.
  3. Enter a name without spaces, such as lookup_order. In the description, explain when the assistant should call it, what information it must collect first, and what to do if the lookup fails.
  4. Enter the endpoint and its HTTP method. The editor supports GET, POST, PUT, PATCH, and DELETE; use the method required by your endpoint.
  5. Define each parameter’s name, type, and description. For an order lookup, a string parameter named order_reference could instruct the assistant to ask the customer for their reference. Parameter definitions describe what to collect; they are not example customer values.
  6. Open the advanced settings to configure the request mode and headers. Add only the credentials required by that endpoint, such as an Authorization header when the provider requires one.
  7. Select Create tool, then add the tool to the assistant from the library. Confirm it appears under Assigned to this assistant. Save and publish the assistant before testing live voice behavior.
You can also use Import cURL to populate a request. Review the imported endpoint, headers, and parameters before saving.

​
Editor fields and choices

​
Parameter types

​
Execution limits

The saved timeout, editor test, and live voice deadline are separate limits. Chat requests through the tool proxy have a 15,000 ms minimum and a 300,000 ms ceiling. The endpoint test accepts 1,000–30,000 ms. Voice calls have a 10-second provider deadline; request preparation and response delivery consume part of it, so the endpoint receives less time and the voice proxy does not retry it. A timeout does not prove a write endpoint made no change—check for the intended record before repeating a write.

​
Match the request shape

For a Direct custom request, the endpoint receives the tool parameters as its JSON body. For a Proxied request, the parameters are under args; conversation identity is supplied separately under meta_data and metadata. For example, a proxied receiver should read the order reference from args.order_reference and the linked contact identifier from meta_data.contact_id when present. Do not ask the assistant to invent a contact ID. GET parameters are sent in the query string, without a JSON request body. Configure your endpoint for the selected mode; an endpoint expecting a flat body will not automatically understand args.

​
Test the result

Use Test in the tool editor with known inputs. Inspect the response body as well as the HTTP status. Then run a conversation that should call the tool and confirm the resulting record in the receiving system. A successful request alone does not prove the intended update occurred. Return a small, explicit result that distinguishes success, no match, and failure. Tell the assistant to report success only when the returned result confirms it.

​
Troubleshooting

  • Missing parameters: compare the endpoint’s expected names and nesting with the request mode and tool definitions.
  • Unauthorized request: check the header name, credential, and target account. Never place credentials in the prompt or model-collected parameters.
  • Works in the editor but times out on a call: voice tools have a shorter execution window. Return promptly; increasing the chat timeout does not extend a voice call’s limit.
  • The assistant never calls the tool: confirm assignment, publish the assistant, and make the trigger conditions clear in its instructions.
  • Duplicate records: make write endpoints recognize repeated submissions before using them in a live workflow.

​
Next steps

Manage tools · Platform tools