Relevance AI Custom Tools: The Most Powerful Feature Most Builders Never Use

Relevance AI's tool builder turns any API or data source into an agent skill. Here is how to build tools that actually work reliably.

What Custom Tools Are

Relevance AI's tool builder lets you create reusable agent skills that can: call any external API, run JavaScript transformations, search knowledge bases, execute LLM prompts, or chain multiple steps together. Tools are what make your agents actually useful beyond conversation -- they are the bridge between AI reasoning and real-world data and actions.

Despite being the platform's most powerful feature for advanced use cases, most builders stop at the pre-built tools. This article walks you through building custom tools that give your agents capabilities specific to your product.

The Tool Structure

Every Relevance AI tool has the same structure: inputs (what the agent passes to the tool), steps (what the tool does), and an output (what the tool returns to the agent).

Example 1: CRM Lookup Tool

A tool that takes a customer email and returns their account details from your CRM API.

1. In Relevance AI, go to Tools > Create Tool.
2. Add an Input: customer_email (Text, Required).
3. Add a Step: API Call.
4. Set the URL to your CRM endpoint: https://api.yourcrm.com/v1/contacts?email={{customer_email}}
5. Add Authorization header: Bearer {{secrets.crm_api_key}}
6. In the Output section, map: account_tier = {{steps.api_call.output.data.tier}}, account_status = {{steps.api_call.output.data.status}}

{
  "tool_name": "lookup_customer",
  "description": "Look up a customer account by email address. Returns account tier, status, and usage data.",
  "inputs": {
    "customer_email": {
      "type": "text",
      "description": "The customer's email address",
      "required": true
    }
  },
  "steps": [
    {
      "type": "api_call",
      "name": "crm_lookup",
      "url": "https://api.yourcrm.com/v1/contacts",
      "method": "GET",
      "params": { "email": "{{customer_email}}" },
      "headers": { "Authorization": "Bearer {{secrets.crm_api_key}}" }
    }
  ],
  "output": {
    "customer_name": "{{steps.crm_lookup.output.data.name}}",
    "account_tier": "{{steps.crm_lookup.output.data.tier}}",
    "account_status": "{{steps.crm_lookup.output.data.status}}"
  }
}

Example 2: Data Transformation Tool

A tool that takes raw API output and uses an LLM step to convert it into a human-readable summary -- useful when the raw API returns complex JSON your agents would otherwise struggle to interpret.

1. Add Input: raw_data (Long Text).
2. Add Step 1: API Call to fetch the data.
3. Add Step 2: LLM Prompt. Prompt: 'Convert the following JSON data into a clear 2-3 sentence summary for a customer support agent: {{steps.api_call.output}}'
4. Output: summary = {{steps.llm_prompt.output}}

LLM steps inside tools consume both an Action (for the step) and Vendor Credits (for the tokens). For high-volume tools, use simple text transformations or code steps instead of LLM steps to reduce cost. Reserve LLM steps for transformations that genuinely require language understanding.

Writing Tool Descriptions That Agents Actually Follow

The description you give a tool is how the agent decides when and how to use it. Vague descriptions lead to misuse or the tool being ignored entirely.

// Weak description (agent will often skip or misuse this):
"Gets customer information"
 
// Strong description (agent knows exactly when and how to use it):
"Look up a customer's account details by their email address.
Use this when the user provides or mentions an email address and you need
to know their account tier, subscription status, or usage.
Do NOT use this for general questions -- only when you have a specific email to look up.
Returns: account_tier (free/pro/enterprise), status (active/suspended/cancelled).

Chaining Tools in an Agent

The real power of custom tools comes when agents chain them together across a conversation. Design tools so their outputs are inputs to other tools.

// Agent conversation example using chained tools:
 
User: "Why is John at acme@example.com having trouble with our API?"
 
Agent step 1: Calls lookup_customer(customer_email="acme@example.com")
  --> Returns: account_tier=pro, status=active, api_key_id=key_abc123
 
Agent step 2: Calls get_api_key_logs(api_key_id="key_abc123", limit=20)
  --> Returns: last 20 API calls with status codes
 
Agent step 3: Analyses logs, identifies 403 errors on /v2/advanced endpoint
 
Agent response: "John's account is active on the Pro plan. His API key is
returning 403 errors on the /v2/advanced endpoint. This endpoint requires
the Enterprise plan. I recommend upgrading or using the /v1/standard endpoint
which is included in his current plan.

Quick Reference

• Every tool needs: inputs (what agent passes), steps (what it does), output (what it returns)
• Write tool descriptions as precise instructions: when to use, what it returns, when NOT to use
• Use API Call steps for external data; LLM Prompt steps for language transformation; Code steps for computation
• Store API keys in Relevance AI Secrets, not hardcoded in tool definitions
• Design tool outputs to be inputs to other tools -- chain them for complex workflows
• Reserve LLM steps in tools for genuine language tasks -- use code/API for everything else to control cost