# How Tool Descriptions Are Designed for Optimal LLM Agent Performance

> Learn how to design effective tool descriptions for LLM agents. Use concise phrasing, keywords, and JSON-Schema for optimal accuracy and performance.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: best-practices
- Published: 2026-07-25

---

**Tool descriptions for LLM agents must use concise, action-oriented phrasing with domain-specific keywords and strict JSON-Schema definitions to maximize function-calling accuracy, tool retrieval, and argument validation.**

The `bojieli/ai-agent-book` repository demonstrates how meticulously engineered tool descriptions serve as the primary interface between an LLM's reasoning capabilities and external function execution. In the self-evolving agent implementation, the quality of these descriptions directly determines whether the model can correctly select tools during the *search-tools* phase and generate syntactically valid arguments during function invocation.

## The Three Pillars of Effective Tool Descriptions

According to the source code in [`chapter8/self-evolving-tools/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter8/self-evolving-tools/agent.py), high-performance tool descriptions must satisfy three distinct requirements for optimal LLM reasoning.

### Understanding the Tool's Purpose

Every description begins with a concise, action-oriented sentence that explicitly states what the tool accomplishes. In [`chapter8/self-evolving-tools/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter8/self-evolving-tools/agent.py) (lines 24-31), the `web_search` tool uses the description **"用 DuckDuckGo 搜索网页，返回标题/URL/摘要。用于寻找开源库或公开 API。"** This phrasing tells the LLM both *what* action to take (search the web) and *why* to use it (find libraries or public APIs), eliminating ambiguity during the tool-selection phase.

### Matching User Intent

Descriptions must include keywords that mirror potential user queries. When the agent performs a *search-tools* lookup, it matches terms from the user's prompt against these descriptions. Including verbs like "搜索" (search), "抓取" (fetch), or domain terms like "API" and "库" (library) ensures the retrieval system surfaces the correct tool when users ask related questions.

### Validating Arguments

The description works in tandem with a JSON-Schema parameter definition to reduce hallucination. While the description explains semantic purpose, the schema enforces syntactic constraints. This separation allows the LLM to focus on *what* values to supply rather than *how* to format them, as the schema guarantees structural validity.

## Static vs. Dynamic Tool Description Architecture

The repository implements a dual-layer approach to tool description management, separating core capabilities from dynamically discovered ones.

### Base Tool Schemas (BASE_TOOL_SCHEMAS)

