Task statement 8.1 · Tools and MCPs

8.1 · Tool Implementation

Shelfwise, the course example, gives its agent one read-only tool, mcp__stock__stock_lookup, served by its small custom MCP server. Tool implementation decides what Claude reads about that tool, who runs each call, what a failure returns, and which calls wait for a person.

Why it's tested

The tempting approach treats a tool as an ordinary programmer's function. It fails because the caller is a model that reads only the tool's name, description and schema, and learns only what each result says, so a terse description or an unhandled exception leaves it guessing.

KnowledgeTool use and function calling

Tool use, also called function calling, is a contract: you describe operations, Claude decides when to call them, and code outside the model runs them. A definition has a name, a description and an input_schema (2.5). A call arrives as a tool_use block with an id, the name and an input object, and the loop (1.2) answers with a matching tool_result. tool_choice is auto by default, so Claude may answer in text. any requires a tool, tool names one and none forbids them, though the newest models reject any and tool (5.3). Claude may call several tools at once, and all results return in one user message. disable_parallel_tool_use: true, set inside tool_choice, limits auto to one call per response.

KnowledgeConfiguration for external system interaction

Configuration lives in the code that runs the tool, never in what Claude reads. Credentials and endpoints sit in that code's environment or a secrets store (7.4), because a schema or prompt travels with every request. Each external call needs a timeout shorter than the person will wait, since a hung call holds the turn. A tool with side effects needs idempotency, where a repeat has the effect of one call (2.4), so a retry after a timeout cannot act twice. Every tool also respects the system's rate limits and tells Claude when to retry. Shelfwise's feed address and credential sit in the MCP server's configuration.

KnowledgeTool description writing

Tool description writing builds on 6.2, where the docs call the description by far the most important factor in tool performance. They ask for at least three or four sentences: what the tool does, when to use it and when not to, what each parameter means, and what it does not return. Anthropic's engineering post adds clear parameter names, such as user_id rather than user, and namespacing by service, such as asana_search. Results should carry meaningful context, such as names instead of opaque codes, and only the fields the next step needs (6.1). Shelfwise's description reads:

"Look up one product's stock at one branch in the hourly stock feed. Use it
 for every count question, not for opening hours. product: the name as staff
 typed it. branch: from the Branch line. Returns source, sku, count and
 feed_time. A vague name returns up to five records and "matches", the
 total: ask staff which one they mean."

KnowledgeError handling

Error handling decides whether a failure reaches Claude as information or ends the conversation. A failed call returns a tool_result with is_error: true and content saying what went wrong and what to try next, such as "Rate limit exceeded. Retry after 60 seconds.", so Claude can retry, change its input or explain. An escaped exception or a failed request gives Claude nothing to reason about. Retry inside the tool only for a transient failure of an idempotent operation, a few times, then report. MCP servers set isError instead (8.2). Server tools need no error result from you.

KnowledgeTool usage patterns

In agentic harness dispatch, the harness (1.2) maps each tool_use block to a handler through a table keyed by tool name, checks the input first, and turns an unknown name or failed check into an is_error result. The Agent SDK does this for Shelfwise. A raw loop needs this code:

try:    out, err = HANDLERS[call.name](**check(call)), False
except (KeyError, ToolError) as e:    out, err = str(e), True
results.append({"type": "tool_result", "tool_use_id": call.id,
                "content": out, "is_error": err})

Client-side tools run in your application, so a Shelfwise lookup takes at least two requests (2.3). Server-side tools, such as web search, web fetch and code execution, run on Anthropic's infrastructure within one request, returning a server_tool_use block and its result block, such as web_search_tool_result. You send no tool_result. The server loop has an iteration limit, and a turn that reaches it ends with stop_reason: "pause_turn". Your loop then resends the conversation with the paused response unchanged and the same tools.

Interactive · who runs each tool call

