Skip to content

Tool Selection Guide

Nikola Balic (@nibzard)

Problem

AI agents often struggle to select the optimal tool for a given task, leading to inefficient workflows. Common anti-patterns include:

  • Using Write when Edit would be more appropriate
  • Launching subagents for simple exploration tasks
  • Skipping build verification after code changes
  • Performing sequential exploration when parallel would be faster

These ineff compound across long sessions, resulting in wasted tokens, slower completion, and more user corrections.

Solution

Encode data-driven tool selection patterns that emerged from analysis of 88 real-world Claude conversation sessions. By matching task type to optimal tool, agents can follow proven workflows.

Tool preference patterns from actual usage data:

Task Type Recommended Tool Evidence
Codebase exploration Read → Grep → Glob Consistent pattern across all projects
Code modification Edit (not Write) 3.4:1 Edit:Write ratio in nibzard-web
New file creation Write Appropriate use case
Build verification Bash 324 uses in nibzard-web, 276 in patterns
Research delegation Task (with clear subject) 48 invocations across sessions

Key selection criteria:

  1. Exploration tasks (discovering code structure, finding patterns):
  2. Start with Glob for file discovery
  3. Use Grep for content search (syntax-aware when available)

  4. Use Read for targeted file inspection

  5. Code modification tasks (changing existing code):

  6. Prefer Edit over Write - preserves existing context and comments
  7. Only use Write for brand new files or complete rewrites (with permission)

  8. Always Read the file before editing

  9. Verification tasks (testing, building, checking):

  10. Use Bash for build commands, test runners, and linting
  11. Run verification after every Edit/Write operation

  12. Check for errors/warnings before proceeding

  13. Delegation tasks (parallel exploration):

  14. Use Task tool for subagent delegation
  15. Always provide clear task subjects (no empty strings)
  16. Prefer parallel over sequential for independent exploration
flowchart TD A[Task Type?] --> B[Exploration] A --> C[Modification] A --> D[Verification] A --> E[Delegation] B --> B1[Glob files] B1 --> B2[Grep content] B2 --> B3[Read targets] C --> C1[Read file first] C1 --> C2{New file?} C2 -->|Yes| C3[Write] C2 -->|No| C4[Edit] D --> D1[Bash build/test] D1 --> D2{Errors?} D2 -->|Yes| D3[Fix then retry] D2 -->|No| D4[Proceed] E --> E1[Define clear subject] E1 --> E2{Independent tasks?} E2 -->|Yes| E3[Parallel delegation] E2 -->|No| E4[Sequential delegation] style B fill:#e1f5ff style C fill:#fff4e1 style D fill:#e8f5e9 style E fill:#f3e5f5

How to use it

Before using any tool, mentally categorize the task:

  • "Am I discovering something?" → Exploration toolkit
  • "Am I changing something?" → Edit (after Read)
  • "Am I checking something?" → Bash verification
  • "Am I delegating something?" → Task with clear subject

Anti-pattern prevention:

  • Don't use Write for modifications (use Edit)
  • Don't skip Read before Edit
  • Don't claim work complete without Bash verification
  • Don't use empty task subjects in Task invocations
  • Don't explore sequentially when parallel is possible

Trade-offs

Pros:

  • Data-driven from 88 real sessions
  • Reduces token waste and user corrections
  • Faster workflow completion
  • Clear mental model for tool selection
  • Prevents common anti-patterns

Cons:

  • Requires tool availability (e.g., Bash for verification)
  • Parallel delegation increases cost
  • May feel slower for simple one-off tasks
  • Requires discipline to follow patterns consistently

References

Source: https://github.com/nibzard/SKILLS-AGENTIC-LESSONS