Design Agent Tools for Effective Interaction

This skill covers designing tools for AI agents as a distinct discipline from traditional developer-facing API design, since agents infer contracts from natural-language descriptions rather than reading documentation like a human engineer would. Its central idea is the consolidation principle: if a human engineer can't definitively say which tool applies in a given situation, an agent can't be expected to do better - so a single comprehensive tool (e.g. schedule_event that finds availability and books it) usually beats several narrow ones (list_users, list_events, create_event) that force the agent to chain calls and create selection ambiguity, though it explicitly notes consolidation isn't universal - fundamentally different behaviors or independently-callable actions should stay separate.

Taken further, it describes architectural reduction: replacing specialized tools with primitive, general-purpose ones (the "file system agent pattern," giving an agent direct shell access to grep/cat/find/ls instead of custom data-exploration tools), which works when the underlying data is well-documented and the model is capable enough to navigate it, and fails when data is messy, the domain needs specialized knowledge, or safety constraints require limiting agent actions. It covers tool description engineering (answering what/when/what-inputs/what-returns, avoiding vague language and cryptic parameter names), response format options (concise vs detailed, to manage context/token budget), actionable error message design for agent recovery, consistent naming conventions (verb-noun tool names), a 10-20 tool guideline per collection with namespacing beyond that, and the requirement to use fully-qualified ServerName:tool_name references for MCP tools to avoid "tool not found" errors across multiple servers. It also describes a feedback-loop pattern where an agent analyzes its own tool-use failures and proposes improved descriptions, reporting a 40% reduction in task completion time in production testing.

Use this skill when creating new tools for agent systems, debugging tool-related failures or misuse, optimizing an existing tool set, designing a tool API from scratch, evaluating third-party tools for agent integration, or standardizing tool naming/conventions across a codebase.

It is specifically about the agent-tool interface - it connects to but doesn't replace context-fundamentals (how tools interact with context) or multi-agent-patterns (specialized tools per agent); use those for those adjacent concerns.

Input is a tool or tool collection being designed, debugged, or evaluated for agent use - a vague existing description, an ambiguous parameter set, or a proposed new tool. Output is a well-formed tool specification (or refactor decision) following the described-in-four-questions pattern, with consolidation applied where it reduces ambiguity, actionable error messages, and consistent naming - illustrated with a concrete good example (get_customer, with clear usage triggers, typed parameters, and documented error codes) against a concrete bad one (search(query) with no context, format, or error handling).

References the Model Context Protocol (MCP) naming convention (ServerName:tool_name), and cross-links to companion skills context-fundamentals and evaluation, plus external references including MCP documentation and a Vercel d0 agent architecture case study.

Engineers building tools, MCP servers, or tool collections for AI agents who need the tool descriptions and API shape themselves to carry the reasoning load, rather than relying on prompt engineering to compensate for ambiguous tool design.