> 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/en/build/agent-ops/tool-execution-records.md).

# Tool Execution Records

Tool execution records: track the complete history of an Agent's calls to APIs, databases, crawlers, and other tools, view inputs, outputs, and failure causes, and speed up troubleshooting of tool iss

## Overview <a href="#overview" id="overview"></a>

Tool execution records let you track the complete history of an Agent's calls to external tools, including API calls, database queries, web crawling, and other operations. When an Agent needs to perform tasks beyond the scope of the conversation, it does so through tools. Tool execution records help you understand how tools are being used, find the causes of execution failures, and optimize tool configurations.

With complete execution records, you can find the cause of a tool failure within 5 minutes, cut troubleshooting time by 80%, and ensure the Agent reliably delivers advanced functionality.

## Who Can Use This <a href="#who-can-use" id="who-can-use"></a>

A role needs the <mark style="color:blue;">Tool Execution Records permission</mark> under the <mark style="color:blue;">AgentOps permission</mark> for <mark style="color:blue;">Tool Execution Records</mark> to appear under <mark style="color:blue;">AgentOps</mark> in the left menu and for the corresponding API to be allowed; organization owners have it by default. This permission applies to the whole organization: members who hold it can see the execution records of all Agents and all tools in the organization, and they do not see fewer records just because they lack the <mark style="color:blue;">AI Assistant permission</mark> for a particular Agent. Records contain user inputs and tool inputs/outputs, so grant access only to people who need to troubleshoot tool issues; sensitive values such as API Keys in request headers are always displayed as masked. For how to configure this, see [Role Permission Management](/maiagent-user-guide/en/org/roles/role-permission.md).

## Features <a href="#features" id="features"></a>

With the tool execution records feature, you can:

### 📋 **Keep a complete execution history** <a href="#complete-execution-history" id="complete-execution-history"></a>

The system automatically records every tool call, including input parameters, execution results, duration, and success or failure status.

* **Use case**: An e-commerce platform's order query tool is called 500 times a day, and you need to track its success rate and response time
* **Actual benefit**: Found that 10% of queries failed due to timeouts; after adjusting the timeout setting, the success rate rose to 98%

### 🔍 **Quickly locate failure causes** <a href="#locate-failure-cause" id="locate-failure-cause"></a>

When a tool execution fails, the system records a detailed error message to help you quickly understand where the problem is.

* **Use case**: A weather query API suddenly starts failing frequently, and you need to find the cause quickly
* **Actual benefit**: The error records revealed an expired API key, which was updated within 5 minutes to restore service

### 📊 **Track tool usage statistics** <a href="#tool-usage-statistics" id="tool-usage-statistics"></a>

View statistics for each tool, such as call count, success rate, and average execution time.

* **Use case**: A company has configured 10 tools and wants to know which are used most often and which have the most problems
* **Actual benefit**: Found 3 tools that were never used; removing them reduced system complexity, and the other tools responded 15% faster

### 🎯 **Optimize tool configurations** <a href="#optimize-tool-configuration" id="optimize-tool-configuration"></a>

Based on analysis of execution records, adjust tool parameters, optimize call logic, and improve error handling.

* **Use case**: A database query tool often times out because its query scope is too large
* **Actual benefit**: After adjusting the query limits based on the record analysis, execution time dropped from an average of 8 seconds to 3 seconds

## Tool Types <a href="#tool-type-descriptions" id="tool-type-descriptions"></a>

MaiAgent supports multiple tool types, and tool execution records track the execution of all of them:

### API Tool <a href="#api-tool" id="api-tool"></a>

Calls external APIs to get real-time data, such as weather queries, exchange rate queries, and inventory queries.

**Common execution issues**:

* API key expired or invalid
* Incorrect request parameter format
* API service timeout or no response
* API call limit exceeded

### Text-to-SQL Tool <a href="#text-to-sql-tool" id="text-to-sql-tool"></a>

Converts natural language questions into SQL queries to retrieve data from a database.

**Common execution issues**:

* SQL syntax errors
* Timeouts caused by an overly broad query scope
* Database connection failures
* Insufficient permissions to access certain tables

### Crawler Tool <a href="#crawler-tool" id="crawler-tool"></a>

Fetches real-time information from specified websites, such as the latest news and product prices.

