---
title: "Tool Variables"
---

The Custom API Tool builder allows you to build sophisticated tools with external APIs using Airia's visual tool builder interface. This allows your Model to connect to existing APIs and call them as functions, passing in dynamic "Variables" with advanced parameter handling including dot notation support (`headers.Content-Type`, `jsonBody.name`, `queryParameters.limit`).

In this guide, we will be building a custom API tool for the Dall-E Image Generation API.

## Building a Custom API Tool
The Dall-E Image Generation API takes the following configuration:

```
curl https://api.openai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "dall-e-3",
    "prompt": "a white siamese cat",
    "n": 1,
    "size": "1024x1024"
  }'
```

### Creating a custom tool
Let's begin by creating a new Custom API Tool by selecting it from a Project:

You'll see the Custom API Tools page, where you can enter Tool Handling details for the API.

### Fill in the details for your Tool

Copy the following sections:
* Tool Name - Name for the Tool
* Tool Purpose - A description indiating how the Tool should be called. _The Tool Purpose should be treated a Prompt._
* API Endpoint - The API that will be called for the Tool (select the dropdown to choose between GET, POST, PUT, and PATCH APIs)
* Body - Copy the JSON as a Body to the right side of the Tool
* Headers - API Headers with Key and Values

Providing the Tool definition as shown above will execute it as is. For example, you can see that the caption in the Body field is written as

```
{
    "model": "dall-e-3",
    "prompt": "a white siamese cat",
    "n": 1,
    "size": "1024x1024"
}
```
This means that the Model will always call the Dall-E Tool with these values and generate an image of a _white siamese cat_.

## Tool Variables
By using Tool Variables, you can indicate to the Model which fields to generate using AI, and replace them in the API with advanced parameter handling capabilities.

Tool Variables support multiple parameter types with validation:
- **String Parameters:** Text values with optional requirements
- **Number Parameters:** Numeric values with validation
- **Boolean Parameters:** True/false values
- **Complex Objects:** Automatic JSON serialization
- **Arrays:** Automatic array structure handling

> 💡 **Note:** Input Parameters of Objects and Array types automatically include the appropriate structure characters such as `[` and `]` or `{` and `}`, so you don't need to include them in a request body. Simply include the variable without any markers or quotation marks such as `<array/>`.


Let's define an Input Parameters for Image Caption.

![Adding a custom tool](../Images/tool_variables.png)

This Variable can now be used in various parts of the Tool to allow the Model to substite this value.

### Using Tool Variables in Tool Definition
Replace static text with dynamic Tool Variables using HTML tag identifiers `<` and `/>`.

**Enhanced Features:**
- **Auto-complete:** Created Tool Variables appear with intelligent auto-completion
- **Real-time Validation:** Parameter types are validated as you configure them
- **Dynamic JSON Body:** Complex objects are automatically serialized
- **Header Management:** Dynamic header injection with dot notation
- **Query Parameter Handling:** Automatic URL parameter construction

![Adding a custom tool](../Images/using_tool_variables.png)

What this does is whenever the user's prompt includes any relevant information to the Tool, the model will substitue the corresponding values.
If the user asks to generate an image of a Big Red Puppy, the model will set the value of "caption" to "Big Red Puppy".

Tool variables can be used throughout your tool configuration with advanced placement options:

**Supported Locations:**
- **Body:** JSON request bodies with automatic serialization
- **URL Endpoint:** Dynamic URL construction with parameter substitution
- **Headers:** Custom headers including authentication and content-type
- **Query Parameters:** URL query string parameters with automatic encoding

**Parameter Requirements:**
- **Required:** Must be provided for tool execution
- **Optional:** Can be omitted, tool provides defaults
- **Request Body parameter / URL parameter:** use the parameter in a URL or as part of Request Body (Headers and Body)


## Advanced Tool Management

### Using the Custom API Tool
Follow the instructions on adding a new tool on the [Tools doc](tools.mdx), and authenticating on [Authenticating Tools](authenticating-tools.mdx) page.

**Integration with 135+ Credential Types:**
Your custom tools can leverage Airia's comprehensive authentication system including OAuth 2.0, API keys, service accounts, and MCP headers.

By calling the newly created API tool, you'll see that the model intelligently picks up on your prompt cues to generate contextually appropriate responses - like generating an image of a Big Red Puppy when requested!

![Adding a custom tool](../Images/dalle_tool.png)
