Back to series
· 13 min read

Tool Calling and Tool Execution Mechanisms


I. What Is Tool Calling?

Tool Calling refers to the large model determining, based on the current task and the available tool definitions, whether an external capability needs to be invoked, and generating a call request that conforms to the specified structure, with the actual operation carried out by the Agent Runtime or the tool execution engine.

The large model itself is mainly responsible for understanding, reasoning, and generating content; it does not inherently possess the ability to directly access databases, execute code, call APIs, or operate a browser.

Tool Calling provides the model with a controlled mechanism for invoking external capabilities.

For example, a user asks:

Check today's weather in Beijing and determine whether it is suitable for outdoor running.

The Agent may need to call two tools:

  • Weather query tool: retrieves the current weather, temperature, humidity, and wind speed.
  • Weather analysis tool: evaluates whether outdoor exercise is suitable based on the weather conditions.

The whole process involves model decision-making, argument generation, tool invocation, result return, and subsequent reasoning.

1. Core Components of Tool Calling

Component Responsibility
Tool Definition Defines the tool name, description, and parameter structure
Tool Registry Registers and manages available tools
Tool Selection Determines which tool should be called
Argument Generation Generates the arguments for the tool call
Argument Validation Validates the legitimacy of the arguments
Permission Check Checks invocation permissions
Tool Executor Performs the actual tool operations
Result Handler Processes the results returned by the tool
Agent Runtime Manages the entire invocation lifecycle

Two concepts need to be distinguished:

  • Tool Calling: the model decides which tool to call and what arguments to generate.
  • Tool Execution: the runtime actually executes the tool and handles the execution result.

The model generating a call request does not mean the tool has been executed successfully.

II. The Overall Workflow of Tool Calling

A typical tool calling process can be divided into the following stages:

  1. Register tools: provide the tool definitions to the model and the runtime.
  2. User input: receive the user's task.
  3. Tool selection: the model determines whether a tool needs to be called.
  4. Argument generation: the model generates structured arguments.
  5. Request validation: verify the tool name, argument format, and business constraints.
  6. Permission check: confirm whether the current user and Agent have the right to execute.
  7. Tool execution: call APIs, databases, code execution environments, etc.
  8. Result handling: parse the return value and handle exceptions and timeouts.
  9. Result feedback: pass the tool result back to the model.
  10. Subsequent reasoning: the model continues execution or generates the final answer based on the result.

1. Complete Invocation Flow

flowchart TD
    A["User submits task"] --> B["Agent Runtime"]
    B --> C["Build model context"]
    C --> D["LLM inference"]
    D --> E{"Is a tool call needed?"}
    E -->|"No"| F["Generate final answer"]
    E -->|"Yes"| G["Generate Tool Call"]
    G --> H["Parse tool name and arguments"]
    H --> I["Argument schema validation"]
    I --> J{"Are arguments valid?"}
    J -->|"No"| K["Return argument error"]
    K --> D
    J -->|"Yes"| L["Permission and safety check"]
    L --> M{"Is execution allowed?"}
    M -->|"No"| N["Reject the call or request approval"]
    M -->|"Yes"| O["Tool Executor"]
    O --> P["Execute external tool"]
    P --> Q["Process tool result"]
    Q --> R["Tool Result"]
    R --> S["Write into conversation context"]
    S --> D

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#EAF3EC,stroke:#83A995,color:#315D49
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style E fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style F fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style G fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style H fill:#EAF3EC,stroke:#83A995,color:#315D49
    style I fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style J fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style K fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style L fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style M fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style N fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style O fill:#EAF3EC,stroke:#83A995,color:#315D49
    style P fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style Q fill:#EAF3EC,stroke:#83A995,color:#315D49
    style R fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style S fill:#E0F0FE,stroke:#93BCE8,color:#1E4976

The most important point here is this: the LLM is responsible for generating the intent to call a tool and its arguments, the Agent Runtime is responsible for parsing and scheduling, and the Tool Executor is responsible for actually executing it.

