Free lesson · Claude Certified Architect - Foundations (CCA-F)
How Claude Selects a Tool: Descriptions as the Routing Surface
Three Fields Decide Everything
When you give Claude a tool, you give it exactly three things.
A name. A description. An input schema.
That is all the model has. It does not see your code. It does not know what your function actually does. It cannot check what the tool returned last time somebody used it.
So when the model decides whether to reach for a tool, it is deciding from those three fields and nothing else.
Important: If the model picks the wrong tool, the first place to look is not the model. It is the description. The description is the entire basis for the decision, so a bad decision almost always traces back to a description that did not distinguish this tool from the others.
Selection Is a Matching Problem
Think about what the model is doing. It has a situation - a user's request, some results so far, a goal. It has a list of tools, each with a name and a description.
It is matching the situation against the descriptions to find the best fit.
graph TD
A["The situation<br/>What is needed<br/>right now"] --> B{Compare against<br/>each tool}
B --> C["lookup_order<br/>description..."]
B --> D["get_refund_policy<br/>description..."]
B --> E["send_email<br/>description..."]
C --> F["Best match wins"]
D --> F
E --> F
F --> G[Tool requested<br/>with arguments]
This diagram shows tool selection as a matching process. The current situation, describing what is needed right now, is compared against each available tool: a lookup order tool, a get refund policy tool, and a send email tool, each with its own description. The best match wins and the model requests that tool with arguments.
This framing explains most selection behaviour.
If two descriptions are similar, matching is unreliable - both look like reasonable fits.
If a description says what a tool does but not when to use it, matching has less to work with.
If no description fits well, the model picks the closest thing, which may be quite wrong.
Tip: When you write a description, imagine it sitting in a list next to every other description you have. The question is not "does this describe my tool?" It is "does this make my tool clearly different from the others in this list?"
Interactive animation: The situation is matched against each tool's description - lookup_order, get_refund_policy, send_email - and the best match wins.
What Each Field Contributes
| Field | What it does for selection |
|---|---|
| Name | A quick signal. Read first, and often enough on its own for an obvious case |
| Description | The real work. Whether this tool fits, and when it does not |
| Input schema | Whether the model has what the tool needs, and what to send |
The name matters more than people expect, because it is short and prominent. get_order and get_order_v2 sitting side by side give the model almost nothing to distinguish them. get_order_summary and get_order_line_items are immediately distinguishable.
The names themselves have a format requirement - letters, numbers, underscores and hyphens, up to 64 characters. Within that, clarity is worth more than brevity.
Tip: Name tools after what they return or do, not after the system behind them.
query_sap_z_tabletells the model nothing useful.get_inventory_leveltells it exactly when to reach for this. The model does not care which system you are calling.
The Schema Affects Selection Too
This surprises people. The input schema is not only about filling in arguments - it also tells the model whether this tool is usable right now.
If a tool requires an order_id and the model does not have an order ID, that tool is a poor fit for this moment, however well its description matches. The model may go and find the order ID first, or pick a different tool that works with what it has.
So schemas participate in selection by describing preconditions. A tool with three required fields is harder to reach for than one with a single optional one.
Important: A schema demanding information the model rarely has will be under-used, even when it is the right tool. If a tool is being ignored, check whether its required fields are obtainable at the point where it should be called.
Where Selection Goes Wrong
Four patterns, all traceable to the three fields.
Descriptions that overlap. Two tools whose descriptions could both apply. The model has no basis for choosing, so it chooses inconsistently.
Descriptions that only say what. "Returns customer data." That describes the output and says nothing about when this is the right call.
Missing negative guidance. No description says when not to use it, so a tool gets used for adjacent situations it was never meant for.
Too many tools. Selection accuracy degrades noticeably as a catalog grows - beyond roughly thirty to fifty tools it becomes a real problem, because too many plausible candidates compete for every situation.
That last one is not a description problem, and it is covered in Topic 8. The other three are, and they are the subject of the next topic.
Warning: A model picking the wrong tool consistently is not being unreliable. It is being consistent with information that does not distinguish the options. The fix is a better description, and it usually takes ten minutes.
An Example of the Difference
Interactive animation: The same two tools, described twice: one pair the model cannot tell apart, one pair that routes correctly.
Example: Two tools, poorly described:
get_order- "Gets order information."get_order_details- "Retrieves details about an order."Nothing here distinguishes them. The model will pick more or less at random, and its choice will vary between runs on identical input.
The same two, described well:
get_order_summary- "Returns an order's status, total, and date. Use this when you need to know where an order stands. Does not include individual items - useget_order_line_itemsfor that."get_order_line_items- "Returns every item in an order with quantity, price, and per-item status. Use this when the customer asks about a specific product. For overall status, useget_order_summaryinstead."Now each description says what it returns, when to reach for it, and explicitly points at the other tool for the case it does not cover.
The second version will route correctly. The first version cannot, because the information needed to choose is not there.
Notice that the fix required no change to the underlying functions. Only the descriptions changed.
Selection Happens Every Turn
One thing worth making explicit: this is not a decision made once at the start.
Every turn of the loop, the model reconsiders. It has new information - the last tool's result, what worked, what failed - and it chooses again from the same catalog. A tool that was the wrong choice on turn two may be exactly right on turn five.
graph LR
A[Turn 1<br/>Situation A] --> B[Selects tool X]
B --> C[Turn 2<br/>Situation A + result]
C --> D[Selects tool Y]
D --> E[Turn 3<br/>Situation grows]
E --> F[Selects tool Z<br/>or finishes]
This diagram shows selection repeating across turns. On turn one the model faces a situation and selects tool X. On turn two the situation now includes that result, and it selects tool Y. On turn three the situation has grown further and it selects tool Z or decides to finish.
This has two practical consequences.
The cost of a large catalog is paid repeatedly, not once, because every definition is present at every decision. And a description that is ambiguous will be ambiguous on every turn, so a single unclear pair of tools can produce wrong choices throughout a long task rather than once at the beginning.
It also means the situation the model is matching against changes as work progresses. A description written only for the opening request may fit poorly later, when the model is deep in a task and needs something specific. Descriptions that state the trigger situation clearly hold up better across a long loop than ones that assume the model is starting fresh.
Why This Is 18 Percent of the Exam
Tool design is Domain 2, and this topic is its foundation. Almost every question in the domain comes back to the fact that the model decides from three fields.
Schemas, errors, scoping, and forcing selection all build on it. So does the exam's habit of presenting a selection failure and asking what to change - where the answer is nearly always the tool definition rather than the model.
Interview: When a scenario describes an agent calling the wrong tool, work through the three fields before anything else. Are the names distinguishable? Do the descriptions say when to use each one? Does either mention the other? Options proposing a stronger model or a firmer system prompt are the distractors - the information the model needs belongs in the tool definition, where it is read at selection time.
Tool design is also where a small amount of care goes a long way. Ten minutes spent on a description can eliminate a routing failure that would otherwise recur on every request for months, which is an unusually good return for the effort involved.
Exercise: Starter. Name the three fields the model uses to select a tool. Then say which one carries most of the decision, and why the name still matters.
Intermediate. Take two tools from a system you know and read their descriptions side by side. Could you tell them apart if you knew nothing else? If not, rewrite both so you could.
Advanced. List every tool in one agent's catalog and write a one-line summary of each from its description alone. Any two summaries you cannot distinguish are a routing failure waiting to happen - and you have just found them without waiting for the failure.
Quiz: Quick check: An agent consistently calls
search_documentswhen it should callsearch_policies. Both descriptions say they search and return relevant results. What is the best first change?A) Use a more capable model that can infer the difference B) Rewrite both descriptions to state what each searches, when to use it, and to point at the other for the case it does not cover C) Remove
search_documentsso only one option remains D) Add a system prompt instruction explaining which tool to use whenAnswer: B - the descriptions give the model no basis for choosing, so its choice is close to arbitrary. Option D puts routing information in the prompt rather than in the definitions where it is read at selection time, and C removes a capability to work around a ten-minute fix.