Tools and MCPs — study note

This note covers Domain 8 of the Claude Certified Developer – Foundations exam. It has three skills:

tool implementation;
MCP server development;
agentic customization.

It summarizes what each topic teaches and the Anthropic pages behind it. On purpose, it teaches mechanisms rather than numbers. Token limits, timeouts, beta headers and version-dated tool types change often, so look them up on the linked pages when you need them.

Defining a tool

A user-defined tool has four fields.

Field	What it carries
`name`	Letters, digits, `_` and `-` only
`description`	What, when, parameters, caveats
`input_schema`	A JSON Schema for the input
`input_examples`	Optional well-formed inputs

The description matters most. Detailed descriptions are by far the most important factor in tool performance. Aim for at least three or four sentences: what the tool does, when to use it and when not to, what each parameter means, and caveats such as what it does not return.
Input examples help complex tools with nested objects, optional parameters or format-sensitive inputs. Each must be valid against the schema, and they add prompt tokens. Server tools do not take them.
Name by service when tools span services, and consider grouping one service's operations into a single tool with an action parameter.
When Claude calls a tool. By default Claude calls one when the request maps to its described use and the answer is not already in context. You can move that boundary in the system prompt; tool_choice requires a call on models and settings that support it. Changing tool_choice invalidates cached message blocks.
Branch on blocks, not words. The text Claude writes before a call varies, so read the tool use block itself.

Answering calls

Situation	What your code sends
A normal result	A `tool_result` with the call's id
Nothing to report	The same, with no content
An image or a file	A list of text, image or document blocks
The tool failed	Content plus `is_error: true`

Tool results go in a user message; the Claude API has no separate tool role. Results come first, and any text comes after them.
Instructive errors. Say what went wrong and what Claude should try next. If a call is missing a parameter, Claude retries with the information filled in; during development, the best fix is a more detailed description.
Keep untrusted content, such as web pages or email, inside the tool result.

Client tools and server tools

Client tool	Server tool
Runs in your application	Runs on Anthropic's platform
Call block: `tool_use`	Call block: `server_tool_use`
You send back a `tool_result`	You send back nothing
You set `is_error`	Claude handles errors

Server tool ids start with srvtoolu_. Server tools can add usage-based charges of their own.
Mixed turns. When Claude calls a server tool and a client tool together, the API does not run the server tool yet. Detect it by a server call with no matching result. Send a user message with only your tool results and keep the same tools array; the next response opens with the server result, paired by id.
Domain filters for the web tools: no scheme, subdomains included, wildcards only in the path, and web fetch matches the domain only. Use either an allowed list or a blocked list, not both, and keep entries ASCII-only.

Tool sets agents can use well

From Anthropic's engineering article on writing tools for agents:

Build tools for workflows, not one per API endpoint: search rather than list, and handle chained steps in one call.
Return what the agent will act on, and let it ask for concise or detailed responses.
Page, filter or truncate large responses with sensible defaults, and say how to get more when you cut a result.
Evaluate on realistic tasks that need several calls, with verifiers that accept valid alternative phrasings, and keep a held-out set.

MCP in Claude Code

Resources: reference them with @server:protocol://path; they are fetched as attachments.
Prompts become commands; arguments split on whitespace.
Live updates: servers can change their tools, prompts and resources without a reconnect, and can ask you for input mid-task through elicitation.
For server authors: write server instructions that say when to use your tools, put key details first, give a larger result allowance to tools with big but necessary output, and mark consent-style tools as requiring approval on every call.

The MCP connector

The connector lets the Messages API call remote MCP servers without an MCP client of your own. A server entry in mcp_servers holds the connection; an MCP toolset in tools chooses and configures its tools.

Pattern	Toolset setting
Every tool	No defaults, no configs
Allowlist	Default off, enable named tools
Denylist	Default on, disable named tools

Per-tool configs override the toolset's defaults, which override the system defaults. You own the OAuth flow and token refresh, and the connector is not covered by zero data retention.

MCP in the Agent SDK

Pass servers in the MCP servers option; tools are named mcp__server__tool.
MCP tools need explicit permission: list them in allowed tools. Accept-edits mode does not approve them, and bypass mode approves far more than MCP.
Pass credentials through the server's env field, and restrict writes in the server's own configuration.
Read each server's status in the init message; pending on its own is not a failure. The SDK runs no OAuth flow, so authorize in your application and pass the token in headers.

Choosing an extension

Need	Extension
Always-on conventions	CLAUDE.md
Knowledge or a workflow, sometimes	Skill
An external system's data or actions	MCP server
A noisy side task	Subagent
An action on every event	Hook
The same setup in another repository	Plugin

Each loads differently: CLAUDE.md in full every session, a skill's description first and its body on use, an MCP server's tool names first and schemas later, a subagent in its own window, and a hook not at all unless it returns output. A skill and an MCP server combine well: the server connects, the skill teaches Claude how to use it.

Skills

Progressive disclosure: name and description always, the SKILL.md body when triggered, bundled files and scripts only when needed. Scripts run, and only their output enters context.
Description: say what the skill does and when to use it.
Surfaces: on the Claude API, skills are workspace-wide and run without network access or runtime installs; in Claude Code they are files on disk; in claude.ai they are per user. Uploads do not sync between surfaces.
Names use lowercase letters, numbers and hyphens, and cannot contain "anthropic" or "claude". In Claude Code, dynamic context injection runs a command and inlines its output before Claude reads the skill.
Trust: use skills you wrote or got from Anthropic, and audit every bundled file of any other.

Custom tools in the Agent SDK

Define a tool with a name, a description, an input schema and an async handler, wrap it in an in-process SDK MCP server, and list its full name in allowed tools.
In Python, the simple dict schema makes every key required; use a full JSON Schema dict for optional fields and enums.
A handler error does not stop the loop. Catch errors and return is_error with a message Claude can act on.
Annotations describe behaviour; they do not enforce it. Images are returned as base64 bytes, never as a URL.

Sources

Tool use with Claude — https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
Define tools — https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
Handle tool calls — https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls
Server tools — https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools
Writing effective tools for agents — https://www.anthropic.com/engineering/writing-tools-for-agents
Connect Claude Code to tools via MCP — https://code.claude.com/docs/en/mcp
MCP connector — https://platform.claude.com/docs/en/agents-and-tools/mcp-connector
Connect to external tools with MCP (Agent SDK) — https://code.claude.com/docs/en/agent-sdk/mcp
Extend Claude Code — https://code.claude.com/docs/en/features-overview
Agent Skills — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
Extend Claude with skills — https://code.claude.com/docs/en/skills
Give Claude custom tools — https://code.claude.com/docs/en/agent-sdk/custom-tools