Separating these three responsibilities prevents content generated by the model from being treated directly as trusted operational instructions.

3. Tool Definition

The model needs to know which tools are currently available, along with what each tool does and what parameters it requires.

Therefore, the Agent needs to provide standardized definitions for its tools.

A tool typically includes:

  • name: the tool name.
  • description: a description of what the tool does.
  • parameters: the parameter structure.
  • required: required parameters.
  • returns: the structure of the returned data.
  • permissions: the permissions required to call it.
  • timeout: the execution timeout.

1. Tool definition example

Suppose we need to define a weather query tool:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Query weather information for a specified city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "City name"
        },
        "date": {
          "type": "string",
          "description": "Query date, in YYYY-MM-DD format"
        }
      },
      "required": [
        "city"
      ],
      "additionalProperties": false
    }
  }
}

Such definitions usually describe parameter structures in a JSON Schema style.

Where:

Field Meaning
type Parameter data type
properties Parameter field definitions
required Required fields
description Field semantic description
enum Restrict allowed values
additionalProperties Whether extra fields are allowed

2. Why Is a Schema Needed?

If the model is only given:

You can query the weather.

Although the model knows what the tool does, it cannot reliably determine the structure of the call parameters.

With a schema, the model can generate structured parameters based on the definition:

{
  "city": "Beijing",
  "date": "2026-11-20"
}

Schemas mainly address structural constraints; they do not mean the parameters are necessarily correct at the business level.

For example:

{
  "city": "Nonexistent City"
}

This parameter meets the string type requirement, but it may fail real business validation.

Therefore, parameter validation usually needs to be divided into multiple levels:

  1. Syntax validation: whether the JSON can be parsed correctly.
  2. Schema validation: whether fields, types, and required items match the definition.
  3. Semantic validation: whether the meaning of the parameters is reasonable.
  4. Business validation: whether specific business rules are satisfied.
  5. Permission validation: whether the current caller is authorized to use these parameters.

4. How Does the Model Select Tools?

Tool Selection is one of the most critical decision-making steps in Tool Calling.

After receiving the user task and tool definitions, the model needs to determine:

  • Whether the current task requires external capabilities.
  • Which tool is best suited to the current task.
  • Whether multiple tools need to be called.
  • What the tool call order should be.
  • Whether more information needs to be collected first.

1. Basic Mechanism of Tool Selection

Suppose the system provides the following tools:

Tool Function
get_weather Query weather
search_web Search the web
query_database Query database
send_email Send email
execute_python Execute Python code

The user asks:

Check today's weather in Beijing.

The model selects get_weather based on the task semantics.

The user asks:

Query the sales for the last three months and calculate the monthly growth rate.

The model may need to call a database query tool and a Python data analysis tool in sequence.

Tool selection is not necessarily simple keyword matching; rather, it is a judgment made by combining tool descriptions, parameter structures, context, and the current task state.

2. Tool Selection Strategies

Common strategies include:

Model-driven selection

The LLM makes the selection autonomously based on tool definitions.

Its advantages are strong semantic understanding and suitability for complex and open-ended tasks.

Its disadvantages are selection errors, parameter errors, and unstable calls.

Rule-driven selection

Tools are selected based on rules, keywords, business routing, or explicit conditions.

For example:

def select_tool(intent):
    if intent == "weather":
        return "get_weather"

    if intent == "database_query":
        return "query_database"

    if intent == "email":
        return "send_email"

    return None

The advantage is high determinism, making it suitable for fixed business scenarios.

The disadvantage is low flexibility, making it hard to cover complex semantics.

Hybrid selection

Rules first filter the scope of tools, and then the LLM selects among the candidate tools.

For example:

User task
   ↓
Intent recognition
   ↓
Rule-based tool filtering
   ↓
LLM selects candidate tools
   ↓
Parameter generation
   ↓
