How to create a Tool

You will learn

How to connect Customer Agent to an HTTP endpoint using a fully custom tool, write a tool description that Customer Agent will actually use, and test your tool before attaching it to a skill.

Before you begin

You’ll need:

• Customer Agent enabled
• An HTTP endpoint reachable through a public hostname. Private-network addresses, localhost, and URLs that use an IP address instead of a hostname are not supported. If the endpoint requires an API key or token, you’ll store it as a secret (see Steps 1 and 6).
• A skill with editable instructions to attach the tool to

You can create and test the tool before attaching it to a skill. To use it in conversations, add it to the skill’s instructions. If you need a new skill, see How to create a Skill.

What a fully custom tool is

A fully custom tool is an HTTP request Customer Agent can make during a conversation. Use one when the tools Customer Agent comes with don’t cover what you need — for example, looking up an order in your own order management system instead of Shopify, checking inventory in a custom warehouse system, or creating a ticket in a helpdesk Klaviyo doesn’t natively integrate with.

For the underlying concept, see Understanding Tools.

When to create a fully custom tool

Reach for a fully custom tool when:

• You need real-time data from a system Klaviyo doesn’t already integrate with
• You want Customer Agent to take an action in an external system (cancel a subscription in your proprietary system, create a ticket, update a record)
• An existing tool doesn’t fit — for example, you use a custom OMS instead of Shopify for orders

If the information doesn’t change often and is the same for every customer, add it as content instead. Tools are for dynamic, per-customer data and actions.

Set it up

1. Open the Custom tools page

1. Navigate to Customer Agent > Connectors, then open the Custom card.
2. If your endpoint needs a credential, go to Secrets and click Add secret. Enter a Name and Secret value, then click Add secret. Skip this step if the secret is already saved or the endpoint does not need one.
3. Click Create tool.

2. Name and describe the tool

• Tool name — A short identifier like “Get Inventory” or “Create Return Ticket.”
• Description — Natural language explaining what the tool does and when to use it. Customer Agent reads this description to decide whether to use the tool for a given request. Be specific.

A good description example:

Fetches real-time inventory count for a given product SKU from the warehouse system. Use when a shopper asks whether a specific product is in stock.

A vague description example (avoid):

Gets product info.

3. Configure the HTTP request

• HTTP method — GET, POST, PUT, DELETE, or PATCH.
• URL template — The full endpoint URL. You can include placeholders for dynamic values (see Step 5).
• Headers — Any headers your endpoint requires, including Content-Type and authentication headers.
• Query parameters — If your endpoint expects values in the query string, enter their names and values here. You can use placeholders for the values (see Step 5).

4. Configure the request body (for POST, PUT, PATCH)

In Body template, provide a JSON object. Use placeholders for values Customer Agent should fill in at runtime.

Example body:

{
"customer_id": "{{profile_id}}",
"sku": "{{product_sku}}"
}

5. Define variables for dynamic values

Each placeholder must have a matching variable under Variables. For the example body above:

1. Click Add variables and enter profile_id as the Variable name. Set Source to Klaviyo Profile and Klaviyo Property to Klaviyo ID. This supplies the authenticated shopper’s Klaviyo profile ID.
2. Add another variable named product_sku. Set Source to Dynamic Variable, choose String as its Type, and describe the SKU Customer Agent should provide in Description. Select Required if the endpoint requires it.

Repeat for other values your endpoint needs, such as order_id. Variable names must match their placeholders exactly. A variable named conversation_id is not automatically filled with the current conversation ID.

Use the variables as placeholders, such as {{profile_id}} and {{product_sku}}, in the URL, headers, query parameters, or body. Tools that use Klaviyo Profile variables require an authenticated shopper; a missing required profile value prevents the request from running.

6. Authentication

If your endpoint requires an API key, bearer token, or other credential, store it as a secret. Secrets are encrypted, their values are never shown to Customer Agent, and they can’t be viewed again after you save them.

1. In your tool, under Variables, click Add variables. Give the variable a name (for example, api_key), set Source to Secret, and choose the secret you saved.
2. Reference the variable wherever your endpoint expects the credential: a header, the URL, a query parameter, or the body. For example, add a header named Authorization with the value Bearer {{api_key}}.

To rotate a key, open the secret’s row menu, click Update, enter the replacement value, then click Update. Every tool that uses the secret picks up the new value. The Used by column shows which tools reference each secret, so check it before you delete one.

