The tool your coding agent keeps ignoring is probably returning addresses instead of answers

A coding agent never sees a tool's backend. It sees the tool's description before the task and the tool's result after the call, and nothing in between. That sounds obvious until you notice how many tools were designed for a client that could do the second half of the job for free.

A language server is the clean example. Under the protocol, a find-references request returns a list of locations: a file, a line, a character offset. That is the right answer for an editor, which has the file open and can jump there. An agent has nothing open. Hand it a location and the next thing it does is read the file, one call per address.

A small pilot study posted in August measured what that costs. With grep and an LSP-backed tool both available, three models picked the semantic tool 0 to 6 percent of the time on code-location tasks, which is roughly never. The author then kept the same backend and the same set of references and changed only the reply, attaching two lines of source above and below each one. On a multi-file rename, pass@1 rose from 0.67 to 0.83 and follow-up file reads fell from 15.2 to 3.2 per episode. The scale is a pilot, six tasks and a few repos, so treat the numbers as direction rather than magnitude. The direction is clear enough.

The second half of the story came from Spotify. They wanted Claude Code to stop reading large files whole and route that work to a smaller model. Rules in CLAUDE.md sort of worked. Advisory, though, and the model could ignore them. What held was a PreToolUse hook that blocks the read past a line threshold and names the alternative, whether or not the model read any instructions about it.

Two habits came out of this for us. Before mounting a tool, print one real result and ask what the agent's next call would be with only that in front of it. And sort your rules: preferences belong in the rules file, where they can lose gracefully; prohibitions that have to hold every time belong in a hook.