> ## Documentation Index > Fetch the complete documentation index at: https://docs.assistable.ai/llms.txt > Use this file to discover all available pages before exploring further. # Connect a custom API tool > Let an assistant retrieve information or perform an action through an API you control. 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](/v3/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 | Field | Values and behavior | | - | - | | **Name** | Required, 1–64 characters. Use letters, numbers, `_`, or `-`; the name must be unique in the account. | | **Description** | Required in the editor, up to 800 characters. Explain when to call the tool and how to interpret its result. | | **HTTP method** | **GET**, **POST** (new-tool default), **PUT**, **PATCH**, or **DELETE**. | | **Endpoint** | The receiving API's URL. A usable endpoint is needed for the tool to execute. | | **Parameters** | Each row has a name, type, and description. Blank-name rows are omitted. All named parameters are marked required when saved; this editor has no optional-parameter switch. | | **Request Type** | **Proxied** (new-tool default) or **Direct**; see the payload shapes below. | | **Timeout** | Milliseconds; the saved value accepts whole numbers from 0 to 300,000. A new tool displays 10,000. Zero does not mean unlimited execution. See the execution limits below. | | **Headers** | Key/value pairs for the receiving API. Rows with a blank key or value are omitted. | | **Speak while the tool runs** | Off for a new tool. On voice calls, adds a short acknowledgement while the action runs. Publish the assistant for this change to take effect. | | **What to say** | Shown when speaking during execution is enabled. Optional guidance, up to 300 characters; blank uses a natural default rather than a fixed phrase. | ### Parameter types | Type | Value to supply | | - | - | | `STRING` | Text, including identifiers that must retain leading zeroes. | | `NUMBER` | A number that may contain a decimal part. | | `INTEGER` | A whole number. | | `BOOLEAN` | `true` or `false`. | | `OBJECT` | A JSON object. Define the expected content in the description and validate it at your endpoint. | | `ARRAY` | An array without an item-type restriction. Validate its item structure at the endpoint. | | `ARRAY_STRING` | An array of strings. | | `ARRAY_NUMBER` | An array of numbers. | | `ARRAY_BOOLEAN` | An array of booleans. | ### 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](/v3/guides/tools/manage) · [Platform tools](/v3/platform-tools) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.