7. Save and test the tool

Before saving, review Timeout (seconds) and Max retries under Settings. You can set an overall time limit of 1–10 seconds and 0–3 retries for temporary failures. If the tool changes data, make sure your endpoint can safely handle a repeated request.

Click Save to create the tool. The saved tool opens with a Test section.

Tests send real requests to your endpoint and can change data. Use a test profile and test records. Save and run test also saves any edits to the tool, including a tool already used by live skills.

In Test, enter sample values for the dynamic variables. Select a test profile under Profile if the tool uses Klaviyo Profile variables. Click Save and run test.

Review Response and check that:

• The response comes back successfully
• The response contains the data your skill needs
• Expected error cases return useful status codes and messages

8. Attach the tool to a skill

1. Navigate to Customer Agent > Skills and open the skill you want to use the tool. If its instructions are read-only, create a fully custom skill.
2. In How to respond, type / where the tool should be used and select the tool from the menu. Explain when to call it, which values to provide, and what to do with the result or an error.
3. When the instructions are ready, click Publish for a draft skill or Update for a live skill.

Writing a good tool description

A clear description helps Customer Agent decide when to use the tool. The skill’s instructions also guide which tool it calls and how it uses the result. Good descriptions:

• Say what the tool does in one sentence
• Say when to use it in one sentence
• Are specific about the data returned or action taken

Bad descriptions are vague (“Gets customer info”), too broad (“Handles anything related to orders”), or tell Customer Agent how to behave rather than what the tool does.

Security considerations

• Store credentials as secrets. Never paste an API key or token directly into a header, URL, or body. Add it as a secret and reference it with a Secret variable (see Step 6).
• Use IP allowlisting where possible. Your endpoint must still be reachable through a public hostname; private-network addresses and localhost are blocked. Use allowlisting as an extra layer of protection alongside authentication.
• Be aware of what data you send. Your request configuration and variable sources determine which values are sent to the endpoint. Skill instructions guide the values Customer Agent supplies for dynamic variables. Review what fields your endpoint receives.
• Rate limits. If your endpoint has rate limits, make sure they’re high enough to handle your expected conversation volume.

Troubleshooting

Symptom: Customer Agent never uses the tool.
Likely cause: The description is too vague, or the tool isn’t included in the skill’s published instructions.
Fix: Rewrite the description to specifically describe when it should be used. In How to respond, insert the tool using / and explain when to call it. Click Publish or Update to apply the instructions.

Symptom: The tool returns an error during testing.
Likely cause: Wrong URL, malformed body, missing required profile data, or a payload your endpoint doesn’t accept.
Fix: In Test, review Request preview and Response. Verify the URL, headers, and body against your endpoint’s expected input. If the tool uses Klaviyo Profile variables, select a test profile with the required values.

Symptom: Customer Agent uses the tool but passes wrong parameters.
Likely cause: A variable has the wrong source or profile property, or the skill instructions are unclear about what to pass.
Fix: Check the variable names, sources, and selected profile properties under Variables. Update the variable descriptions and skill instructions to be explicit about what to provide.

Symptom: The tool is slow, causing delays in responses.
Likely cause: Endpoint latency.
Fix: Optimize your endpoint. Check whether you can cache results on your side.

FAQ

Can one tool be used by multiple skills?
Yes. Once created, a tool can be used by multiple skills. Insert it into each skill’s editable instructions and publish or update each skill.

What auth methods are supported?
Any method that sends a static credential with the request, such as a bearer token or an API key header. Store the credential as a secret and reference it with a Secret variable (see Step 6). Flows that need to fetch or refresh a token at request time, such as OAuth, aren’t supported in fully custom tools.

What happens if my endpoint is down or returns an error?
Klaviyo reports tool failures to Customer Agent. Temporary failures can be retried within the tool’s timeout and retry limits. In the skill’s instructions, explain how to respond if the tool cannot complete the request, such as offering to hand off. Use reliable endpoints and monitor tool behavior closely.

Can I edit a tool after creating it?
Yes. Open the tool from Customer Agent > Connectors > Custom, edit its name, description, or request configuration, then click Save. Add or remove the tool in each skill’s instructions.

Can I version a tool?
Versioning isn’t supported yet. Saved changes apply to the shared tool used by every skill that references it. Save and run test also saves changes, so check which live skills use the tool before editing it.

Additional resources