Three tool calls, each read from top to bottom. Client tool, Shelfwise's stock lookup: your code sends request 1 with the tools and the question; the response ends with stop_reason tool_use and a tool_use block; your harness dispatches and runs the tool; your code sends request 2 with the tool_result; the response ends with end_turn and the answer. Two requests. Server tool, web search: your code sends one request; Anthropic runs the search as a server_tool_use block followed by a web_search_tool_result block, and may search again inside the same request; the response ends with end_turn; your code reads it and sends no tool_result. One request. Server loop paused: your code sends one request; Anthropic searches until the server loop's iteration limit; the response ends with pause_turn; your code resends the history with the paused response unchanged and the same tools; the next response ends with end_turn. Two requests, with the continuations capped. Client tool: stock_lookup TIME request 1 TOOLS + QUESTION stop_reason: tool_use tool_use BLOCK: NAME + INPUT dispatch, check, run YOUR HARNESS RUNS THE TOOL request 2: tool_result SAME tool_use_id stop_reason: end_turn THE ANSWER 2 requests YOUR CODE RUNS THE TOOL Server tool: web_search TIME request web_search ENABLED server_tool_use ANTHROPIC RUNS THE SEARCH web_search_tool_result MAY SEARCH AGAIN, SAME REQUEST stop_reason: end_turn ALL BLOCKS + THE ANSWER read the response NO tool_result TO SEND 1 request ANTHROPIC RUNS THE TOOL Server loop paused TIME request web_search ENABLED searches until the cap SERVER LOOP ITERATION LIMIT stop_reason: pause_turn THE WORK IS NOT FINISHED resend, same tools PAUSED RESPONSE AS IT IS stop_reason: end_turn THE ANSWER 2 requests CAP THE CONTINUATIONS

Choose a kind of tool call.

Client tool: the response stops at tool_use, and nothing happens until your harness runs stock_lookup and sends its tool_result with the same tool_use_id. A Shelfwise lookup is at least two requests.

Server tool: Anthropic runs the search inside your one request and may search again. The response already holds server_tool_use and web_search_tool_result, so your code reads it and sends no tool_result.

Server loop paused: the search loop reached its iteration limit, so the response ends with pause_turn and the work is unfinished. Resend the conversation with that response unchanged and the same tools, and cap how many times you continue.

Each column reads downward. Blue is your code's work, amber is Anthropic's, and the footer counts your requests.

More precise than the guide. The docs sort tools into three groups by where the code runs (as of 2026-10-05). Your code runs user-defined and Anthropic-schema tools, such as bash, and Anthropic runs server-executed tools. Exam answer: a client-side tool is one your application executes, even when Anthropic wrote its schema, and a server-side tool is one Anthropic executes.

Approval patterns put a person between Claude's choice of a call and its side effect. In a raw loop the check sits in dispatch, and a refusal returns as an is_error result. The Agent SDK checks each call in order: hooks, deny rules, ask rules, the permission mode, allow rules, and last your can_use_tool callback, which can ask the person. A call settled earlier never reaches the callback, so read-only tools go in allowed_tools by name and write tools are left to the callback. The mode sets the fallback: dontAsk denies whatever would prompt, acceptEdits approves file edits but not MCP tools, and bypassPermissions approves nearly everything. A check that must see every call is a PreToolUse hook (7.3).

KnowledgeTool set construction best practices

Tool set construction is choosing which tools Claude holds, since every definition costs context and competes for selection. Fewer, well-scoped tools select better: the engineering post prefers one schedule_event tool over separate list_users, list_events and create_event tools. Overlapping tools leave Claude guessing. The docs say selection degrades beyond 30 to 50 tools, so a large library marks most tools defer_loading: true and adds the tool search tool, which loads only the few Claude finds by name and description.

SkillWorked example: a write tool, and who approves it

The owners asked whether staff could reserve items from the chat. The team designed a stock_reserve tool on paper and parked it, since the feed accepts no writes. The first allow list used a wildcard:

