Select and apply built-in tools (Read, Write, Edit, Bash, Grep, Glob) effectively

Use Glob to find where a function is called.

Glob matches paths, not contents, so it returns files whose names happen to resemble the symbol and misses every real caller.

Grep searches inside files; Glob searches the names of files.

Read the whole directory up front so the agent has full context.

It spends the context window on files that turn out to be irrelevant, and the relevant ones end up buried in the middle of it.

Grep to the entry points, Read to follow the imports that matter, and let the trace decide what to load.

Keep retrying Edit until the anchor finally matches.

A non-unique anchor fails deterministically — Edit reports it rather than editing the wrong site — so the retries never converge and the modification never lands.

When Edit cannot find a unique anchor, Read the file and Write it back. That is the objective's named fallback.

Use Write for a small change because it is the most direct tool.

Write replaces the file, so anything the agent did not reproduce in its output is gone — and nothing reports the loss.

Edit for targeted change; Write when you intend to author the whole file.

Search for the function name once to find every usage.

Re-exports and wrapper modules rename it on the way through, so call sites that use the alias never appear.

Identify the exported names first, then search for each one across the codebase.

recovering from a non-unique Edit anchor

Answer this: When Edit cannot find a unique anchor, fall back to Read plus Write.

The docs now say: The documented remedy is to extend old_string with enough surrounding context to pin one occurrence, or to set replace_all — and Edit is preferred over Write for partial changes. Edit fails loudly on a non-unique anchor rather than editing the wrong site. Read it