Agent Tools Configuration Patterns Skill

Agent Tools Configuration Patterns

Core Principle

tools: [] ≠ tools omission

| Configuration | Meaning | Use Case | |---------------|---------|----------| | tools field omitted | Inherit ALL tools (including MCP) | Default, MCP-using agents | | tools: [] (empty array) | NO tools | Pure reasoning agents only | | tools: ["Read", "Grep"] | Specific tools only | Minimum privilege |

Decision Tree

Does agent need MCP tools (Serena, Playwright, etc.)?
├─ YES → OMIT tools field (inherit all)
└─ NO
    ├─ Needs specific Claude Code tools → tools: ["Read", "Grep", "Bash"]
    ├─ External access only → tools: ["WebSearch", "WebFetch"]
    └─ Pure thinking, no tools → tools: []  # Add comment!

Pattern Catalog

Pattern 1: MCP Tool Inheritance (Default)

When: Agent uses Serena MCP, Playwright MCP, or other MCP tools Config: Omit tools field entirely Rationale: MCP tools cannot be listed explicitly; they're inherited

---
name: mcp-executor
description: Executes refactoring via Serena MCP
# tools field intentionally omitted - inherits all including MCP
---

Pattern 2: Read-Only Analysis

When: Agent only analyzes, never modifies Config: tools: ["Read", "Grep", "Glob"] Rationale: Minimum privilege for safety

Pattern 3: External Access Only

When: Agent fetches from external sources, no file access Config: tools: ["WebSearch", "WebFetch"] or tools: ["Bash"] Rationale: Restrict file system access

Pattern 4: Pure Reasoning (Rare)

When: Agent only generates text, no tool use Config: tools: [] with comment Rationale: Must be explicit and documented

---
name: pure-thinker
description: Generates creative ideas without tool access
tools: []  # Intentional: pure reasoning agent
---

Anti-patterns

| Anti-pattern | Problem | Fix | |--------------|---------|-----| | tools: [] without comment | Unclear intent | Add comment or remove | | tools: [] with MCP description | Agent is broken | Remove tools line | | Listing MCP tools explicitly | MCP tools can't be listed | Omit tools field |

Validation Codes

| Code | Meaning | Action | |------|---------|--------| | W049 | tools: [] but description implies tool usage | Remove tools line | | W050 | tools: [] without clear intent | Add comment or remove |

Quick Reference

MCP agent → omit tools
Read-only → tools: ["Read", "Grep", "Glob"]
External → tools: ["WebSearch", "WebFetch"]
SDK only → tools: ["Bash"]
Thinking → tools: []  # Intentional

Agent Skills: Agent Tools Configuration Patterns

Install this agent skill to your local

Skill Files