**Common execution issues**:

* Target website unreachable
* Parsing failures caused by webpage structure changes
* Blocked or rate-limited by the target website
* Crawl timeouts

### Custom Tool <a href="#custom-tool" id="custom-tool"></a>

Tools with specific functions developed by the company itself, such as order processing and member verification.

**Common execution issues**:

* Internal service errors
* Parameter validation failures
* Business logic errors
* System integration problems

## Usage Steps <a href="#usage-steps" id="usage-steps"></a>

### Step 1: Open Tool Execution Records <a href="#step-access-tool-execution-records" id="step-access-tool-execution-records"></a>

1. Go to the admin console and click <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">Tool Execution Records</mark> in the left menu
2. View the list of recent tool execution records

### Step 2: Filter and View Records <a href="#step-filter-records" id="step-filter-records"></a>

Use the filters to find the execution records that need your attention:

1. **Time range**:
   * Today, last 7 days, last 30 days
   * Or a custom start and end date
2. **Tool type**:
   * All tools
   * API tool
   * Text-to-SQL
   * Crawler tool
   * Custom tool
3. **Execution status**:
   * All
   * Succeeded
   * Failed
   * Running
4. **Specific tool**:
   * Select a specific tool name from the dropdown
5. Click "Apply Filters" to view the matching records

{% hint style="info" %}
**Priority items to review**

We recommend checking these first:

1. Records of failed executions
2. Records with an execution time over 10 seconds
3. The execution status of frequently used tools
   {% endhint %}

### Step 3: View Execution Details <a href="#step-view-execution-details" id="step-view-execution-details"></a>

1. Click any record in the list
2. Expand the detailed information, which includes:

**Basic information**:

* Tool name
* Execution time (when it was called)
* Duration (how many seconds it took)
* Execution status (succeeded/failed)

**Input parameters**:

* The parameters the AI passed to the tool
* Lets you check whether the parameters are correct

**Execution result**:

* The complete result returned by the tool
* On success, shows the data retrieved
* On failure, shows the error message

**Related conversation**:

* The conversation that triggered this tool call
* Lets you trace the user's original question

**Request information** (API tools):

* <mark style="color:blue;">Request URL</mark>, <mark style="color:blue;">Request Method</mark>: The URL actually sent (with path parameters and query parameters filled in) and the HTTP method, which you can compare directly against the API documentation
* <mark style="color:blue;">Request Headers</mark>: The headers sent; sensitive values such as Authorization and API Key are shown as <mark style="color:blue;">Masked</mark>, and hovering shows the tooltip "Sensitive data; the original value is kept only in the backend DB"
* <mark style="color:blue;">Request Body</mark>: The content sent with POST/PUT; if there is none, "No body" is shown
* When the card shows "Request information was not saved for this record (legacy record or non-API tool)", this record predates the feature's release, or it belongs to a non-API tool such as MCP or Text-to-SQL

**Error message** (if any):

* A detailed error description
* Error code or exception type
* Stack trace information (if applicable)

### Step 4: Analyze the Failure Cause <a href="#step-analyze-failure-cause" id="step-analyze-failure-cause"></a>

When you find a failed execution record, you can analyze it with the following steps:

1. **Check the error message**:
   * Read the detailed error description
   * Identify whether it is a configuration issue, a permission issue, or a service error
2. **Check the input parameters**:
   * Confirm that the parameters the AI passed are correct
   * Check that the parameter format meets the tool's requirements
3. **View the related conversation**:
   * Understand what question the user asked
   * Determine whether a particular type of question caused the failure
4. **Compare against successful cases**:
   * Find successful execution records of the same tool
   * Compare the differences between successful and failed cases

### Step 5: Optimize the Tool Configuration <a href="#step-optimize-tool-config" id="step-optimize-tool-config"></a>

Based on the analysis of the execution records, take improvement measures:

1. **Update the tool settings**:
   * Fix incorrect API keys or connection information
   * Adjust the timeout setting
   * Optimize query parameters or limits
2. **Adjust the AI prompt**:
   * If parameters are often wrong, add explicit guidance to the prompt
   * Explain how to use the tool correctly and the parameter format
3. **Improve error handling**:
   * Add friendly error messages for common error situations
   * Set up an automatic retry mechanism
