agent-design

name	agent-design
description	Guidelines for designing tools and action spaces for AI agents. Use when building agent harnesses, designing tool interfaces, creating elicitation mechanisms, or optimizing agent-tool interactions. Covers progressive disclosure, tool design patterns, and lessons from Claude Code development.

Agent Design Guidelines

Overview

Designing tools for AI agents is as much art as science. The key principle: give agents tools shaped to their own abilities — which you discover by paying attention to their outputs.

The Mental Model

Imagine being given a difficult math problem. What tools would you want?

Tool	Limitation
Paper only	Limited by manual calculations
Calculator	Better, but requires knowledge to operate
Computer	Most powerful, but requires coding skills

The right tool depends on your own abilities. Same for agents — design tools that match what the model can actually do well.

Core Principles

1. Claude Must "Like" Calling the Tool

Even the best designed tool doesn't work if Claude doesn't understand how to call it.

• Test if the model naturally uses the tool
• Read outputs to see if it's confused
• Iterate on the interface until it "clicks"

2. Tools That Were Necessary Can Become Constraints

As models improve:

• Old workarounds become unnecessary
• Previous "helps" become limitations
• Constantly revisit assumptions

Example: TodoWrite reminders helped older models but made newer ones think they couldn't modify the list.

3. Progressive Disclosure Over Context Bloat

Instead of stuffing everything in the system prompt:

• Give agents tools to discover context themselves
• Let them search, read, and explore recursively
• Skills can reference other files for nested discovery

4. High Bar for New Tools

More tools = more options to think about = cognitive overhead.

• Claude Code has ~20 tools
• Consider: can this be a subagent? A skill? Progressive disclosure?
• Only add tools when truly necessary

Design Patterns

Pattern: Structured Elicitation (AskUserQuestion)

Problem: Claude asking questions in plain text was slow and unstructured.

Failed Attempts:

1. Adding questions to another tool's output → confused the model
2. Modified markdown format → unreliable output

Solution: Dedicated tool with:

• Structured input (question + options)
• Modal UI that blocks until answered
• Clear prompt about when to call it

Key insight: Claude "liked" calling this tool — the interface matched how it naturally thinks about asking questions.

Pattern: Task Coordination (Task Tool)

Evolution from TodoWrite:

• TodoWrite was for keeping the model on track
• Task Tool is for subagent coordination
• Tasks have dependencies, can be shared, modified, deleted

When to use: When multiple agents need to coordinate on shared state.

Pattern: Context Building (Search Tools)

Evolution:

1. RAG → fast but fragile, context was given not found
2. Grep tool → let Claude search directly
3. Skills → progressive disclosure through file references

Key insight: As models get smarter, they become better at building their own context if given the right tools.

Pattern: Capability Without Tools (Subagents)

Problem: Claude didn't know about itself (MCP, slash commands, etc.)

Failed approach: Put docs in system prompt → context rot

Solution: Claude Code Guide subagent

• Prompted to call when users ask about Claude Code
• Has extensive instructions on searching docs
• Adds capability without adding a tool

Tool Design Checklist

Before adding a tool, ask:

1. Can this be progressive disclosure?

   • A skill that references files?
   • A subagent with specialized instructions?

2. Does Claude naturally want to call this?

   • Test with real scenarios
   • Read the outputs carefully

3. Is this solving a real problem?

   • Or is it a workaround for model limitations that may improve?

4. How many tools will this make?

   • Is the cognitive overhead worth it?

5. Will this age well?

   • As models improve, will this still be useful?
   • Or will it become a constraint?

Anti-Patterns

Anti-Pattern: Overloading Tool Purpose

# BAD: Asking for plan AND questions in same tool
ExitPlanTool(plan: string, questions: Question[])

# GOOD: Separate tools for separate purposes
ExitPlanTool(plan: string)
AskUserQuestion(questions: Question[])

Anti-Pattern: Relying on Output Format

# BAD: Hoping model outputs specific format
"Output questions in this format: - Question [Option A | Option B]"

# GOOD: Structured tool input
AskUserQuestionTool({
  questions: [{
    question: "...",
    options: ["A", "B"]
  }]
})

Anti-Pattern: Static Context

# BAD: Everything in system prompt
"You have access to MCP servers, here's how to configure them..."

# GOOD: Progressive disclosure
"You can call the claude-code-guide agent to learn about Claude Code features"

Practical Tips

See Like an Agent

1. Read the outputs — What confused the model? What did it do naturally?
2. Experiment often — Try different tool shapes
3. Watch for patterns — Is the model working around your tools?

Iterate on Tool Interfaces

The first design rarely works. Expect:

• 2-3 iterations minimum
• Testing with real use cases
• Adjusting based on model behavior

Model Capabilities Change

What works for Claude 3.5 may not work for Claude 4:

• Revisit tool designs with new models
• Remove tools that are no longer needed
• Don't optimize for old model limitations

Reference

Source: Claude Code Team Learnings

Related Concepts:

• Tool calling / Function calling
• Progressive disclosure
• Subagent coordination
• Context building
• Elicitation patterns