Try this first

Here are two descriptions of the same function. Predict which one gets used more often.

A: "Search the codebase."

B: "Search the project's source files for a text pattern and return matching lines with
their file paths and line numbers. Use this when you need to find where something is defined
or used, before reading whole files."

Now count what B tells the model that A does not:

  • What it searches (source files, not the whole disk)
  • What comes back (matching lines, paths, line numbers)
  • When to reach for it (finding where something lives)
  • What to do instead (this before reading whole files)

A is a label. B is an instruction.

The rule

A tool description has four jobs, in this order of importance:

  1. When to use it. The single most valuable sentence. Most descriptions omit it entirely.
  2. What it does, precisely enough that “does it fit here?” is answerable.
  3. What comes back, so the model knows what it is getting before it asks.
  4. What it does not do, when there is a near neighbour it could be confused with.

Three or four sentences is a normal length. One line is almost always too short.

The mistake that goes the other way

There is an opposite failure, and it is more common in code written a couple of years ago:

"description": "CRITICAL: You MUST use this tool for ALL file operations. NEVER skip this."

Shouting used to be necessary. Older models under-used tools, so people compensated with
capital letters. Current models follow instructions closely, so that same text now
over-triggers: the tool gets called when it is not needed, on tasks where reasoning would
have been better.

Write the trigger condition plainly and let it land:

"description": (
    "Read a file from the project and return its contents. "
    "Use this when you need the actual text of a file, rather than just its name. "
    "Returns the whole file, so prefer search_files first on large files."
)

Say when to use it, at normal volume. That one sentence does more than any amount of
emphasis.

Where to put things that are not descriptions

Two things people jam into descriptions that do not belong there:

Worked examples and fake dialogue. They cost tokens on every single request, and they
narrow the model’s thinking to the shapes you demonstrated. Make the parameters expressive
instead — a well-named enum carries more than a paragraph of examples.

Instructions about other tools. "ALWAYS use this instead of read_file" in one
description, scattered across a dozen tools, becomes impossible to reason about. A preference
for tool X belongs in X’s own description.

Try this before the next lesson

Take your read_file description down to just "Reads a file." and ask Rover three questions
that should need it.

Then restore a full description and ask the same three. Note how many times each version
triggered. You have just measured the thing this lesson claims.

PreviousNext