AnthropicClaude Certified Architect – Foundations2026-105.2 Design effective escalation and ambiguity resolution patterns
Ask for identifiers before selecting records
Completed by the knowledge check
Learning objective
Request clarifying identifiers when lookups return multiple possible matches rather than guessing a customer or record.
Core idea
A successful lookup can return ambiguous evidence. Several records matching a name do not identify which record belongs to the customer or which order they mean. Ask for an additional identifier and rerun the relevant lookup instead of selecting the first, newest, or most plausible candidate.
The exam guide requires clarification rather than heuristic selection. Treat that distinction as part of the tool contract and standing prompt. The ambiguity is not necessarily a reason to hand the case to a person: the customer may be able to supply the missing identifier immediately.
How it works
Preserve the meaning of multiple matches
Suppose your support application exposes a custom client tool named get_customer. A search for Sam Patel returns three possible customer records. That result means the query did not resolve identity. It is not a failed tool call, a confirmed customer, or permission to choose a candidate.
Your application can return an explicit candidate list and an application-defined match_count. These fields are examples of a response contract, not Anthropic product fields. Preserve stable record identifiers so later operations can refer to verified evidence. Anthropic’s tool-definition guidance recommends high-signal responses with meaningful stable identifiers and only the fields needed for the next decision.
A tool that returns one silently chosen record hides the ambiguity before Claude can ask. Put the distinction in the operation’s behavior: a broad search returns candidates; a lookup with a discriminating identifier returns the relevant match evidence. The description should explain when the result requires clarification and which query inputs are supported.
In the Messages API, tools defines the client operation and its input_schema. Your code executes a returned tool_use request and sends the lookup evidence back in a tool_result. The model’s next turn can then ask for the identifier. See 1.1.5 for the loop and 2.2.4 for distinguishing no matches from inaccessible data.
Ask for a discriminating identifier
The best question names something the customer can supply and the lookup can use. For a customer record, that may be an account email or a customer identifier. For an order, an order number often addresses the actual ambiguity more directly than repeating the customer’s name.
Match the question to the unresolved object. If the account is established but the customer has two lamp orders, asking for the account email again does not distinguish those orders. Ask for the order identifier or another supported discriminator instead. If an order number identifies a record, preserve its relationship to the customer through the application’s normal access checks.
This is an illustrative support design, not a claim that an email or order number alone authenticates a customer. Disambiguation answers which record the request concerns. Authentication and authorization answer whether the person may access or change it. Keep the application’s established checks before disclosures and mutations.
Use a short question such as, “What is the order number for the lamp you want to return?” Do not present a guess for confirmation: “You probably mean your newest lamp order, right?” That wording has already selected a candidate and pressures the customer to accept it.
Avoid leaking candidate details
Design the clarification question to obtain information from the customer rather than disclose the other candidates. Do not list several account emails or addresses from unresolved identity results and ask which one is theirs. The application should supply only the information needed to resolve the request through its permitted workflow.
Anthropic’s general tool guidance supports minimizing results to high-signal information; the privacy rule here is part of the illustrative retailer’s own contract. Make it explicit in the standing prompt and enforce disclosures in the application. Prompt wording alone is not an access-control check.
The same principle applies to mutations. process_refund should require the resolved order identifier, not a name plus “choose most likely.” If the schema accepts an identifier, that establishes the required input shape; the application still verifies that the identifier comes from the permitted resolution and access path.
Use the answer, then check the result
Put the rule in the Messages API’s top-level system parameter: when a lookup returns multiple candidates, request an additional identifier and do not choose by recency, list order, or perceived relevance. Allow the agent to state that it does not yet have enough information. Anthropic’s hallucination guidance recommends explicitly permitting uncertainty rather than forcing unsupported answers.
When the customer supplies an identifier, issue a fresh lookup using that input. Do not keep the earlier guess and attach the identifier to it. Continue only when the result resolves the relevant ambiguity and the application’s access checks allow the next operation.
If the identifier still yields multiple candidates, ask for another supported discriminator. If it yields no matches, explain that the lookup did not find a record with that information and check a useful correction. Do not reinterpret no matches as proof that the first candidate must have been correct.
Repeated clarification can eventually stop producing progress. If the customer cannot supply a usable identifier and no permitted resolution path remains, use the blocked-progress trigger from 5.2.1. If the customer requests a person during clarification, honor that request immediately under 5.2.2. Neither path licenses selecting an unresolved record.
Each identifier the customer supplies feeds a fresh lookup, and only a resolved result continues to the next operation.
Key distinctions and trade-offs
The following outcomes have different meanings:
| Lookup evidence | Next step | Avoid |
|---|---|---|
| Multiple customer records | Ask for a supported customer or order identifier | Selecting by name similarity |
| One account, multiple relevant orders | Ask which order through a supported discriminator | Choosing the most recent purchase |
| No records for the supplied identifier | Check a useful correction or permitted recovery | Falling back to an arbitrary prior candidate |
| Record resolved, access checks passed | Continue with the covered operation | Treating clarification as automatic escalation |
| No usable clarification path remains | Escalate for blocked progress | Repeating the same ambiguous lookup indefinitely |
Clarification adds a turn but avoids acting on a guessed target. Escalating every multi-match response also adds delay and discards a path the customer could resolve. The correct boundary is whether another supported identifier can establish the target, not whether the lookup returned more work.
Architecture / decision scenario
A customer says, “I’m Sam Patel. I’d like to return the lamp.” The retailer’s custom get_customer search returns three records. The agent asks for the order number without displaying the candidates’ addresses or emails. It does not call process_refund or choose the record with the most recent lamp purchase.
The customer supplies an order number. A fresh lookup identifies the associated record, and the application performs its normal access checks. It then applies the return policy to that order. This resolves the information gap without treating multiple matches as a compulsory human handoff.
Run two variants. In one, the order number still leaves two possible records in the integration’s search scope. The agent asks for the next supported discriminator; it does not treat the first refinement as proof of uniqueness. In the other, the customer says, “I don’t have it; please connect me to a person.” The next operation is handoff with the unresolved identity noted, not another search.
Evaluate the trace for target selection as well as wording. A response that asks a question after already submitting a refund against a guessed identifier fails the objective. Clarification must precede the action whose target it establishes.
Common exam traps
- Choosing the first result because the lookup succeeded.
- Selecting the newest order or the one matching a plausible product.
- Asking for information that cannot distinguish the unresolved records.
- Treating one search match as authentication or authorization.
- Escalating every ambiguous lookup before requesting a usable identifier.
What to remember
Multiple matches mean the target is unresolved. Ask for an identifier the operation can use, rerun the lookup, and preserve the distinction between record selection and access authority. If clarification cannot advance the case—or the customer asks for a person—escalate without guessing a target.
Knowledge check
A customer writes: “Hi, I’m Priya Shah. I want to cancel my order.” The custom get_customer tool returns two customer records named Priya Shah, both with open orders. What should the agent do next?
The agent has resolved a customer’s account through the application’s normal checks. The customer asks to return “the lamp”, and the account has two lamp orders. Which question should the agent ask?
A custom get_customer tool returns the single best-scoring record whenever a name matches several customers, and the agent then acts on that record. Which change lets the agent handle ambiguous names correctly?
A name search returned three customer records, so the agent asked for an order number. A fresh lookup with that number returns exactly one order, and the customer asks for a refund on it. What must hold before the agent calls process_refund?
References
- Anthropic, Claude Certified Architect – Foundations Exam Guide
- Anthropic, Define tools
- Anthropic, Tool use with Claude
- Anthropic, Create a Message
- Anthropic, Reduce hallucinations