agent-tools-patterns

chkim-su's avatarfrom chkim-su

Patterns for configuring agent tools correctly

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 7, 2026⬇️2downloads
[Tool Routing and Orchestration]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for correctly configuring agent tools, ensuring optimal performance and security. It addresses the critical technical nuances of tool inheritance, specifically for Model Context Protocol (MCP) integrations, and establishes best practices for 'least privilege' access. By following these patterns, developers can prevent common configuration errors that lead to broken agent workflows or security vulnerabilities.

Use Cases

  • Case 1: Configuring agents to seamlessly inherit and utilize MCP tools like Serena or Playwright by applying the correct field omission patterns.
  • Case 2: Implementing security-first 'Read-Only' agents by restricting tool access to specific file analysis commands, preventing unauthorized system modifications.
  • Case 3: Developing specialized 'Pure Reasoning' agents that focus entirely on text generation and logic without the overhead or risk of tool execution.
  • Case 4: Troubleshooting and auditing existing agent configurations to identify anti-patterns, such as explicit MCP tool listing or mismatched tool-description logic.
nameagent-tools-patterns
descriptionPatterns for configuring agent tools correctly
allowed-tools["Read"]

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