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.
share
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
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.
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.
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.- Server tools come back as
server_tool_useplus, normally, a result block in the same response; only client tools wait for yourtool_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.