An on-call agent keeps calling search_logs when get_metrics would answer. How do you fix it?

## The diagnosis comes first Before changing anything, establish that this is a *selection* problem. Pull the traces and look at what the model wrote in the thought immediately before the action. Three different diseases look identical from the outside. If the thought says "I need the error rate for billing-api" and the action is `search_logs`, the model knew what it wanted and picked the wrong surface — a genuine selection failure, and the tool definitions are the lever. If the thought is vague — "let me investigate the service" — the model has not decided what it is looking for, and the fix is upstream in how the task is framed, not in the catalogue. If the model tried `get_metrics` first, got an empty or confusing result, and fell back to `search_logs`, that is not a selection failure at all; the metrics tool is under-serving and the agent is compensating. Assume the first case for the rest of this. ## Descriptions are prompt text At the moment of choosing, the model sees the tool name, the description, and the argument schema. That is the entire basis for the decision. A description like "Search the logs." tells it what the tool does and nothing about when to reach for it, which is the only question actually being asked. A description that discriminates has three parts. **Scope**: what class of question this answers — "numeric time-series for a named metric on a named service over a time window". **Anti-scope**: what it is explicitly not for, naming the alternative — "not for free-text search across log lines; use search_logs for that". **A trigger phrasing or two**: the shape of request that should route here — "error rate, latency percentile, request volume". The anti-scope clause is the one most teams omit and the one that moves the number most, because ambiguity is by definition a comparison between two tools and only a cross-reference resolves it. Write these in the imperative and keep them short. Every token spent here is spent on every turn, and a rambling description competes with the task for attention. ## Make the wrong call harder to express Schemas do selection work too. If `get_metrics` takes `metric` as a free string, the model can invent one and the tool half-answers. If `metric` is an enum of the metrics you actually export, the model either picks a real one or discovers it cannot express the request — which pushes it toward the other tool for the right reason. Required arguments have the same effect: a tool that demands a `service` and a `window` signals that it answers a narrow, structured question, while a tool taking one free-text `query` signals the opposite. Argument shape communicates intent before a single word of description is read. ## Near-duplicates: delete rather than describe The worst version of this problem is three tools that are the same tool. `find_user`, `lookup_user`, `user_by_email` are synonyms in English, and no amount of description writing makes a model reliably choose among synonyms — you are asking it to guess an arbitrary convention. Merge them into one `get_user` with a discriminating argument (an identifier plus an enum of identifier kinds, or optional mutually exclusive fields) and the ambiguity is gone by construction rather than by persuasion. The general principle: prefer one tool with a well-typed argument over several tools that differ only in how you reach the same data. Every additional near-synonym in the catalogue is a fresh opportunity to be wrong, and it costs prompt tokens forever. ## Exemplars for the confusable case A ReAct prompt usually carries a few worked examples. Spend one of them on the boundary you are losing: a question that sounds like free-text investigation but is actually a metric lookup, with the thought that names the discriminating feature ("this asks for a rate over time, so metrics, not logs") and the correct action. Exemplars are expensive in tokens, so target the demonstrated confusion rather than adding generic ones. ## Verify, do not assume Every change here is a prompt change, and prompt changes regress silently. Keep a labelled set of representative on-call questions with the tool you expect for each, run it before and after, and look at whether the confusion moved or merely relocated — a description that over-corrects will start routing genuine log searches to metrics. Watch the reverse direction as explicitly as the one you set out to fix. ## What interviewers are checking That you reach for the tool definitions rather than for a bigger model or a longer system prompt; that you know a description is read as instruction, not documentation; that you are willing to delete a tool; and that you validate the change instead of declaring victory from one good trace.