Try this first

Give Rover these two tools at the same time:

{
    "name": "read_file",
    "description": "Read a file.",
    "input_schema": {
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"],
    },
},
{
    "name": "get_file_info",
    "description": "Get information about a file.",
    "input_schema": {
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"],
    },
},

Now ask: “How big is notes.txt?”

Then ask: “What does notes.txt say?”

Watch which tool it picks each time. It will get at least one wrong, and it will look
arbitrary.

What you just did

Read the two descriptions as the model does — as the only information available.

“Read a file” and “Get information about a file”. Is the contents of a file information about
the file? Obviously yes. Is size something you get by reading? Arguably.

The boundary between these two tools does not exist in the text. The model is not confused.
You were ambiguous, and it is guessing.

The fix is a boundary, not a warning

The instinct is to add emphasis: "Get information about a file. NOT the contents." That
helps a little, and it is the wrong shape of fix.

Say what each one is for, and let the boundary fall out:

{
    "name": "read_file",
    "description": (
        "Return the full text contents of a file. "
        "Use this when you need to know what is written inside the file."
    ),
    ...
},
{
    "name": "get_file_info",
    "description": (
        "Return a file's size in bytes and when it was last modified. "
        "Does not return the file's contents. "
        "Use this to check whether a file is large before reading it."
    ),
    ...
},

Now the two questions have obvious answers, and one description even tells the model how the
tools work together.

The three causes of wrong tool choice

When a model picks badly, it is nearly always one of these:

Symptom Cause Fix
Picks between two similar tools inconsistently Overlapping descriptions Name the boundary in both
Ignores a tool that obviously applies No trigger sentence Add “Use this when…”
Calls a tool constantly, including when useless Emphasis language, or too-broad description Remove the shouting, narrow the scope
Sends wrong argument types Missing property descriptions, or no enum Describe every property

Note what is not on that list: “the model is not good enough”. That is occasionally true. It
is not the first thing to check, and it is the only item on the list you cannot fix.

When you have too many tools

Two tools with a fuzzy boundary is a writing problem. Twenty tools with fuzzy boundaries is a
design problem.

If two tools take the same arguments and return similar things, they are usually one tool
with a parameter. Fewer, clearly bounded tools beat a large menu of near-duplicates — for the
model and for you.

If you cannot state the boundary between two tools in one sentence, the model cannot infer
it from your descriptions.

Try this before the next lesson

Write descriptions for list_files and search_files that make the boundary unambiguous.
Then ask Rover: “Which file mentions the plumber?”

It should search, not list. If it lists, your search description has no trigger sentence.

PreviousNext