AI21 Maestro’s User-Provided Tool Calling feature enables integration with external systems via user-defined tools. Instead of relying solely on built-in capabilities, AI21 Maestro can incorporate user-defined tools and invoke them when relevant to a task or context. These tools allow AI21 Maestro to interact with external services such as internal APIs, third-party platforms, or custom business logic by executing HTTP requests or other defined operations. This extends its ability to retrieve information, perform actions, or delegate parts of the task to external systems. Each tool must include a description specifying its name, purpose, input parameters, and expected output. Accurate and complete metadata improves the model’s ability to identify when a tool should be used. AI21 Maestro is responsible for calling the tools directly without returning control to the user.
There are two supported types of user-provided tools: HTTP Tool This tool type is identical in its essence to the widespread “Function tool”. The user is responsible for passing the function’s name, description and the parameters’ descriptions. In addition, the user needs to provide an endpoint which AI21 Maestro will call with the relevant parameters. Find more details on how AI21 Maestro interacts with the endpoint here. MCP Tool Tools are hosted on a remote server that implements the Model Context Protocol (MCP). AI21 Maestro connects to this server to fetch the available tools and invokes them directly when needed. This model can optionally include approval steps before execution.
Find more details about the MCP tool here.

​
Limitations

Due to AI21 Maestro’s multi-path execution and planning architecture, it may explore more than one way to accomplish a task, , which can result in multiple calls to the same tool.
Because of this behavior:
Action / Write tools are strongly discouraged.
If such tools are invoked in more than one path, it can lead to unintended duplication of actions, inconsistent states, or conflicting side-effects.
Retrieval / Read tools are recommended instead.
They are safer under multi-path exploration because they avoid the risks associated with side effects and state change: they provide information without altering external systems or resources.

​
Key Benefits

  • Enhanced Context: AI21 Maestro can retrieve data directly from your systems in order to better answer your queries.
  • Real-time data: AI21 Maestro can access your system directly without needing to index the data in advance.
  • Support for Existing Infrastructure: You can reuse your existing tools and services instead of transforming internal knowledge into ingestible documents for file search.

​
Example: Tool Definition

Here’s a simplified Python snippet of a tool definition for accessing JIRA issue data: 
@jira_mcp.tool(tags={"jira", "read"})
async def get_issue(
    ctx: Context,
    issue_key: Annotated[str, Field(description="Jira issue key (e.g., 'PROJ-123')")],
    ...
) -> str:
    """Get details of a specific Jira issue including its Epic links and relationship information."""
This tool could be registered for either HTTP Tool or MCP usage, depending on where and how it is hosted. Note that this tool implicitly contains the following definitions:
  1. Tool name
  2. Tool description
  3. Parameter names
  4. Parameter types
  5. Parameter descriptions
Every one of these definitions helps AI21 Maestro decide when to call the tool and with which parameters to do so.

Example: Tool definition in JSON 
{
  "name": "get_issue",
  "description": "Get details of a specific Jira issue including its Epic links and relationship information.",
  "tags": ["jira", "read"],
  "input_schema": {
    "type": "object",
    "properties": {
      "issue_key": {
        "type": "string",
        "description": "Jira issue key (e.g., 'PROJ-123')"
      }
    },
    "required": ["issue_key"]
  },
  "output_schema": {
    "type": "string"
  }
}

​
Practical Considerations

  • Keep tool descriptions complete and accurate.
  • Limit the number of tools exposed per use case to improve selection accuracy.
  • Ensure tool outputs are structured in a machine-readable format (e.g., JSON) and consistently shaped.

​
MCP vs. HTTP: Choosing the Right Tool

MCPHTTP
**Multiple related tools **
(e.g., Jira, HubSpot)		YesNo
Providing tool definitionsThe MCP provides them via tool discoveryThe user provides the description
The user provides the descriptionNoYes