Tool invocation

This approach reduces the selection burden on the model when it faces a large number of tools, and also lowers the probability of incorrect calls.

3. The Problem of Too Many Tools

When an Agent has registered a large number of tools, the following problems may arise:

  • Tool descriptions become too long.
  • Tools overlap in functionality.
  • The model has difficulty choosing.
  • Context token consumption increases.
  • The probability of incorrect tool calls rises.

In engineering practice, you can use tool grouping, on-demand loading, and hierarchical routing.

For example:

Tool Registry
├── Data tools
│   ├── Database query
│   ├── Data cleaning
│   └── Data analysis
├── Search tools
│   ├── Web search
│   └── Document search
├── Communication tools
│   ├── Send email
│   └── Send message
└── System tools
    ├── File operations
    └── Code execution

The Agent can first determine the task domain and then provide the model with the tool definitions for the corresponding category, instead of exposing all tools every time.

V. Data Structure of a Tool Call

When a model generates a tool call, it usually returns a structured call object.

In a generic format:

{
  "id": "call_001",
  "type": "function",
  "function": {
    "name": "get_weather",
    "arguments": {
      "city": "北京",
      "date": "2026-11-20"
    }
  }
}

The actual call format of a model API may differ slightly; for example, some interfaces represent arguments as a JSON string.

1. Tool Call ID

id is used to identify a single tool call.

It is very important, because a single model response may contain multiple tool calls.

After execution completes, the runtime must associate each tool result with its corresponding call ID.

Otherwise, when multiple tools execute in parallel, results may be mismatched.

2. Function Name

name specifies the tool to be executed.

The runtime must not directly execute any arbitrary function name returned by the model; instead, it should look up the registered tool in the Tool Registry.

If the tool does not exist, execution should be refused and a clear error returned.

3. Arguments

arguments are the tool parameters generated by the model.

They must be parsed and validated, and must not be passed directly to the underlying tool.

Pay particular attention to the following:

  • Parameters may be missing.
  • Parameter types may be wrong.
  • Parameters may be outside the allowed range.
  • Parameters may contain extra fields.
  • Parameters may violate business rules.
  • Parameters may contain malicious or untrusted content.

4. Multiple Tool Calls

A single model response may contain multiple tool calls.

For example:

{
  "tool_calls": [
    {
      "id": "call_001",
      "function": {
        "name": "get_weather",
        "arguments": {
          "city": "北京"
        }
      }
    },
    {
      "id": "call_002",
      "function": {
        "name": "get_weather",
        "arguments": {
          "city": "上海"
        }
      }
    }
  ]
}

If two tool calls are independent of each other, they can be executed in parallel.

However, you cannot conclude that calls can safely run in parallel just because the model returned several at once. The runtime still needs to check dependencies, resource limits, and side effects.

VI. Tool Executor: The Tool Execution Engine

The Tool Executor is the core component in the Agent Runtime responsible for actually executing tools.

It receives the Tool Call generated by the model and handles tool lookup, parameter processing, permission validation, call dispatch, and result packaging.

1. Core Responsibilities of the Execution Engine

Module Responsibility
Tool Resolver Look up tools by tool name
Argument Parser Parse invocation arguments
Schema Validator Validate argument structure
Permission Manager Check invocation permissions
Execution Dispatcher Dispatch execution requests
Timeout Controller Manage timeouts
Retry Manager Manage retries
Result Serializer Standardize result format
Error Handler Handle execution exceptions
Audit Logger Record invocation audit information

2. Execution Process

