# Tool Design

> This skill should be used when designing, creating, or refactoring agent tools and descriptions. Focuses on architectural reduction, consolidation, and reliability using MCP standards.

- Skill: `futurediffusion/tool-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add futurediffusion/tool-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/futurediffusion/tool-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: futurediffusion (https://skillmd.com/u/futurediffusion)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/futurediffusion/tool-design

---


# Tool Design Skill

Optimize the interface between deterministic systems and non-deterministic agents. This skill focuses on the "Architectural Reduction" principle to improve model reliability and reduce context bloat.

## Core Principles

### 1. The Consolidation Principle
Reduce tool count and ambiguity. Fewer, more capable tools outperform many granular ones.
- **Merge Coupled Steps**: Combine dependent actions (e.g., `validate` + `execute`) into a single intent-based tool.
- **Reduce Search Space**: Minimizing the number of available tools reduces the probability of selection errors.

### 2. Tools as Contracts
Strict typing and clear error handling ensure predictable behavior.
- **Schema-First**: Define precise inputs using JSON Schema or equivalent.
- **Contextual Errors**: Return actionable failure reasons and correction hints to enable agent self-correction.

### 3. Response Optimization
Manage tool output volume to preserve the context window.
- **Verbosity Control**: Include parameters to specify detail levels (e.g., `summary` vs `full`).
- **Signal-to-Noise**: Strip boilerplate and redundant metadata from results.

### 4. Semantic Clarity
Names and descriptions dictate selection accuracy.
- **Action-Object Naming**: Use clear `verb_noun` conventions (e.g., `fetch_record`).
- **Effect-Based Descriptions**: Explain *when* to use the tool and what its side effects are.

## When to Activate
- Creating new tools or MCP servers.
- Refactoring "confused" agents with high tool-count environments.
- Optimizing token usage for tool-heavy workflows.

---
*Inspired by the Agent Skills for Context Engineering collection.*