> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai21.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP tools

> Description of your new file.

## Overview

HTTP tools allow AI21 Maestro to call external services directly using standard HTTP requests. Unlike MCP, which supports dynamic discovery and standardized communication, HTTP tools are statically defined and managed by the user. They are best for simple or one-off integrations that don’t require a full MCP server.

## When to Use HTTP Tools

* When you want a **quick integration** without building an MCP Server.
* When you have standalone endpoints that don’t require cataloged discovery.

## Defining an HTTP Tool

Each HTTP tool must include a `function` definition and an `endpoint` configuration.

* The `function` field describes **what the tool does** and **what input it expects**.

  | Field                  | Description                                |
  | :--------------------- | :----------------------------------------- |
  | `type`                 | Must be `"http"`                           |
  | `function.name`        | Unique function identifier (per execution) |
  | `function.description` | What the tool does and when to use it      |
  | `function.parameters`  | JSON schema for input parameters           |
* The `endpoint` field defines how to call it over HTTP:

  | Field                           | Description                                 |
  | :------------------------------ | :------------------------------------------ |
  | `endpoint.url`                  | The HTTP URL that will be called via POST   |
  | `endpoint.headers` *(optional)* | Custom headers, typically for authorization |

**JSON Example of HTTP Tool definition:**

```json theme={"system"}
{
  "type": "http",
  "function": {
    "name": "get_weather",
    "description": "Get current temperature for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and country e.g. Bogotá, Colombia"
            }
        },
        "required": [
            "location"
        ],
        "additionalProperties": false
    }
  },
  "endpoint": {
    "url": "https://my.endpoint.com",  
    "headers": { 
      "Authorization": "Bearer {api_key}"
    }
  }
}
```

## Request Flow & Authentication

Once defined, AI21 Maestro can call this tool by sending a `POST` request to the provided endpoint.

### **Example Request:**

Given that the user provided the example input above with the `get_weather` tool, and during an execution Maestro decides to call it with "Tel-Aviv" as the location, the following HTTP request will be sent to the user's endpoint:

URL: `https://my.endpoint.com/get_weather`

Method: `POST`

Headers: `Authorization: Bearer {api_key}`

Body:

```json theme={"system"}
{
  "location": "Tel-Aviv"
}
```

### Authentication

Headers are defined statically in the `endpoint.headers` object. This is where you can pass:

* Bearer tokens
* API keys
* Session headers or custom headers

## Best Practices

* **Use specific tool names** that clearly reflect their action (`get_user_profile`, `get_invoice`).
* **Include descriptions for all parameters**, not just the tool itself — this improves tool selection by the LLM.
* **Avoid overly broad or generic tools**; precise and focused tools tend to perform better.
* **Limit additional properties** unless the endpoint accepts flexible payloads.