The Art of Tool Design
ACI: Agent-Computer Interface
HCI (Human-Computer Interaction) has been studied for decades, but the interaction between Agents and computers (ACI) is just getting started. Practical experience shows that the quality of tool design directly determines an Agent's capability ceiling.
Core Concept: Tools Are the Contract Between Agent and World
In traditional software development, we invest heavily in designing user interfaces (HCI): where to place buttons, how to write copy, how interactions should respond. But when an Agent becomes the user of a system, the interface becomes the tool definition. The tool's name, parameters, and description are the Agent's user interface.
HCI Human → System
Humans interact with systems through buttons, forms, and menus. The quality of UI design directly impacts user experience.
User clicks "Check Weather" button
→ System calls getWeather("NYC")
→ Returns result to user
Deterministic: same action → same result
ACI Agent → System
Agents interact with systems through tool definitions (name, parameters, description). The quality of tool design directly impacts Agent performance.
User says: "Should I bring an umbrella?"
→ Agent thinks: do I need the weather tool?
→ First asks: which city are you in?
→ Calls get_weather(city="Shanghai")
→ Makes holistic judgment and responds
Non-deterministic: same question → different call paths
"Plan to invest as much effort into your Agent-Computer Interface (ACI) as you would into a Human-Computer Interface (HCI)."
The Fundamental Difference Between Tools and Traditional APIs
When a user says "Should I bring an umbrella?", the Agent's decision process
1
Where is the user?
If no location is mentioned in conversation history, the Agent may first ask "Which city are you in?" before deciding whether to call the tool.
2
Does it need to call the weather tool?
If the weather was just checked in the previous turn, the Agent may answer directly using cached results, skipping the tool call.
3
Which tool should it call?
Use get_weather or get_forecast? Current conditions vs. future forecast — the tool name and description determine the Agent's choice.
4
How to fill in the parameters?
Should the city parameter be "Shanghai" or "上海"? When the format is unclear, Agents frequently make mistakes.
Traditional APIs are deterministic: a developer writes
getWeather("NYC") and the execution path is identical every time. Agent tools are non-deterministic: the model needs to understand when and how to use them — which depends entirely on the quality of the tool's design.
Four Principles of Tool Design
PRINCIPLE 01
Give the model enough Token space to think clearly
The model generates parameters token by token, and once it starts writing it is hard to go back. Tool design should let the model write simple directional parameters before tackling complex ones.
Anti-pattern: The first parameter requires a 500-line code patch
Best practice: Write file_path first, then change_type, and finally content
Best practice: Write file_path first, then change_type, and finally content
PRINCIPLE 02
Formats should match the model's training data
The model has seen large amounts of natural language and common code formats during training. The closer the tool parameter format is to these familiar patterns, the less likely the model is to make mistakes.
Anti-pattern: Using a custom DSL to describe file changes
Best practice: Use standard unified diff format — the model has seen it countless times in training data
Best practice: Use standard unified diff format — the model has seen it countless times in training data
PRINCIPLE 03
Avoid unnecessary formatting overhead
Don't ask the model to count lines or handle JSON escaping. Models are not good at precise counting — forcing them to do so only increases error rates.
Anti-pattern: Requiring exact line numbers like
Best practice: Use unique surrounding context strings to identify target locations
{"start_line": 15, "end_line": 23}Best practice: Use unique surrounding context strings to identify target locations
PRINCIPLE 04
Poka-yoke (Mistake-proofing)
A concept from the Toyota Production System: redesign to make errors harder to occur. Rather than hoping the model won't make mistakes, design tools that are inherently difficult to misuse.
Anti-pattern: Parameters accepting relative paths (the model frequently gets the working directory wrong)
Best practice: Only accept absolute paths, eliminating ambiguity at the source
Best practice: Only accept absolute paths, eliminating ambiguity at the source
Real Case: A Change in SWE-bench
File Path: Relative Path vs. Absolute Path
BEFORE -- Relative Path
{
"tool": "edit_file",
"path": "src/utils/helper.py",
"content": "..."
}
The Agent frequently got the working directory wrong, causing edits to the wrong file or file-not-found errors
AFTER -- Absolute Path
{
"tool": "edit_file",
"path": "/repo/src/utils/helper.py",
"content": "..."
}
Path ambiguity eliminated; tool calls went from frequent errors to nearly flawless
The code change itself was tiny: simply switching a parameter from accepting relative paths to requiring absolute paths. But the effect was enormous: a single parameter design change dramatically improved the entire Agent's reliability. That is the power of poka-yoke.
The Art of Writing Tool Descriptions
Industry best practice recommends writing tool descriptions as if you are documenting for a smart but context-free junior developer. This developer knows nothing about the system but learns quickly — you need to tell them every prerequisite.
A good tool description should include
Usage examples: Concrete input/output samples that let the model understand at a glance
Edge case handling: What to do when input is empty? What is returned when no result is found?
Input format requirements: ISO 8601 or Unix timestamp for dates? Absolute or relative paths?
Differences from other tools: "Use search_code to search code, use search_files to search filenames — don't mix them up"
When NOT to use this tool: "If you only need to check whether a file exists, use file_exists; reserve read_file for when you need to read the content"
Tool Description Comparison
Poor tool description
{
"name": "search",
"description": "Search for things"
}
The model doesn't know what to search (code? files? web pages?), the parameter format is unclear, and it can't be distinguished from other search tools
Good tool description
{
"name": "search_code",
"description": "Search for code patterns
across the repository using
regex. Returns matching file
paths and line numbers.
Use search_files for filename
matching instead.
Example: search_code({
pattern: 'def process_',
file_glob: '*.py'
})"
}
Precise name, clear description, includes examples, and clarifies boundaries with other tools
Tool design deserves as much investment as Prompt engineering. Tool names, parameter structure, and description copy are all part of the Agent's user interface. A single parameter change can turn an unreliable Agent into a dependable one — as demonstrated by the absolute path case in SWE-bench.