flowchart TD
    A["Receive Tool Call"] --> B["Parse Invocation Object"]
    B --> C["Query Tool Registry"]
    C --> D{"Does the Tool Exist?"}
    D -->|"No"| E["Return TOOL_NOT_FOUND"]
    D -->|"Yes"| F["Parse Arguments"]
    F --> G["Schema Validation"]
    G --> H{"Are the Arguments Valid?"}
    H -->|"No"| I["Return INVALID_ARGUMENT"]
    H -->|"Yes"| J["Permission and Risk Check"]
    J --> K{"Is Execution Allowed?"}
    K -->|"No"| L["Reject the Call or Request Approval"]
    K -->|"Yes"| M["Select Executor"]
    M --> N["Execute Tool"]
    N --> O{"Did Execution Succeed?"}
    O -->|"Yes"| P["Serialize Execution Result"]
    O -->|"No"| Q["Error Classification and Recovery"]
    P --> R["Return Tool Result"]
    Q --> S{"Is Retry Allowed?"}
    S -->|"Yes"| N
    S -->|"No"| T["Wrap Execution Error"]
    T --> R

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#EAF3EC,stroke:#83A995,color:#315D49
    style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style E fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style F fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style G fill:#EAF3EC,stroke:#83A995,color:#315D49
    style H fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style I fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style J fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style K fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style L fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style M fill:#EAF3EC,stroke:#83A995,color:#315D49
    style N fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style O fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style P fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style Q fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style R fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style S fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style T fill:#F7EAE7,stroke:#C98D7C,color:#754438

3. Why Is an Independent Execution Engine Needed?

If tool calls generated by the model are mapped directly to underlying functions, the system will face significant security and stability risks.

For example:

# Not recommended: look up and execute arbitrary functions directly based on model output
tool_name = model_response["name"]
arguments = model_response["arguments"]

globals()[tool_name](**arguments)

This implementation has serious problems:

  • The model may generate unauthorized function names.
  • It may call internal functions that should not be exposed.
  • Parameters are not validated.
  • Missing permission control.
  • No execution timeout.
  • No audit records.
  • Exception handling is not controlled.

The correct approach is to use an explicit registry and allow only pre-registered and authorized tools to be executed.

VII. Tool Registry: Tool Registration and Management

The Tool Registry is responsible for maintaining the set of tools available to the Agent.

A tool registry can be understood as a controlled tool catalog.

Each tool needs a unique identifier and a corresponding execution implementation.

1. Tool Registration Example

from dataclasses import dataclass
from typing import Callable, Any


@dataclass
class Tool:
    name: str
    description: str
    handler: Callable[..., Any]
    permissions: set[str]


class ToolRegistry:
    def __init__(self):
        self.tools = {}

    def register(self, tool: Tool):
        if tool.name in self.tools:
            raise ValueError(
                f"Tool already exists: {tool.name}"
            )

        self.tools[tool.name] = tool

    def get(self, name: str):
        return self.tools.get(name)

    def list_tools(self):
        return list(self.tools.values())

Register a tool:

def get_weather(city: str):
    return {
        "city": city,
        "temperature": 18,
        "condition": "晴"
    }


registry = ToolRegistry()

registry.register(
    Tool(
        name="get_weather",
        description="查询指定城市天气",
        handler=get_weather,
        permissions={"weather:read"}
    )
)

2. Problems the Tool Registry Needs to Solve

A production-grade Tool Registry also needs to consider:

  • Tool name uniqueness.
  • Tool version management.
  • Tool description and Schema management.
  • Tool permission configuration.
  • Tool lifecycle management.
  • Tool health status.
  • Tool call statistics.
  • Dynamic loading and unloading of tools.

Tool definitions and execution implementations should remain consistent.

If the parameter Schema the model sees is inconsistent with the actual tool implementation, it may result in many invalid calls.

VIII. Parameter Parsing and Validation Mechanism

Parameter validation is an important security boundary before tool execution.

Parameters generated by the model must not be treated as trusted input; even though they come from the model, they may contain errors or content that does not conform to business constraints.

1. JSON Parsing

If the parameters returned by the model API are JSON strings, they need to be parsed first:

import json

arguments_text = '{"city": "北京"}'

arguments = json.loads(arguments_text)

When parsing fails, return a clear parameter format error instead of executing the tool directly.

