effective-tool-use

Effective Tool Use

CRITICAL: Prefer dedicated IDE tools over shell equivalents. They provide better user experience, clearer diffs, and easier permission review.

Tool Preference Matrix

Always use the dedicated tool instead of its shell equivalent:

Task	Use This	NOT This
Find files by pattern	Glob	find, ls -R
Search file contents	Grep	grep, rg, ag
Read a file	Read	cat, head, tail
Edit an existing file	Edit	sed, awk, inline scripts
Create / overwrite a file	Write	echo >, cat <<EOF >, tee
Communicate with the user	Direct text output	echo, printf

Reserve the shell (Bash) tool for actual system commands: git, npm, docker, make, curl, test runners, build tools, and other CLI operations that have no dedicated tool equivalent.

Token Cost Hierarchy

Tools differ drastically in token cost. Always narrow before you read:

1. Glob (near-zero tokens) — Returns file paths only. Start here to map the landscape.
2. Grep with -C 3 (lightweight) — Returns matched lines plus context. Use head_limit to cap results for common terms. Often sufficient without a full file read.
3. Read (heavy, 500-5000+ tokens) — Full file content. Use ONLY after Glob/Grep confirmed the file is relevant.

For meaning-based queries ("how does authentication work"), check if MCP tools like search_code are available before falling back to broad Grep with keywords and synonyms.

When research spans >5 files, spawn a subagent via the Agent tool to research in an isolated context and return a summary. This prevents context exhaustion in the main session.

Reading Files

• Read files before editing them. An edit to unread code is a guess, not a fix.
• Write tool requires a prior Read of the target file. It will fail otherwise.
• For large files, use offset/limit to read only the relevant section. Don't load 2000 lines when you need 20.
• When you already know which section you need (from a Grep match with line numbers), read just that range.
• Prefer Edit over Write for modifying existing files — Edit sends only the diff. Use Write for new files or complete rewrites.
• Never create documentation files (*.md) or READMEs unless the user explicitly asks.