> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/tools/tool_description.md).

# Tools Feature Overview

## What Are Tools?

Tools are like **plugins** or **extensions** for an AI assistant, enabling it to do more than just chat. For example, if an AI assistant has a **"Check Weather"** tool, it can tell you today's temperature; if it has a **"Play Music"** tool, it can play music directly for you.

By letting users define a set of "tools" that the AI assistant can use, the AI assistant is able to:

1. Understand complex user requests.
2. Automatically determine when a specific tool needs to be used.
3. Automatically generate the parameters required to call that tool.

This enables the AI assistant to go beyond generating text responses and actually perform a variety of tasks, such as:

* **Querying real-time information:** Retrieve the latest stock prices, weather forecasts, flight statuses, etc. from databases or APIs.
* **Executing external operations:** Call booking system APIs, control smart home devices, send emails or messages.
* **Processing files:** Read, write, or analyze local or cloud documents.
* **Integrating with other software:** Operate CRM systems, project management tools, or other enterprise applications.

<figure><img src="/files/tu5ns8sS66QHhN4qgFuo" alt=""><figcaption></figcaption></figure>

## How Tools Work

A basic tool invocation workflow includes the following steps:

1. **Define tools:**
   * Users must first define the relevant parameters for the tools.
   * Configure which tools the AI assistant can use.
   * Each tool must include:
     * A clear **Name**.
     * An easy-to-understand **Description** that explains the tool's purpose.
     * Detailed **Parameter specifications**, including each parameter's name, data type, whether it's required, etc.
2. **User asks a question:**
   * The user makes a request to the AI assistant in natural language.
   * *Example:* "Check tomorrow's weather in Taipei for me."
3. **Model reasoning and tool selection:**
   * The LLM inside the AI assistant analyzes the intent of the user's request.
   * The model determines whether a tool is needed and which tool from the available list to use.
   * *Example:* The model determines that weather information is needed and selects the tool named `get_weather`.
4. **Generate tool call parameters:**

   * The model generates a structured output (typically in JSON format) containing the tool name and its required parameters.
   * *Example:*

   ```json
   {
     "name": "get_weather",
     "arguments": {
       "city": "Taipei",
       "date": "tomorrow"
     }
   }
   ```
5. **Application executes the tool:**
   * The AI assistant's backend application receives and parses the JSON instruction generated by the model.
   * The application executes the corresponding function or calls the external API based on the tool name and parameters in the instruction.
   * *Example:* The backend calls the weather query API, passing "Taipei" and "tomorrow" as parameters.
6. **Return the result to the model:**

   * The application returns the result of the tool execution (typically also in JSON format) back to the AI assistant's model.
   * *Example:*

   ```json
   {
     "temperature": "25°C",
     "condition": "Sunny"
   }
   ```
7. **Model generates the final response:**
   * The model receives the tool execution result and incorporates it into the final natural language response.
   * *Example:* "Tomorrow's weather in Taipei is expected to be sunny with a temperature of about 25°C."

<figure><img src="/files/qC9iKYR2k1xvvj3ABfy1" alt=""><figcaption></figcaption></figure>

## Key Advantages of Tools

* **Extend AI assistant capabilities:** Break free from the limitation of only generating text, enabling the AI assistant to access real-time information and perform real-world tasks.
* **Improve reliability and accuracy:** Through structured calls and responses, ensure task instructions are clear and precise, reducing the risk of model "hallucinations" or operational errors.
* **Enable complex automated workflows:** Design AI assistants that can autonomously complete multi-step, cross-system tasks, dramatically improving efficiency (e.g., automatically planning a travel itinerary and booking flights and hotels).
* **More natural interaction experience:** Users only need to describe their needs in natural language, and the AI assistant can understand and translate them into precise system operations.

## Tool Types Supported by MaiAgent

The following major types are currently supported:

### API Tools

* **The most commonly used type.** Used to connect to and call external HTTP/HTTPS API services.
* **Common applications**: Retrieving weather information, querying external databases, triggering webhooks, integrating with third-party services, etc.
* **Required configuration**: API endpoint URL, HTTP method, request headers, parameter schema.

### MCP Tools

* **Model Context Protocol** (MCP) enables collaboration between servers, clients, and hosts through a standardized protocol.
* **Applicable scenarios**: Enabling the AI assistant to call external tools for more complex and practical tasks.
* **Required configuration**: MCP server URL, parameters, environment variables, etc.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/tools/tool_description.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.