tool-design

Tool Design - AI Agent Tool Design Guide

Skill Overview

Tool Design is a tool-design methodology specifically for AI agent developers. It helps you build tool APIs that agents can use efficiently, covering complete design patterns—from integration principles to architectural simplification.

Applicable Scenarios

1. Creating an Agent Tool System

When you need to design callable tools for AI agents such as Claude and GPT, this skill provides a complete design framework. Unlike traditional APIs aimed at developers, agent tools must account for how language models understand intent, infer parameter values, and generate calls. With the design principles in this skill, you can avoid common tool-design pitfalls and ensure your agent can correctly understand and use your tools.

2. Optimizing an Existing Tool Set

If you find that agents frequently call the wrong tools, cannot correctly interpret tool descriptions, or have a low tool-calling success rate, this skill can help you diagnose the issues and provide optimization plans. Concrete methods include rewriting tool descriptions, optimizing parameter names, and improving error messages. In real-world tests, it can reduce task completion time by 40%.

3. MCP Tool Integration Development

When developing tools with Model Context Protocol (MCP), you must follow specific naming conventions (such as the ServerName:tool_name format). This skill details MCP tool naming requirements, standards for writing descriptions, and how to avoid tool-targeting problems in multi-server environments.

Core Capabilities

1. Integration Principles and Architectural Simplification

The integration principle states: If even human engineers cannot determine which tool to use in a given situation, then an agent is unlikely to do better. This skill teaches you how to integrate multiple narrow tools into a single comprehensive tool, reducing the agent’s burden of choosing.

Architectural simplification pushes this principle to the extreme: replace most specialized tools with raw general capabilities. For example, instead of building multiple specialized tools such as data exploration, pattern finding, and query validation, provide a single command-execution tool—allowing the agent to freely explore using standard Unix tools (grep, cat, find, ls). Production evidence shows that this minimalist architecture can outperform complex multi-tool designs.

2. Tool Description Engineering

A tool description is essentially a form of prompt engineering and directly affects an agent’s behavior. This skill provides description structure templates to ensure answers to four key questions:

It also covers practical techniques such as response-format optimization (concise/detailed modes), error-message design (so the agent can recover), and sensible default parameter choices.

3. Organizing and Testing Tool Collections

As the number of tools grows, organization becomes critical. This skill guides you to:

It also provides agent-driven tool optimization methods: have the agent attempt to use the tools, collect failure modes, and then analyze and improve the descriptions. This feedback loop can continuously enhance tool usability.

Common Questions

How are agent tools different from traditional APIs?

Traditional APIs are designed for human developers. After reading the documentation, developers understand the contract and call it correctly. Agent tools are designed for language models: the model must infer the contract from the description and generate calls that match the expected format. This fundamental difference means tool design must be reconsidered: the contract must be unambiguous, descriptions must include usage context, and error messages must guide correction. Any ambiguity in a tool definition can become a failure mode for the agent.

How do I write effective tool descriptions?

Effective tool descriptions should answer four questions: what the tool does, when to use it, what input it accepts, and what it returns. Avoid vague language like “help” or “can be used for,” and instead precisely describe what the tool does. Include specific usage triggers (e.g., “when the user asks about pricing”) and parameter constraints (e.g., a format like “xxxx-xxxx”). More importantly, the description is part of prompt engineering and directly influences the agent’s behavior and choice of actions.

What is the tool integration principle, and when should it be used?

The integration principle states: when multiple tools have overlapping functions or must work together, they should be integrated into a single comprehensive tool. For example, instead of separately implementing list_users, list_events, and create_event, implement a schedule_event tool that internally handles finding availability and scheduling the event end to end. Integration can reduce token consumption, eliminate ambiguity, and lower selection complexity. But integration is not a cure-all: tools with fundamentally different behaviors should be separated, and tools used in different contexts should also be separated.

What are the requirements for MCP tool naming?

When using MCP (Model Context Protocol) tools, you must always use fully qualified names ServerName:tool_name to avoid “tool not found” errors. For example: "Use the BigQuery:bigquery_schema tool" is correct, while "Use the bigquery_schema tool" may fail in a multi-server environment. Establish a naming convention that includes server context in all tool references.

In what scenarios does the architectural simplification pattern apply?

Architectural simplification (removing most specialized tools and using raw general capabilities) works best when: the data-layer documentation is complete and consistently structured, the model has sufficient reasoning ability, specialized tools actually constrain rather than empower the model, and the time spent maintaining scaffolding is more than the time spent improving results. It will fail when: the underlying data is messy or inconsistent, the domain requires specialized knowledge the model lacks, security constraints must limit agent actions, or the operations are truly complex and benefit from structured workflows.

How do I test whether agent tool design is effective?

Test by presenting representative requests to the agent and evaluating the generated tool calls. Evaluation criteria include: unambiguity (does the agent choose the correct tool), completeness (does the description include all necessary information), recoverability (do error messages guide correction), efficiency (is the response format optimized for token usage), and consistency (are naming and structure unified). You can also use the agent itself to optimize tools: have it attempt to use the tools, collect failure cases, analyze the problems, and improve the descriptions.