Custom HTTP Tools

Define your own HTTP endpoints as agent tools — no MCP server required.

What Are Custom HTTP Tools?

Custom HTTP tools let you expose any API endpoint as a callable tool for your agents. When the agent decides it needs to call the tool, A91I makes the HTTP request on its behalf and returns the response to the agent.

This is the fastest way to integrate a proprietary internal API, a webhook receiver, or any third-party service not covered by the built-in integrations — without writing a custom MCP server.

Shared across agents

Custom HTTP tools are defined at the organization level and can be enabled on any of your agents. Define a tool once, use it in multiple agents.

Creating a Custom Tool

Navigate to Agents → Custom Tools and click New Tool.

Tool Fields

Field	Description
Tool name (snake_case)	Machine-readable identifier the agent uses to call the tool, e.g. get_weather. Must be lowercase letters, numbers, and underscores.
Display name	Human-readable name shown in the UI, e.g. Get Weather.
Description (for LLM)	Explains to the agent when and how to use this tool. Be specific — the agent reads this to decide whether to call the tool.
Method	HTTP method: GET, POST, PUT, PATCH, or DELETE.
URL	The endpoint URL. Supports template variables like {{city}} that the agent fills in.
Headers (JSON)	Static HTTP headers to include in every request, e.g. Authorization, Content-Type.
Request body (JSON)	Static or templated request body for POST/PUT/PATCH requests.

URL & Body Templates

Use {{paramName}} placeholders in the URL or request body. The agent extracts parameter values from the conversation context and substitutes them before making the request.

Example: URL with parameters

# URL template
https://api.weather.com/v1/current?city={{city}}&units={{units}}

# The agent will fill in city and units based on the conversation:
https://api.weather.com/v1/current?city=London&units=metric

Example: JSON body with parameters

{
  "recipient": "{{email}}",
  "subject": "{{subject}}",
  "message": "{{message}}"
}

Authentication

Pass static authentication credentials via the Headers field. Common patterns:

Bearer token authentication

{
  "Authorization": "Bearer YOUR_API_TOKEN",
  "Content-Type": "application/json"
}

API key header

{
  "X-API-Key": "YOUR_KEY",
  "Accept": "application/json"
}

Credential security

Headers are stored encrypted at rest. Avoid putting credentials in the URL itself (they may appear in logs). Always use headers or the request body for secrets.

Enabling Tools on an Agent

Open agent settings

Click the settings icon on the agent card, or navigate to the agent chat and open Settings.

Find Custom Tools

Scroll to the Custom Tools section in the agent settings panel.

Toggle the tool on

Enable the tools you want this agent to be able to call. An agent can have multiple custom tools enabled simultaneously.

Save and test

Save the agent settings. Start a new conversation and ask the agent to perform a task that should trigger the tool.

Writing Good Tool Descriptions

The tool description is the most critical field. The agent reads it to determine whether and when to use the tool. A vague description leads to missed tool calls or incorrect usage.

State clearly what the tool does and what it returns.
Mention the required parameters and what they represent.
Give an example of when to use it.
Note any limitations or caveats.

Good tool description example

Get the current weather conditions for a given city. Returns temperature
(in Celsius or Fahrenheit), weather description, humidity, and wind speed.

Parameters:
- city: The city name, e.g. "London" or "New York"
- units: Temperature units — "metric" for Celsius, "imperial" for Fahrenheit

Use this tool when the user asks about weather in a specific location.

Debugging Tool Calls

When an agent calls a custom tool, the chat shows a tool call block with the full request parameters and the raw HTTP response. If the tool fails:

Check that the URL is reachable from the internet (not localhost or an internal network).
Verify the headers include correct authentication.
Inspect the response body for API-level errors.
Confirm the URL template variables match what the agent is substituting.