All five are reads

Nothing in this set writes, comments, re-runs or pushes, and there is no sixth tool that does. Everything is pinned to the SHA that failed, taken from the run rather than from anything the model says, so the agent cannot talk itself into reading a different commit.

The catalog

`read_file`

Open one source file at the failing commit.

use when: The log names a file whose contents you have not seen and the root cause cannot be stated without them — a traceback frame in application code, a test asserting on a value defined elsewhere, or the workflow file driving the failing step.
do not use when: The log already contains the answer verbatim. Re-reading a file to confirm something the log stated wastes a turn.

This is the highest-value call in the set. It is especially the right move on type and attribute mismatches, where the traceback points at the caller and the bug is in what the callee returns.

`get_full_diff`

Read the actual patch for a changed file.

use when: The diff summary lists a file whose change you need line by line to confirm or kill a hypothesis you already have. Passing a path restricts the patch to that file.
do not use when: As an opening move to look around. The summary already says what changed and by how much, and the largest hunk is very often not the cause.

`search_code`

Find where a symbol is defined or used.

use when: You know the name of the thing that broke — a function, constant, class or import — but not which file holds it, and neither the log nor the diff says.
do not use when: You already know the path; call read_file directly. It also reads file contents, so a vague query is expensive and comes back as noise.

`list_directory`

List a directory at the failing commit.

use when: You need to know whether a file exists or what the layout is before reading anything — a ModuleNotFoundError where the question is whether a package has an __init__.py, or finding a workflow file's real name.
do not use when: Browsing. One targeted listing is fine; walking the tree directory by directory means you are guessing.

`get_more_log`

Read another slice of the failing step's log by line number.

use when: The window is visibly cut off mid-evidence: a traceback whose top is above the excerpt, or a second failure referenced in the summary whose body is not shown.
do not use when: Reading the rest just in case. The window is already anchored on the first real error and always includes the tail.

Why the descriptions are written as decision criteria

A tool description is the only thing the model sees when deciding what to do next. Written as a description of behaviour — “reads a file from the repository” — it gives the model nothing to decide with, and the result is an agent that either calls everything or calls nothing.

So each one is written as a pair of criteria: use this when X and do not use it when Y. Over-calling and under-calling are both tuned here rather than in the system prompt, because this is the text that is in front of the model at the moment the choice is made.

Reading the trace as a quality signal

The tools an agent chose tell you how the diagnosis was reached. A single read_file on the file the traceback named is a good sign. Threesearch_code calls with vague queries followed by a confident answer is a sign the agent was lost and then guessed.

Interaction with the budget

Each call spends one of six. A call that returns nothing useful still spends one — so the cost of an exploratory search_code is not zero, and the tool descriptions are written to discourage it for that reason. When the budget is exhausted the agent is asked to conclude from what it has, and the resulting confidence should be, and usually is, lower.

Evidence and confidence

What the agent has to bring back from these calls.

Failure scenarios

Which tools a good run uses on each kind of failure.