Why does the model pick the wrong tool when two of them sound almost the same?

Because the model never reads either tool's code. It sees a name, a description string and a list of typed arguments, so when two descriptions use almost the same words the distinction between the tools is not in the text it reads. It resolves the ambiguity to the most common reading and makes the call with confidence.

That is the whole interface. The model cannot see the database, the column types, the rate limit or the fact that a date argument must be the first of a month. Anything true but unstated gets guessed, and the guess is not flagged as a guess. A description that says 'gets the account balance' is not wrong. It is incomplete in ways that force the model to invent the missing parts.

The natural guess is that the model reads the function body, or recognises from the name what the tool does. It does neither. A name is a string, and a description is a string, and two strings that both say 'search the documents' do not tell the model which index is meant. The model does not become hesitant when the description is vague. It picks the more common reading, which is usually right, and then repeats that choice every time the same overlap appears.

Put two balance tools side by side. One returns the settled balance in minor units; the other returns the available balance in major units. If both descriptions say 'gets the account balance', the model has no signal for settled versus available and no signal for pence versus pounds. It will choose one reading, say pounds, and use it consistently. Every result is then out by a factor of 100 in one direction, and nothing in the response looks like an error. The same shape appears when one tool treats a limit as a maximum and the other as an exact count.

An unknown identifier that returns an empty list is worse than one that returns an error, because an empty list looks like a true answer rather than a failed call. The model sees no failure, so it reports that the customer has no orders. One sentence in the description, saying an unknown identifier is an error and not an empty result, converts a confident false statement into a visible failure. That sentence costs less than the support ticket it prevents.

The largest improvement is usually not a better paragraph. It is fewer tools. Four search tools that differ only in which index they consult ask the model to make a distinction that is genuinely fine, and no wording removes that fineness. One search tool with an index argument makes the same distinction a value the program can validate instead of a choice between near-identical options.

Measure wrong choices per tool, not just overall. If two tools are confused in both directions, merge them. If one tool is chosen when another was meant but never the reverse, the problem is usually in the description of the one being over chosen, because it claims more than it does. If a tool is never chosen when it should be, it is probably named after its mechanism rather than the question it answers.

Better wording stops helping when the overlap is real in the domain. If both tools genuinely do the same job against different backends, a sentence saying when not to use one can reduce the error, but it cannot make the two choices different. At that point the tool set is wrong, not the prose. If the tools must remain separate, make the difference an argument that the program checks, such as an index or a mode value, rather than a distinction the model has to infer from two similar names. A description can prevent a systematic error by stating the thing the model would otherwise guess, but it cannot supply a distinction the tool set does not have.