How to Design Effective Tool Descriptions for AI Agents with Parameter Examples

Effective AI agent tool descriptions combine imperative verb naming, JSON Schema parameter definitions with concrete examples, and operational contracts to enable reliable function calling and autonomous error recovery.

Designing clear tool descriptions is essential for AI agents to invoke functions correctly. The bojieli/ai-agent-book repository demonstrates production-ready patterns for crafting machine-readable specifications that bridge natural language understanding and precise API execution. By following these patterns in tools.py and expanded_catalog.py, developers ensure their agents generate syntactically valid JSON calls and handle edge cases gracefully.

Why Tool Descriptions Matter for AI Agents

A well-crafted tool description serves as the bridge between an AI agent's reasoning and the external functions it can invoke. When descriptions are ambiguous or parameters lack type constraints, models produce hallucinated arguments or invalid JSON structures. The ai-agent-book codebase demonstrates that precise specifications reduce the cognitive load on the language model, allowing it to focus on high-level planning rather than syntax validation.

The repository implements a staged approach where STAGE1_TOOLS, STAGE2_TOOLS, and STAGE3_TOOLS expose only contextually relevant capabilities. This prevents the model from over-searching the toolbox and focuses its planning on appropriate actions for the current workflow phase.

Core Components of an Effective Tool Description

Use Imperative Verbs for Tool Names

Tool names should be short, action-oriented verbs that clearly indicate the operation. In chapter10/staged-system-prompt/tools.py, functions follow the pattern write_file, run_linter, and run_tests. This naming convention gives the model a clear mental model of the capability and prevents ambiguous calls.

The description field must complement the name with a one-sentence purpose starting with "Do..." or equivalent action language. For example, the write_file tool description states: "写入（或覆盖）一个文件的完整内容" (Write or overwrite the complete content of a file).

Define Typed Parameter Schemas

Every parameter requires a JSON Schema definition with explicit typing. The _tool helper function in tools.py constructs schemas where each argument specifies:

• type: Valid JSON Schema types (string, integer, boolean, array, object)
• description: Human-readable explanation of the parameter's purpose
• required: Array listing mandatory parameters

# Excerpt from chapter10/staged-system-prompt/tools.py

_tool(
    "write_file",
    "写入（或覆盖）一个文件的完整内容。",
    {
        "path": {
            "type": "string",
            "description": "文件路径，如 organize_downloads.py"
        },
        "content": {
            "type": "string",
            "description": "文件的完整内容"
        }
    },
    ["path", "content"],
)

This strict typing enables the model to reason about correct data types and produce syntactically valid JSON arguments.

Include Parameter Examples and Constraints

While the schema defines structure, concrete examples guide the model toward valid inputs. The test suite in chapter10/staged-system-prompt/test_official_evidence.py demonstrates realistic values such as path = "x.py". Although the base schema may not embed examples, adding an "example" field or documenting typical values in the description improves robustness.

For complex parameters, document edge-case handling directly in the description: "If path does not exist, the tool returns an error message." This explicit contract helps the agent anticipate failure modes and plan recovery strategies.

Advanced Techniques from the Source Code

Enriching Descriptions with Operational Contracts

The enrich_existing_tools function in chapter4/perception-tools/src/expanded_catalog.py demonstrates how to augment basic descriptions with detailed operational metadata. This pattern appends provenance, expected output formats, and failure conditions to give the agent richer context beyond a one-sentence summary.

# Excerpt from chapter4/perception-tools/src/expanded_catalog.py

tool.description = (
    f"{tool.description.rstrip()}.\n\n"
    f"Operational provenance for {name}: {provenance}. This tool performs the named "
    "operation when called; it does not substitute a cached demonstration or generated "
    f"sample. Successful observations contain {output}. The structured ActionResponse "
    "retains source identifiers, URLs, timestamps, paths, counts, or provider metadata "
    "that the underlying operation actually supplies, so downstream receipts can trace "
    f"the evidence. Tool-specific failure conditions are {failures}."
)

This operational contract enables the agent to decide when a tool is appropriate and trace evidence for downstream verification.

Implementing Stage-Aware Tool Sets

The repository organizes tools into stage-specific constants (STAGE1_TOOLS, STAGE2_TOOLS, STAGE3_TOOLS) defined in the agent logic. When constructing prompts, the system injects only relevant tool definitions:

# Conceptual usage from chapter10/staged-system-prompt/agent.py patterns

prompt = f"""You have the following tools at your disposal:
{json.dumps(STAGE2_TOOLS, ensure_ascii=False, indent=2)}
When you need to create a new file, call `write_file` with appropriate arguments."""

This selective exposure prevents context window pollution and reduces the likelihood of the model selecting inappropriate tools for the current task phase.

Design Checklist for Production Tool Descriptions

Follow this checklist when designing tool descriptions for AI agents:

1. Name it as an imperative verb (create_image, fetch_weather) to indicate action clearly.

2. Write a one-sentence purpose that starts with "Do..." and explains the tool's function unambiguously.

3. Define strict parameter blocks:

   • Use JSON Schema type annotations (string, integer, boolean, array, object)
   • Add human-readable description fields for each parameter
   • Mark required fields explicitly in the required array
   • Include "example" values for complex string formats

4. Document operational details for external service calls: describe provenance, expected success payloads, and failure conditions as implemented in enrich_existing_tools.

5. Keep schemas small (≤ 5 parameters) to reduce combinatorial complexity and prevent argument hallucinations.

6. Specify edge-case handling explicitly, such as behavior when files do not exist or network requests timeout.

Summary

• Use verb-based naming (write_file, run_tests) and concise action descriptions to prevent ambiguous tool selection.
• Implement strict JSON Schema typing with type, description, and required fields to ensure syntactically valid arguments.
• Add operational contracts via description enrichment to document provenance, success formats, and failure modes.
• Organize tools by workflow stage (STAGE1_TOOLS, STAGE2_TOOLS) to focus the agent's context window on relevant capabilities.
• Limit parameter count to five or fewer and include concrete examples to guide the model toward valid inputs.

Frequently Asked Questions

What format should AI agent tool descriptions use?

AI agent tool descriptions should use the OpenAI function-calling JSON Schema format. This specification requires a name, description, and parameters object containing type definitions for each argument. The bojieli/ai-agent-book repository implements this through the _tool helper in tools.py, which constructs valid schemas that language models can parse to generate structured JSON arguments.

How many parameters should an AI agent tool have?

Limit tool descriptions to five or fewer parameters to minimize combinatorial complexity. As demonstrated in the staged system prompt examples, smaller schemas reduce the cognitive load on the model and decrease the probability of hallucinated or malformed arguments. If a function requires more than five inputs, consider splitting it into multiple specialized tools or accepting a configuration object.

Should I include examples in tool parameter descriptions?

Yes, include concrete examples in parameter descriptions or as separate "example" fields in the JSON Schema. The test files in test_official_evidence.py demonstrate how values like path = "x.py" guide the model toward syntactically correct inputs. Examples are particularly important for string formats, file paths, and enum values where the model might otherwise generate plausible but invalid values.

How do I handle optional versus required parameters in AI tool schemas?

Mark required parameters explicitly in the JSON Schema's required array, as shown in the _tool function implementation. Optional parameters should be omitted from this array and may include default values in their descriptions. The repository demonstrates that explicitly distinguishing required fields helps the model avoid omitting critical arguments like path or content in the write_file tool while understanding that certain flags may be optional.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}