skills.rest
TECH-HY
TECH-HYOFFICIAL
Explore all skills by this author →
GitHub

tool-design

Designs agent tool interfaces using consolidation, description engineering, and MCP naming conventions.

Updated Mar 22, 2026
Search Tags:#prompt engineering#api design#mcp#tool design#agent tools#tool consolidation#llm agents
One-click install
npx skills add https://github.com/TECH-HY/SKILLS --skill tool-design-tech-hy
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: tool-design
Source: https://github.com/TECH-HY/SKILLS/tree/main/skills/tool-design
Command: npx skills add https://github.com/TECH-HY/SKILLS --skill tool-design-tech-hy

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Poorly designed agent tools create failure modes that prompt engineering cannot fix: ambiguous tool selection, cryptic parameters, unrecoverable errors, and bloated tool sets that consume context budget. This Skill provides principles and patterns for designing tool APIs that language models can reliably reason about and call. ## Core Features & Use Cases - Tool Description Engineering: Structures descriptions that answer what a tool does, when to use it, what inputs it accepts, and what it returns, with defaults and examples. - Consolidation & Architectural Reduction: Guides merging narrow tools into comprehensive workflow tools, or replacing specialized tools with primitive general-purpose capabilities like file system access. - MCP Tool Naming & Error Design: Enforces fully qualified ServerName:tool_name conventions and error messages that enable agent recovery. - Use Case: When building an MCP server with multiple database tools, apply this Skill to consolidate overlapping query tools, write unambiguous descriptions, and design actionable error responses. ## Quick Start Use the tool-design skill to review my agent's tool definitions and rewrite the descriptions for clarity and consolidation.

Frequently Asked Questions about tool-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design tools for AI agents?▼

Design agent tools by writing descriptions that answer what the tool does, when to use it, what inputs it accepts, and what it returns. Prefer comprehensive tools covering full workflows over many narrow tools, and include defaults and usage examples.

How many tools should an agent have?▼

A reasonable guideline is 10-20 tools for most applications. Overlapping tool descriptions cause model confusion, so use namespacing to group related tools when more are needed, and consolidate tools with ambiguous boundaries.

How do I name MCP tools correctly?▼

Always use fully qualified MCP tool names in the format ServerName:tool_name, such as BigQuery:bigquery_schema. Without the server prefix, agents may fail with tool-not-found errors when multiple MCP servers are available.

When should I not consolidate agent tools?▼

Avoid consolidation when tools have fundamentally different behaviors, are used in different contexts, or are called independently. Consolidation also fails when underlying data is messy, safety constraints require limits, or workflows genuinely need structure.

Why do agents fail to use my tools correctly?▼

Failures usually come from vague descriptions, cryptic parameter names, missing usage context, and generic error messages. You can use an agent to analyze observed failure modes and propose improved tool descriptions.

Related Skills

Explore More Software Engineering Skills→
LazyNinja435LazyNinja435
1

using-superpowers

Enforce a skill-first invocation protocol for AI agents.

Community
Advanced
DarkCodePEDarkCodePE

agent-harness-construction

Design agent harnesses with deterministic tool usage and standardized observation formatting.

Community
Advanced
CJ-1981CJ-1981

moai-foundation-context

Manage token budgets, session state, and context windows for multi-agent workflows.

Community
Advanced
4shil4shil
1

understand-chat

Generate interactive knowledge graphs from JSON codebase data for analysis.

Community
Intermediate