4. **Remove unused tools**:
   * If a tool has gone unused for a long time, consider removing it to simplify the configuration

### Step 6: Export Execution Records <a href="#step-export-execution-records" id="step-export-execution-records"></a>

1. Click the "Export" button on the tool execution records page
2. Choose the export format (CSV or Excel)
3. Choose the time range and filters
4. Download the report for further analysis or archiving

{% hint style="info" %}
Exported records can be used for:

* In-depth data analysis and trend tracking
* Reporting issues to the technical team
* Regularly reviewing tool usage efficiency
* Compliance auditing and record keeping
  {% endhint %}

## Use Cases <a href="#use-cases" id="use-cases"></a>

### Use Case 1: Diagnose a Tool Failure <a href="#use-case-diagnose-tool-failure" id="use-case-diagnose-tool-failure"></a>

**Scenario**: An e-commerce platform's inventory query tool suddenly starts failing in large numbers, and customer service cannot check product stock for customers.

**Steps**:

1. Open tool execution records and filter by "Inventory query tool" + "Failed"
2. Find 50 failed records in the past 2 hours
3. Check the error message in the failed records: "Database connection timeout"
4. Check the database service status and find that the database is under maintenance
5. Temporarily disable the tool and notify customer service to switch to manual lookups
6. Re-enable the tool after the database recovers, and monitor the success rate returning to normal

**Quantified benefits**:

* Pinpoint the root cause within 5 minutes
* Spare the technical team hours of troubleshooting
* Notify customer service in time to use a fallback plan, reducing customer waiting time

### Use Case 2: Optimize Tool Performance <a href="#use-case-optimize-tool-performance" id="use-case-optimize-tool-performance"></a>

**Scenario**: The order query tool is often slow to execute, hurting the conversation experience.

**Steps**:

1. Export the order query tool's execution records for the past 30 days
2. Analyze the distribution of execution times and find:
   * Average execution time of 7.5 seconds
   * 25% of queries take over 10 seconds
   * The longest takes up to 18 seconds
3. Review the input parameters of the slow queries and find that most are querying "all orders in the past year"
4. Optimize the tool configuration:
   * Limit the query scope to the past 3 months
   * Add pagination that returns at most 20 records at a time
5. After optimization, the average execution time dropped to 3.2 seconds

**Quantified benefits**:

* Execution time reduced by 57% (7.5 seconds → 3.2 seconds)
* Queries over 10 seconds fell from 25% to 5%
* Conversation experience improved significantly, and customer satisfaction increased

### Use Case 3: Discover Unused Tools <a href="#use-case-discover-unused-tools" id="use-case-discover-unused-tools"></a>

**Scenario**: A company has configured 12 tools for an Agent and wants to understand actual usage in order to simplify the configuration.

**Steps**:

1. Export all tool execution records for the past 90 days
2. Count the calls for each tool:
   * Order query: 1,500 calls
   * Member query: 800 calls
   * Promotion query: 300 calls
   * Product specification query: 200 calls
   * The other 8 tools: 0 calls
3. Review the configurations of the unused tools and find that:
   * Some tool definitions are unclear, so the AI does not know when to use them
   * Some tools have duplicate functions
   * Some tools are outdated
4. Remove 6 unused tools and improve the descriptions of 2 rarely used tools

**Quantified benefits**:

* Simplified configuration, with the AI's tool selection accuracy improving by 20%
* System response speed improved by 10% (less time spent deciding which tool to select)
* Lower maintenance costs

### Use Case 4: Monitor API Usage <a href="#use-case-monitor-api-usage" id="use-case-monitor-api-usage"></a>

**Scenario**: A company uses a third-party weather API with a monthly call limit, and needs to monitor usage to avoid exceeding it.

**Steps**:

1. Export the weather query tool's execution records every Monday
2. Track the trend in call counts:
   * Week 1: 320 calls
   * Week 2: 450 calls
   * Week 3: 680 calls
   * Week 4: estimated 900 calls (monthly limit of 2,000 calls)
3. Notice the call volume growing quickly and analyze the causes:
   * Customers are asking about the weather more often
   * Some unnecessary repeated queries
4. Take action:
   * Add a caching mechanism so the same city is not queried again within 1 hour
   * Optimize the prompt so the AI does not over-rely on the weather tool
