CCDV-F Domain 8: Tools and MCPs

A tool definition has exactly three required parts: name, description, and input_schema. The schema is plain JSON Schema — type: "object" at the root, a properties map describing each parameter, and a required array naming which of those parameters must be present. Claude never executes your tool directly; it emits a structured request for your application to run, so the schema is the entire contract between the model's intent and your code's expectations.

{
  "name": "get_current_price",
  "description": "Look up the current market price for a stock ticker. Call this when the user asks about a stock's current, live, or today's price — do not use it for historical prices or general company information, and do not answer price questions from prior knowledge.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Stock ticker symbol, e.g. AAPL"
      }
    },
    "required": ["ticker"]
  },
  "strict": true
}

• name and description are both required, plain strings — Claude reads the description on every turn it considers using a tool, so treat it as documentation the model will act on, not internal comments.
• input_schema must be a JSON Schema object with type: "object"; use enum for parameters with a fixed set of legal values rather than describing the constraint in prose.
• Give every property its own description — Claude uses per-parameter descriptions to decide what value to fill in, separately from the tool-level description that decides whether to call it at all.
• Add strict: true at the top level of the tool definition (a sibling of name/description/input_schema, not a tool_choice setting) when you need guaranteed schema conformance — the returned input is validated exactly against the schema, which removes an entire class of "my code crashed parsing the model's arguments" bugs.

When Claude decides to call a tool, the response carries stop_reason: "tool_use" and one or more tool_use content blocks — each with an id, a name, and an input object matching your schema. This applies to client-side tools: tools you defined and must execute yourself. Server-side tools such as web search, web fetch, and code execution are resolved by Claude directly and never generate a tool_use block your application has to handle.

Your application executes the requested client-side tool(s) and sends the result back as a tool_result content block in the next user turn. The tool_use_id on that block must exactly match the id of the originating tool_use block — this is how Claude correlates a result with the call that produced it, and it is the single most common source of "the model ignored my tool result" bugs when it doesn't match.

// 1) Claude's response — stop_reason: "tool_use"
{
  "stop_reason": "tool_use",
  "content": [
    { "type": "text", "text": "Let me check that." },
    {
      "type": "tool_use",
      "id": "toolu_01A1b2C3",
      "name": "get_current_price",
      "input": { "ticker": "AAPL" }
    }
  ]
}

// 2) Your next user turn — tool_result matched by tool_use_id
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A1b2C3",
      "content": "AAPL: $228.14"
    }
  ]
}

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A1b2C3",
  "content": "Error: ticker 'ZZZZZ' not found. Provide a valid ticker symbol.",
  "is_error": true
}

Parallel tool calls are on by default: a single assistant turn can contain multiple tool_use blocks in one response, and your application is expected to execute them concurrently. Once all results are ready, return every corresponding tool_result block together in one user message — not spread across several follow-up messages.

• Default behavior: Claude may emit multiple tool_use blocks per turn when it judges the calls to be independent (e.g. looking up weather in three different cities).
• Your application should execute independent tool calls concurrently, not serially, to avoid unnecessary latency.
• To force single-tool-per-turn behavior, set disable_parallel_tool_use: true inside tool_choice — this applies regardless of which tool_choice type you're also using.

tool_choice is set per-request, so it's normal to force {"type": "tool", "name": "..."} on one call — for example, when you already know the user wants a specific action performed — and fall back to "auto" for open-ended turns.

The Model Context Protocol (MCP) standardizes how an AI application connects to external context and capabilities. A Host application (Claude Code, Claude Desktop, or your own app) creates one MCP client per connected MCP server; each server exposes context and functionality to the host over that connection.

MCP servers support two transports. stdio is for local, single-client servers — the host launches the server as a subprocess and communicates over standard input/output, which is the natural fit for local development tooling. Streamable HTTP is for remote servers that need to support many concurrent clients; it supports SSE-style streaming over a standard HTTP connection.

Everything in the previous section describes MCP from the consuming side — a host connecting to a server someone else already built. The "MCP Server Development" sub-objective is about the other side: writing that server. A minimal MCP server only needs to do three things: instantiate a server object, register at least one tool with a name, a description, and an input schema in the same JSON-Schema shape covered in this guide's first section, and connect a transport so a host can reach it. Nothing else is required to have a working server.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "example-server", version: "1.0.0" });

server.tool(
  "get_weather",
  "Look up the current weather for a city. Call this when the user asks about current conditions.",
  { city: z.string().describe("City name, e.g. 'Austin'") },
  async ({ city }) => {
    const data = await fetchWeather(city); // your own implementation
    return { content: [{ type: "text", text: JSON.stringify(data) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

McpServer is the high-level, ergonomic API the TypeScript SDK provides specifically so you don't hand-roll the underlying JSON-RPC request handlers yourself — server.tool(...) registers a tool's name, description, and parameter shape in one call, and the SDK derives the JSON-Schema Claude sees from that shape and validates incoming calls against it before your handler runs. TypeScript and Python are the two officially-supported languages for both the Claude SDK and the MCP SDK, so this is the shape worth being able to read even if your own server ends up in Python. SDK APIs evolve, so check the current @modelcontextprotocol/sdk documentation for the exact method signature before shipping — the structure above (instantiate, register, connect) is what to hold onto.

• Stateless protocol. MCP is now explicitly stateless — capability and version information is carried per-request via _meta rather than negotiated once and held in session state.
• Mandatory `server/discover` handshake. A new required handshake replaces the older assumption of a single up-front initialize exchange whose results persisted for the connection's lifetime.
• Sampling and Logging primitives are deprecated. Don't teach or expect these as current best practice — use direct LLM-provider APIs in place of the old Sampling primitive, and OpenTelemetry in place of the old Logging primitive.
• Notifications are opt-in. Subscribe via subscriptions/listen; the old push-by-default notification model is gone.

Transport and auth also changed. Streamable HTTP has fully superseded the older, separate "HTTP+SSE" transport — don't present HTTP+SSE as the current recommendation for remote MCP servers; it's the pattern Streamable HTTP replaced.

A real decision developers face on every project: given a capability the agent needs, which mechanism should implement it? The right answer trades off implementation effort, how much control you need over execution, and how reusable the capability needs to be across different tools and hosts.

One Anthropic-specific detail worth knowing at the API level: the Messages API supports an mcp_servers / mcp_toolset parameter (the "MCP connector," currently in beta) that lets Claude call a remote MCP server directly, server-side, without your application acting as the MCP client itself. This sits alongside — not instead of — the standard client-side approach of connecting to an MCP server from your own host application.