​
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’re 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 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.
    FieldDescription
    typeMust be "http"
    function.nameUnique function identifier (per execution)
    function.descriptionWhat the tool does and when to use it
    function.parametersJSON schema for input parameters
  • The endpoint field defines how to call it over HTTP:
    FieldDescription
    endpoint.urlThe HTTP URL that will be called via POST
    endpoint.headers (optional)Custom headers, typically for authorization
JSON Example of HTTP Tool definition: 
{
  "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",  // Full URL to the endpoint the server will use a POST request
    "headers": {  // Optional 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: 
{
  "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.