Tool Error Handling and Usage Patterns for CCDV-F

From calling a tool to calling it well

Once you understand tool use and function calling, the next step is making tools behave reliably when things go wrong or when the action is risky. That is what this knowledge point is about, and because it sits at the apply level on the Claude Certified Developer - Foundations (CCDV-F) exam, you are expected to choose the right pattern for a given situation, not just define terms. Three ideas do the work: structured errors, the client-side versus server-side distinction, and approval gates.

Returning a structured error, not a silent failure

When a tool cannot complete its job, it must tell Claude clearly. The right behaviour is to return a structured error: an outcome the model can read and reason about, explicitly marked as a failure. If a get_invoice tool cannot find the invoice because the service is down, it should return an error saying so, so Claude can retry, apologise, or escalate. The model treats a tool_result as ground truth, so how you shape that result directly steers its next decision.

The critical distinction is between a failure and a valid empty result. These are not the same thing, and conflating them is the central exam trap here. A search that ran correctly and found nothing returned a valid empty result: the answer is "there are zero matches." A search that could not run at all returned a failure: the answer is "I do not know, something broke." If you return the failure as an empty result, Claude concludes there are no matches and moves on, hiding the outage. If you return the empty result as an error, Claude thinks the tool is broken and may retry forever or give up on a perfectly good query. Structured errors keep the two cases separate so the model reasons correctly.

Client-side versus server-side tools

Where a tool actually runs changes its trust profile and its latency, and the exam expects you to reason about that. A client-side tool executes in the caller's own environment: the same process or machine that is orchestrating the conversation. It has direct access to local files, local credentials, and the caller's network position, and it typically runs with low latency because there is no extra hop.

A server-side tool executes remotely, on a separate service the caller reaches over the network. That remote execution changes two things. Trust shifts, because the tool now runs in an environment you may not fully control and the data crosses a boundary to get there. Latency rises, because every call is a network round trip to the remote service. Neither is automatically better; the point is that the choice has consequences. A tool that needs the caller's local context and speed belongs client-side, while a tool that centralises a capability for many callers, or that must run where sensitive systems live, belongs server-side. This same trade-off reappears when you decide between local and networked MCP communication patterns.

Approval patterns for sensitive calls

Not every tool is safe to run the instant Claude requests it. A tool that sends money, deletes records, emails a customer, or changes production configuration is one bad request away from real damage. An approval pattern places a gate between the model's tool_use request and the actual execution: a human confirms the action, or a deterministic check validates it, before the harness runs the call. Only after that gate passes does the tool execute and return a result.

The exam trap here is treating every tool as safe to auto-run. It is tempting to wire all tools onto the same automatic path because it is simpler, but that removes the one safeguard that stops a mistaken or manipulated request from doing harm. The discipline is to classify tools: read-only and low-impact tools can auto-run, while sensitive or destructive ones sit behind an approval gate. Note that this is a request-execute-return loop with a checkpoint inserted, the same loop from tool use and function calling, so the model still only requests, and the gate governs whether your harness actually runs the call.

The traps the exam sets

This knowledge point has two closely watched traps, and both are about honesty of signals. The first is returning a valid empty result as an error, or an error as an empty result. A question may describe an agent that keeps insisting a customer has no orders when the order service was actually down, or an agent that retries endlessly against a query that simply has no matches. The cause in both cases is a tool that blurred the line between "nothing found" and "could not run." Returning a structured error for real failures and a clean empty result for genuine emptiness is the fix.

The second trap is treating every tool as safe to auto-run without an approval pattern for sensitive ones. A scenario might show an agent that autonomously issued a refund or deleted a record because the tool was on the automatic path with no gate. The correction is to place sensitive actions behind a human or deterministic approval before execution.

Common misreadings to avoid

How this is tested on the exam

Domain 8 questions on this knowledge point are scenario-based and ask you to apply judgement. You will see an agent that misreports an outage as an empty result, or one that took a destructive action with no checkpoint, and you must identify the missing pattern. The correct answers come back to the three ideas here: return structured errors distinct from empty results, understand that client-side and server-side execution change trust and latency, and gate sensitive calls behind approval. Master those and you can diagnose the tool-behaviour scenarios the CCDV-F exam favours.