Skip to content
Get packs

Tool Design for Agents

Write clear tool descriptions, schemas, and error messages so agents pick and call tools correctly

Source Download skill
Repository
muratcankoylan/Agent-Skills-for-Context-Engineering
Stars
18,282
Licence
MIT
Files
4 files

What it does

When installed, the agent gets guidance for designing the tools it or your software exposes to AI models: writing descriptions the agent can choose from, defining parameter formats, naming conventions, error messages that help the agent recover, and deciding when to merge overlapping tools into fewer ones. It also includes a Python helper script for generating tool descriptions, scoring descriptions for vagueness, and producing error message templates. It points work about overall project structure or sub-agents to other skills.

Great for

  • Developers building agents or MCP servers who see the agent picking the wrong tool or making malformed calls
  • Teams with a growing catalog of overlapping tools who want to consolidate them
  • Engineers reviewing third-party tools before adding them to an agent's toolset

Skip it if

  • Non-technical users with no tool-based agent to configure: the guidance assumes you are building tool interfaces
  • Project-level decisions such as pipeline architecture or whether to use sub-agents: the skill explicitly routes these elsewhere, so it will not answer them well

Try asking

  • “Rewrite these five overlapping tool descriptions so the agent can tell which one to call”
  • “Review my MCP server's tool names and parameters and suggest consolidation”
  • “Generate actionable error messages for my customer lookup tool so the agent can self-correct”
  • “Score this tool description for vague or incomplete wording”
Step-by-step guide: how to use Tool Design for AgentsInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 4 original files, the MIT licence and an attribution note.

    tool-design.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip tool-design.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip tool-design.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Give the skill your actual tool definitions or catalog so it can judge overlap and naming against real examples
  • Run the evaluator script on drafted descriptions as a quick check, but treat its scores as heuristics, not a standard
  • Read the Python script before running it, since the agent will execute scripts it contains

What's inside

  • references/architectural_reduction.md
  • references/best_practices.md
  • scripts/description_generator.py
  • SKILL.md

Redistributed unmodified from muratcankoylan/Agent-Skills-for-Context-Engineering under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.