2. Schema Validation

Tools such as JSON Schema or Pydantic can be used to validate the parameter structure.

For example:

from pydantic import BaseModel, Field


class WeatherArgs(BaseModel):
    city: str = Field(min_length=1, max_length=50)
    date: str | None = None

Validation:

args = WeatherArgs.model_validate({
    "city": "北京"
})

If parameter types or constraints do not match the definition, the validation process will throw an exception.

3. Business Validation

Schema can only constrain data structures and cannot fully express business rules.

For example:

def validate_weather_args(args):
    allowed_cities = {
        "北京",
        "上海",
        "深圳",
        "杭州"
    }

    if args.city not in allowed_cities:
        raise ValueError("Unsupported city")

In a real system, structural validation and business validation can be separated to facilitate maintenance and reuse.

4. Parameter Validation Layers

flowchart TD
    A["Model generates parameters"] --> B["JSON parsing"]
    B --> C{"Is JSON valid?"}
    C -->|"No"| D["Format error"]
    C -->|"Yes"| E["Schema validation"]
    E --> F{"Is structure correct?"}
    F -->|"No"| G["Parameter structure error"]
    F -->|"Yes"| H["Semantic validation"]
    H --> I{"Are parameter semantics reasonable?"}
    I -->|"No"| J["Semantic error"]
    I -->|"Yes"| K["Business rule validation"]
    K --> L{"Are business constraints satisfied?"}
    L -->|"No"| M["Business validation failed"]
    L -->|"Yes"| N["Enter execution phase"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style D fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style E fill:#EAF3EC,stroke:#83A995,color:#315D49
    style F fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style G fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style H fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style J fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style K fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style L fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style M fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style N fill:#DCEFE5,stroke:#4F8B70,color:#24563F

9. Tool Execution Results and Model Context

After tool execution completes, the execution engine needs to return the result to the Agent Runtime, which then writes the result into the model context.

The model continues reasoning based on the tool result.

1. Basic Structure of a Tool Result

It is recommended to encapsulate tool results in a uniform structure:

{
  "tool_call_id": "call_001",
  "tool_name": "get_weather",
  "status": "success",
  "data": {
    "city": "北京",
    "temperature": 18,
    "condition": "晴"
  },
  "error": null,
  "metadata": {
    "duration_ms": 120
  }
}

Where:

  • tool_call_id: links to the original tool call.
  • tool_name: identifies the tool that was executed.
  • status: execution status.
  • data: business result.
  • error: error information.
  • metadata: metadata such as execution duration and call count.

Tool results should remain structured as much as possible; avoid concatenating all complex data into a single natural-language paragraph.

2. How Are Tool Results Fed Back to the Model?

Taking a weather query as an example, after the model generates a tool call, the runtime executes the tool and returns the result.

Tool result:

{
  "city": "北京",
  "temperature": 18,
  "condition": "晴",
  "wind_speed": 2
}

The Runtime writes it into the conversation context as a tool response.

After the model receives the result, it can continue to analyze:

  • Whether the weather is suitable for outdoor running.
  • Whether the temperature is appropriate.
  • Whether the wind speed is too high.
  • Whether the user should be reminded to use sun protection or hydrate.

The tool result is not the final answer; it is the input for the model's subsequent reasoning.

3. Closed Loop Between Tool Calls and Model Reasoning

flowchart TD
    A["User Task"] --> B["LLM Inference"]
    B --> C["Generate Tool Call"]
    C --> D["Runtime Executes Tool"]
    D --> E["Obtain Tool Result"]
    E --> F["Write to Model Context"]
    F --> G["LLM Infers Again"]
    G --> H{"Are More Tools Needed?"}
    H -->|"Yes"| C
    H -->|"No"| I["Generate Final Answer"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#EAF3EC,stroke:#83A995,color:#315D49
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style H fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style I fill:#DCEFE5,stroke:#4F8B70,color:#24563F

This is the Tool Calling Loop commonly seen in Agents.

What distinguishes it from ordinary function calling is that the model participates in the decision to call and in judging the follow-up tasks, while tool execution is handled by a controlled runtime.

10. Synchronous, Asynchronous, and Parallel Tool Calls

Different tools have different execution characteristics.

For example:

  • Local computation usually takes a short time to execute.
  • Database queries may need to wait on network and disk operations.
  • Web searches may take several seconds.
  • Processing large files may last several minutes.
  • External tasks may require asynchronous polling to obtain the final result.

Therefore, the tool execution mechanism needs to support different execution modes.

1. Synchronous Calls

A synchronous call means the caller waits for the tool to finish executing before continuing.

def execute_tool(tool, arguments):
    return tool.handler(**arguments)


result = execute_tool(
    weather_tool,
    {"city": "北京"}
)

Suitable for:

  • Tools with short execution times.
  • Local function calls.
  • Simple computations.
  • Operations with clear requirements on response time.

The drawback is that long-running tasks occupy the calling thread or execution resources.

2. Asynchronous Calls

Asynchronous calls allow the program to handle other tasks while waiting for a tool to execute.

import asyncio


async def get_weather(city: str):
    await asyncio.sleep(1)

    return {
        "city": city,
        "temperature": 18
    }


async def main():
    result = await get_weather("北京")
    print(result)


asyncio.run(main())

Suitable for network requests, database access, and other I/O-intensive operations.

Asynchronous does not mean tasks are necessarily executed in parallel. It mainly addresses resource utilization during waiting periods.

3. Parallel Calls

When multiple tool calls do not depend on each other, they can be executed in parallel.

For example, querying the weather in Beijing, Shanghai, and Shenzhen at the same time.

import asyncio


async def get_weather(city):
    await asyncio.sleep(1)

    return {
        "city": city,
        "temperature": 18
    }


async def main():
    cities = ["北京", "上海", "深圳"]

    results = await asyncio.gather(
        *[
            get_weather(city)
            for city in cities
        ]
    )

    print(results)


asyncio.run(main())

The three tasks can wait on their respective I/O operations simultaneously, shortening the overall response time.

4. Prerequisites for Parallel Execution

Before executing in parallel, you must confirm that:

  • There are no data dependencies between the tool calls.
  • There are no unhandled shared-state conflicts.
  • Duplicate writes will not occur.
  • The external API permits the corresponding level of concurrency.
  • System resources are sufficient.
  • Partial success can be handled correctly after a failure.

For example, two tools reading data at the same time is usually fine, but if two tools modify the same record at the same time, you need to consider locking, version control, or transaction mechanisms.

11. Exception Handling During Tool Execution

Tool calls in production environments cannot be guaranteed to succeed every time.

Common exceptions include:

  • Tool does not exist.
  • Invalid argument format.
  • Argument outside the supported business range.
  • Insufficient permissions.
  • Network connection failed.
  • API timeout.
  • Rate limited by an external service.
  • Returned data format is abnormal.
  • Tool executed successfully but the result did not meet expectations.

1. Error classification

It is recommended to use standard error codes:

Error code Meaning Handling
TOOL_NOT_FOUND Tool does not exist Check tool registration
INVALID_ARGUMENT Invalid argument Correct the arguments
PERMISSION_DENIED Insufficient permissions Reject execution or request authorization
TOOL_TIMEOUT Tool timeout Retry according to policy
RATE_LIMITED Request was rate limited Retry after a delay
TOOL_UNAVAILABLE Tool unavailable Switch to a backup tool
EXECUTION_FAILED Execution failed Handle by category
RESULT_INVALID Returned result does not meet requirements Validate or re-execute

2. Exception handling strategies

Retry

Suitable for transient network errors, brief service unavailability, and similar issues.

Fallback

When the primary tool is unavailable, use a backup tool with similar capabilities.