5. After optimization, weekly calls dropped to 400, ensuring the limit is not exceeded

**Quantified benefits**:

* Avoid service interruptions caused by exceeding the API limit
* Reduce API call costs by 40%
* Control costs while maintaining service quality

## FAQ <a href="#faq" id="faq"></a>

### Q: How long are tool execution records kept? <a href="#faq-record-retention-period" id="faq-record-retention-period"></a>

A: Records are not cleared automatically over time. If you need to keep them long term or analyze them in another system, use [Export](#step-export-execution-records) to download them.

### Q: Why did a tool execution fail but the conversation looks normal? <a href="#faq-tool-failed-but-conversation-normal" id="faq-tool-failed-but-conversation-normal"></a>

A: When a tool execution fails, the Agent may:

1. Tell the user "I'm unable to look that up right now. Please try again later."
2. Answer using knowledge base information instead (if relevant content exists)
3. Ask the user for more information and try again

Although the conversation continues, functionality is limited. We recommend using execution records to track down the cause of failures and fix them, so that the tools run reliably.

### Q: How can I reduce the tool execution failure rate? <a href="#faq-reduce-failure-rate" id="faq-reduce-failure-rate"></a>

We recommend optimizing in the following areas:

**Configuration**:

* Make sure configurations such as API keys and database connections are correct
* Set a reasonable timeout (10-15 seconds recommended)
* Add an error retry mechanism

**Prompt**:

* Clearly explain when to use the tool and its parameter format
* Add examples to help the AI call the tool correctly

**Monitoring**:

* Check execution records regularly
* Detect and fix problems promptly
* Track the success rate trend

### Q: What if the input parameters in the execution records contain sensitive data? <a href="#faq-sensitive-data-in-input-params" id="faq-sensitive-data-in-input-params"></a>

A: The system automatically masks sensitive fields in the request Headers: common key fields (such as `Authorization` and `X-API-Key`) and all fields supplied by contact credentials are replaced with `***` when displayed. Input parameters and the request Body are not currently masked automatically. If your tool handles other sensitive data (such as customer personal information), we recommend:

1. Avoid having the AI pass keys or personal information directly in the tool's input parameters; supply sensitive values through request Headers or contact credentials instead
2. Control who can view execution records, and authorize only the necessary people
3. In private deployment environments, you can use the `TOOL_API_SENSITIVE_HEADERS` environment variable to extend the Header fields to be masked (for example, `x-functions-key`)

### Q: Can I re-run a failed tool call? <a href="#faq-retry-failed-tool-call" id="faq-retry-failed-tool-call"></a>

A: The system currently does not support directly re-running historical records. If you need to test a tool, we recommend:

1. Ask a question directly on the conversation platform to trigger the tool call
2. Use the tool testing feature (if available)
3. Fix the problem and wait for a real user to trigger it

### Q: How can I see which tools were called in a conversation? <a href="#faq-view-tools-used-in-conversation" id="faq-view-tools-used-in-conversation"></a>

A: There are two ways:

1. **From the conversation record**: The conversation details show all tools called in that conversation
2. **From the tool records**: Click the "Related conversation" link in tool execution records

## Best Practices <a href="#best-practices" id="best-practices"></a>

### Regular Check Recommendations <a href="#regular-check-recommendations" id="regular-check-recommendations"></a>

* **Daily check**: Review failed records from the past 24 hours to make sure key tools are working properly
* **Weekly review**: Tally each tool's call count and success rate to identify items that need optimization
* **Monthly analysis**: Export a complete report and analyze long-term trends and usage patterns

### Alert Setup Recommendations <a href="#alert-setup-recommendations" id="alert-setup-recommendations"></a>

We recommend setting up the following alerts (if supported by the system):

* A tool fails more than 10 times within 1 hour
* A tool's success rate falls below 80%
* A tool's average execution time exceeds 10 seconds
* A tool has not been used for more than 7 days (check whether it is still needed)

### Documentation Recommendations <a href="#documentation-recommendations" id="documentation-recommendations"></a>

Create usage documentation for each tool that records:

* The tool's purpose and applicable scenarios
* Input parameter descriptions and examples
* Expected output format
* Common errors and how to resolve them
* Optimization history


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/agent-ops/tool-execution-records.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.