Static tool definitions reside in `BASE_TOOL_SCHEMAS` within [`chapter8/self-evolving-tools/agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter8/self-evolving-tools/agent.py). This list contains the foundational functions available to every agent instance, with each entry structured as:

- `name`: The function identifier
- `description`: A human-readable, search-optimized sentence
- `parameters`: A JSON-Schema object defining required and optional arguments

This static collection ensures consistent baseline capabilities while demonstrating the verb-first, keyword-rich description pattern that all tools should follow.

### Dynamic Tool Creation and Registration

When the agent discovers new capabilities, it registers them via the `create_tool` function (implemented in [`chapter8/self-evolving-tools/tool_manager.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter8/self-evolving-tools/tool_manager.py) and invoked in [`agent.py`](https://github.com/bojieli/ai-agent-book/blob/main/agent.py) lines 69-81). The registration payload requires a `description` field that follows the same optimization principles:

```python

# File: chapter8/self-evolving-tools/agent.py

payload = {
    "name": "get_stock_price",
    "description": "获取指定股票代码的实时价格，返回数值而非字符串。",
    "parameters": {
        "type": "object",
        "properties": {
            "ticker": {"type": "string", "description": "股票代码，如 AAPL"}
        },
        "required": ["ticker"],
    },
    "code": """
def run(**kwargs):
    import yfinance as yf
    ticker = kwargs["ticker"]
    data = yf.Ticker(ticker).info
    return {"price": data["regularMarketPrice"]}
""",
    "test_args": {"ticker": "AAPL"},
}
response = tool_library.create_tool(**payload)

```

The `tool_library` stores these descriptions for later retrieval via `search_tools`, enabling the agent to reuse existing capabilities rather than creating redundant tools.

## Design Patterns for Maximum LLM Compatibility

The repository establishes specific linguistic and structural patterns that align with LLM token-level modeling.

### Verb-First Phrasing

Descriptions begin with action verbs ("搜索网页", "抓取网页", "获取...价格") to explicitly signal the tool's operation type. This pattern matches how LLMs model action sequences, making the tool's intention immediately apparent during the function-calling decision process.

### Domain-Specific Keyword Injection

Effective descriptions embed terminology that users naturally include in their prompts. For example, the stock price tool includes "股票代码" (stock ticker) and "实时价格" (real-time price), ensuring that when a user asks about stock information, the semantic similarity between the query and description triggers the correct tool selection.

### Compact Single-Sentence Structure

The source code consistently uses brief, single-sentence descriptions rather than multi-paragraph explanations. This reduces cognitive load during the LLM's tool-selection heuristic and prevents the model from conflating descriptive text with operational instructions.

### Strict JSON-Schema Consistency

Every tool description pairs with a `parameters` object using standard JSON-Schema syntax. In [`chapter8/self-evolving-tools/tool_manager.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter8/self-evolving-tools/tool_manager.py), the `execute_tool` function relies on this schema to validate arguments before execution, ensuring that the LLM-generated function calls are syntactically valid and type-safe.

## Complete Implementation Examples

### Defining a New Tool with Optimal Description

When creating the `get_stock_price` tool, the description explicitly states the return type to prevent string-numeric confusion:

```python

# File: chapter8/self-evolving-tools/agent.py

NEW_TOOL = {
    "type": "function",
    "function": {
        "name": "get_stock_price",
        "description": "获取指定股票代码的实时价格，返回数值而非字符串。",
        "parameters": {
            "type": "object",
            "properties": {
                "ticker": {"type": "string", "description": "股票代码，如 AAPL"},
            },
            "required": ["ticker"],
        },
    },
}

```

### Searching and Reusing Existing Tools

The `search_tools` function leverages description quality to match queries against available capabilities:

```python

# File: chapter8/self-evolving-tools/agent.py

result = tool_library.search_tools(query="stock price")
if result["count"]:
    tool_name = result["tools"][0]["name"]
    answer = tool_library.execute_tool(tool_name, {"ticker": "AAPL"})

```

This retrieval mechanism depends entirely on the semantic overlap between the user's query ("stock price") and the tool's description ("获取指定股票代码的实时价格").

## Summary

- **Action-oriented descriptions** using verb-first phrasing align with LLM token models and clarify tool purpose.
- **Domain-specific keywords** embedded in descriptions enable accurate retrieval during the `search_tools` phase.
- **JSON-Schema pairing** with descriptions ensures syntactic argument validation, reducing hallucination and execution errors.
- **Static and dynamic registration** via `BASE_TOOL_SCHEMAS` and `create_tool` creates a reusable tool ecosystem.
- **Concise single-sentence structure** minimizes cognitive load and maximizes function-calling accuracy.

## Frequently Asked Questions

### How long should an LLM tool description be?

Tool descriptions should consist of a single, compact sentence—typically 10-20 words. The `bojieli/ai-agent-book` implementation demonstrates that brief descriptions like "用 DuckDuckGo 搜索网页，返回标题/URL/摘要" outperform lengthy paragraphs because they reduce noise during the LLM's tool-selection heuristic while preserving essential semantic keywords.

### Why do tool descriptions need to include specific keywords?

Domain-specific keywords (e.g., "API", "股票代码", "实时价格") bridge the gap between user queries and tool capabilities. When the agent executes `search_tools`, it matches terms from the user's prompt against these descriptions. Without relevant keywords, the retrieval system fails to surface the correct tool, forcing the agent to create redundant functions or return incorrect results.

### What is the relationship between the description and the parameters schema?

The description explains *what* the tool does and *when* to use it, while the JSON-Schema defines *how* to structure the arguments. This separation of concerns allows the LLM to focus on semantic reasoning when selecting tools and syntactic validation when generating calls. In [`chapter8/self-evolving-tools/tool_manager.py`](https://github.com/bojieli/ai-agent-book/blob/main/chapter8/self-evolving-tools/tool_manager.py), the schema enforces type safety during `execute_tool`, while the description drives the initial selection in `search_tools`.

### Should tool descriptions be written in English or the user's native language?

The repository uses Chinese descriptions for Chinese-language agent interactions, demonstrating that descriptions should match the primary language of the expected user queries. Since LLMs process descriptions as semantic tokens during function calling, aligning the language with user prompts maximizes retrieval accuracy and reduces cross-lingual semantic drift.