allowed_tools=["mcp__stock__*"]                 # draft: approves stock_reserve too
allowed_tools=["mcp__stock__stock_lookup"]      # kept: lookups need no prompt
permission_mode="default", can_use_tool=ask_staff   # staff confirm each reservation

With the wildcard, ask_staff would never run, because the allow rule settles every reservation before the callback runs. Naming only the read-only tool sends each reservation to staff. The mode is set explicitly: a session without one can start in auto mode, where a classifier, not staff, decides.

Before adding a tool, ask: who runs it, and what does a call change? Anthropic runs it → a server tool: read its results and resend on pause_turn. Your code runs a read → a client tool, allowed by name. It changes something → a client tool left out of the allow list and sent to your can_use_tool check, with a timeout and an idempotency key.
Takeaway
  • Server tools come back as server_tool_use plus, normally, a result block in the same response; only client tools wait for your tool_result.
  • Credentials, endpoints and timeouts live in the code that runs a tool, never in its schema or description.
  • In the Agent SDK an approved call never reaches can_use_tool, so a wildcard allow rule skips your approval step.

check yourself

0 / 3 answered

A market-research assistant calls the Messages API with the web search server tool and its own save_note client tool. Its loop runs tools while stop_reason is tool_use and otherwise shows the last text. About one report in twenty stops mid-research: each final response has stop_reason: "pause_turn" and ends with a server_tool_use block that has no result block.What is the most likely root cause?

Select one.

An IT operations agent on the Messages API holds 140 tools from six services, and their definitions add about 60,000 input tokens to every request. It often picks a similar tool from the wrong service, and many questions span two services. Every tool is used weekly by some team, and none may be rewritten or removed this quarter.Which change most directly reduces both the definition tokens in context and the wrong picks, within those limits?

Select one.

A nightly job runs a TypeScript Agent SDK agent with nobody watching. It reaches a vendor's MCP server, registered as crm, with read_account and update_account tools, and the vendor adds tools every few months. Reads must run without a prompt, and no other crm tool, including one the vendor adds later, may run until an engineer has reviewed it.Which TWO settings best meet both requirements?

Select two.

sources

  1. Claude Platform Docs, "Tool use with Claude" and "How tool use works": tool use "also called function calling"; user-defined, Anthropic-schema and server-executed tools; the client loop keyed on stop_reason; the server-side loop, its iteration limit and pause_turn. Checked 2026-10-05.
  2. Claude Platform Docs, "Define tools": name, description and input_schema; detailed descriptions, "by far the most important factor", of at least 3–4 sentences; namespacing; high-signal responses; the four tool_choice options and the models that reject any and tool. Checked 2026-10-05.
  3. Claude Platform Docs, "Handle tool calls" and "Parallel tool use": tool_use fields; tool_result with is_error; instructive error messages; server tool errors handled by Claude; all results in one user message; disable_parallel_tool_use inside tool_choice. Checked 2026-10-05.
  4. Claude Platform Docs, "Server tools": server_tool_use and its result block; no tool_result; continuing a pause_turn response as-is with the same tools, capping continuations. Checked 2026-10-05.
  5. Claude Platform Docs, "Tool search tool": selection accuracy degrading beyond 30–50 tools; defer_loading: true; search over tool names and descriptions. Checked 2026-10-05.
  6. Anthropic Engineering, "Writing effective tools for agents": schedule_event over three tools; namespacing by service and resource; meaningful identifiers; user_id over user; actionable error messages. Checked 2026-10-05.
  7. Claude Code Docs, "Configure permissions", "Handle approvals and user input" and "Connect to external tools with MCP": the evaluation order; auto-approved calls never reaching canUseTool; permission modes and the auto-mode default; mcp__server__* wildcards; acceptEdits not approving MCP tools; credentials in the server's env. Checked 2026-10-05.
  8. Model Context Protocol, "Tools": tool execution errors reported with isError: true. Checked 2026-10-05.
  9. Shelfwise's tool description, its product and branch inputs, the allow list and the parked stock_reserve design are this course's additions to Shelfwise.