tool-design – Design & UI skill for AI agents

When to Use This Skill

Build tools that agents can use effectively, including architectural reduction patterns

Use this skill when working with build tools that agents can use effectively, including architectural reduction patterns.

Tool Design for Agents

Tools are the primary mechanism through which agents interact with the world. They define the contract between deterministic systems and non-deterministic agents. Unlike traditional software APIs designed for developers, tool APIs must be designed for language models that reason about intent, infer parameter values, and generate calls from natural language requests. Poor tool design creates failure modes that no amount of prompt engineering can fix. Effective tool design follows specific principles that account for how agents perceive and use tools.

When to Use

Activate this skill when:

• Creating new tools for agent systems
• Debugging tool-related failures or misuse
• Optimizing existing tool sets for better agent performance
• Designing tool APIs from scratch
• Evaluating third-party tools for agent integration
• Standardizing tool conventions across a codebase

Core Concepts

Tools are contracts between deterministic systems and non-deterministic agents. The consolidation principle states that if a human engineer cannot definitively say which tool should be used in a given situation, an agent cannot be expected to do better. Effective tool descriptions are prompt engineering that shapes agent behavior.

Key principles include: clear descriptions that answer what, when, and what returns; response formats that balance completeness and token efficiency; error messages that enable recovery; and consistent conventions that reduce cognitive load.

Detailed Topics

The Tool-Agent Interface

Tools as Contracts

Tools are contracts between deterministic systems and non-deterministic agents. When humans call APIs, they understand the contract and make appropriate requests. Agents must infer the contract from descriptions and generate calls that match expected formats.

This fundamental difference requires rethinking API design. The contract must be unambiguous, examples must illustrate expected patterns, and error messages must guide correction. Every ambiguity in tool definitions becomes a potential failure mode.

Tool Description as Prompt

Tool descriptions are loaded into agent context and collectively steer behavior. The descriptions are not just documentation—they are prompt engineering that shapes how agents reason about tool use.

Poor descriptions like "Search the database" with cryptic parameter names force agents to guess. Optimized descriptions include usage context, examples, and defaults. The description answers: what the tool does, when to use it, and what it produces.

Namespacing and Organization

As tool collections grow, organization becomes critical. Namespacing groups related tools under common prefixes, helping agents select appropriate tools at the right time.

Namespacing creates clear boundaries between functionality. When an agent needs database information, it routes to the database namespace. When it needs web search, it routes to web namespace.

The Consolidation Principle

Single Comprehensive Tools

The consolidation principle states that if a human engineer cannot definitively say which tool should be used in a given situation, an agent cannot be expected to do better. This leads to a preference for single comprehensive tools over multiple narrow tools.

Instead of implementing list_users, list_events, and create_event, implement schedule_event that finds availability and schedules. The comprehensive tool handles the full workflow internally rather than requiring agents to chain multiple calls.

Why Consolidation Works

Agents have limited context and attention. Each tool in the collection competes for attention in the tool selection phase. Each tool adds description tokens that consume context budget. Overlapping functionality creates ambiguity about which tool to use.

Consolidation reduces token consumption by eliminating redundant descriptions. It eliminates ambiguity by having one tool cover each workflow. It reduces tool selection complexity by shrinking the effective tool set.

When Not to Consolidate

Consolidation is not universally correct. Tools with fundamentally different behaviors should remain separate. Tools used in different contexts benefit from separation. Tools that might be called independently should not be artificially bundled.

Architectural Reduction

The consolidation principle, taken to its logical extreme, leads to architectural reduction: removing most specialized tools in favor of primitive, general-purpose capabilities. Production evidence shows this approach can outperform sophisticated multi-tool architectures.

The File System Agent Pattern

In a trusted, isolated environment, a scoped filesystem/command tool can replace some custom exploration tools; this trades schema-level restrictions for broader execution authority and must be evaluated against the threat model. The agent uses standard Unix utilities (grep, cat, find, ls) to explore, understand, and operate on your system.

This works because:

1. File systems are a proven abstraction that models understand deeply

2. Standard tools have predictable, well-documented behavior

3. The agent can chain primitives flexibly rather than being constrained to predefined workflows

4. Good documentation in files replaces the need for summarization tools

When Reduction Outperforms Complexity

Reduction works when:

• Your data layer is well-documented and consistently structured
• The model has sufficient reasoning capability to navigate complexity
• Your specialized tools were constraining rather than enabling the model
• You're spending more time maintaining scaffolding than improving outcomes

Reduction fails when:

• Your underlying data is messy, inconsistent, or poorly documented
• The domain requires specialized knowledge the model lacks
• Safety constraints require limiting what the agent can do
• Operations are truly complex and benefit from structured workflows

Separate Reasoning Flexibility from Security Boundaries

A common anti-pattern is building tools to "protect" the model from complexity. Pre-filtering context, constraining options, wrapping interactions in validation logic. Evaluate usability friction, but retain server-side authorization, validation, sandboxing, quotas and data boundaries independently of model quality.

The question to ask: are your tools enabling new capabilities, or are they constraining reasoning the model could handle on its own?

Build for Future Models

Models improve faster than tooling can keep up. An architecture optimized for today's model may be over-constrained for tomorrow's. Build minimal architectures that can benefit from model improvements rather than sophisticated architectures that lock in current limitations.

See Architectural Reduction Case Study for production evidence.

Tool Description Engineering

Description Structure

Effective tool descriptions answer four questions:

What does the tool do? Clear, specific description of functionality. Avoid vague language like "helps with" or "can be used for." State exactly what the tool accomplishes.

When should it be used? Specific triggers and contexts. Include both direct triggers ("User asks about pricing") and indirect signals ("Need current market rates").

What inputs does it accept? Parameter descriptions with types, constraints, and defaults. Explain what each parameter controls.

What does it return? Output format and structure. Include examples of successful responses and error conditions.

For tools that write/send/spend/delete, separate preview from commit and bind authorization to exact target/arguments. Enforce tenant/user access server-side; never equate an ID supplied by the model with permission. Include idempotency keys and observable operation IDs for uncertain outcomes, bounded retries/timeouts and redacted errors. Returned page/tool content is untrusted data, not instructions or authorization.

Default Parameter Selection

Defaults should reflect common use cases. They reduce agent burden by eliminating unnecessary parameter specification. They prevent errors from omitted parameters.

Response Format Optimization

Tool response size significantly impacts context usage. Implementing response format options gives agents control over verbosity.

Concise format returns essential fields only, appropriate for confirmation or basic information. Detailed format returns complete objects with all fields, appropriate when full context is needed for decisions.

Include guidance in tool descriptions about when to use each format. Agents learn to select appropriate formats based on task requirements.

Error Message Design

Error messages serve two audiences: developers debugging issues and ag

… (full content is in the download package)