Agents và tools — Abstract vs specialized

Abstract > specialized

Anti-pattern: Specialized tools

Problems:

Good pattern: Abstract tools

• Claude can't adapt when task slightly different
• Tool maintenance burden
• Prompt bloat (list all 50 schemas)
• Combinations locked in

Tools:
- refactor_code()
- install_dependencies()
- fix_typescript_error()
- deploy_to_aws()
- ...50 specific actions

Good pattern: Abstract tools

Claude combines:

6 tools → unlimited task types.

• "Refactor code" = read → analyze → edit (multiple)
• "Install deps" = bash(pip install ...)
• "Fix TS error" = read → understand → edit
• "Deploy" = bash(AWS CLI commands)

Tools:
- bash(command)       # Run anything
- read(file)          # Read anything
- write(file, text)   # Create anything
- edit(file, old, new) # Modify anything
- grep(pattern)       # Search anything

Case study: Claude Code tool set

Claude Code (production agent) has:

9 tools handle:

No specialized "refactor_code" or "run_tests". Claude figures out.

• Debugging
• Refactoring
• Adding features
• Running tests
• Git operations
• Documentation
• Research

Tool design principles

1. Verb + noun name

2. Single responsibility

Each tool does 1 thing. Combine for complex.

3. Natural composition

Output of 1 tool = input of another.

4. Descriptive errors

Claude reads errors to retry:

Claude learn from error message.

5. Return string or structured

Structured data easy for Claude to reason.

• read_file ✓
• file ✗
• get ✗
• read_file(path) ✓
• read_and_edit_file(path, old, new) ✗ (too much)
• glob("*.py") → list of paths → read_file(path) → content → grep(pattern, content)

raise ValueError("File not found: /path/to/file. Existing files: [...]")

Tool set example: Social media video agent

Claude can:

Multi-paths from 6 tools.

• Research trend + write script + generate voice + generate images + combine video + post
• Or: user approve image first → proceed
• Or: iterate on script → then generate

tools = [
    "bash",           # FFmpeg, misc commands
    "generate_image", # Image from prompt
    "text_to_speech", # TTS API
    "post_media",     # Upload to platform
    "read_file",      # Check generated files
    "get_trends"      # Fetch trending topics
]

Anti-pattern: Tool bloat

Agent with 50 tools:

Problems:

Threshold: < 15 tools generally. > 20 = refactor.

• Prompt tokens massive (each schema 50-200 tokens × 50 = 2.5K-10K overhead)
• Claude decision slower
• Similar tools confuse selection
• Maintenance nightmare

Solution: Tiered tools

If you really need many tools, tier them:

Primary routes to specialist. Each specialist tractable tool count.

Claude Code Task tool spawns sub-agent — same pattern.

Primary agent:
  Tools: [search_docs, ask_specialist, escalate]

Specialist "code reviewer" sub-agent:
  Tools: [read, edit, lint, run_tests]

Specialist "deployment" sub-agent:
  Tools: [build, deploy, monitor, rollback]

Abstraction layers

Low-level (primitive)

Mid-level (convenience)

High-level (workflow)

Use mid/high for repeated patterns. Low for flexibility.

Default: Primitive. Add convenience only if Claude struggles với primitives.

• bash — run any command
• run_tests — wrap bash("pytest ...") with standard args
• deploy_to_staging — multi-step workflow wrapped

Tool integration with workflow patterns

Agent tools combine with workflow patterns:

Chaining within agent

Claude: tool 1 → tool 2 → tool 3. Effectively chaining within 1 agent.

Parallel tools

Multiple tool calls trong 1 turn → parallel execution (if supported).

Routing via tools

Tool route_to(specialist) → hand off task.

Environment inspection

Tools include read/get_state — Claude check before act (bài 6.73).

Debugging agents

Agent behavior varies. Debug:

1. Log all tool calls

Replay sessions later.

2. Tool call tree visualization

Understand flow at glance.

3. Success metrics per tool

Track error rates per tool. High errors → tool design issue.

Session XYZ
├─ read_file(main.py)         [200ms]
├─ grep("TODO")                [100ms]
├─ edit(main.py, ...)          [150ms]
└─ bash("pytest")              [2s]

def log_tool_call(name, input, result):
    logger.info({
        "timestamp": now(),
        "agent_session": session_id,
        "tool": name,
        "input": input,
        "result_preview": str(result)[:100]
    })

Best practice: Eval agent behavior

Can't test all behaviors of agent. Sample:

Track over time as add tools / update prompts.

test_scenarios = [
    "Fix bug in auth.py",
    "Add logging to main",
    "Deploy to staging",
    # 20 diverse scenarios
]

for scenario in test_scenarios:
    session = run_agent(scenario)
    # Grade:
    # - Completed task? (human verify)
    # - Number of tool calls
    # - Cost
    # - Correct final state

Anti-patterns

❌ Tool = reimplement existing API

get_user(id) wrapping requests.get(...) exactly.

Fix: MCP server hoặc wrap meaningfully.

❌ Tool hide important error

Claude doesn't know action failed → bad chains.

Fix: Surface errors honestly.

❌ Tools with hidden coupling

Tool A must call before B, not documented.

Fix: Tools independent. Or document requirement in description.

❌ Agent without max_turns limit

Infinite loops = money burn.

Fix: Always max_turns (bài 6.35-6.36).

try:
    do_work()
except:
    return "Done"  # Lie

Áp dụng ngay

Bài tập 1: Design tool set (30 phút)

Cho app của bạn, design 6-10 tools cho agent:

Bài tập 2: Reduce tool count (20 phút)

Nếu list > 10 tools, identify:

• List candidates
• Check abstraction level
• Identify composition paths
• Duplicates (similar tools merge)
• Specializations → abstract
• Rarely used (drop)

Tóm tắt

🎯 Abstract tools > specialized cho agents.

🎯 Claude Code mẫu: 9 tools handle countless tasks.

🎯 5 design principles: verb+noun, single responsibility, composition, errors, structured return.

🎯 Tool bloat at > 15 tools — tier with sub-agents.

🎯 Debug: log + tree visualization + eval scenarios.