D2 · Tool Design & MCP › Cluster 6 · MCP Primitives

6.1 · Tools (Server-Exposed Functions)

Model-controlled actions

CONCEPT Tools are the model-controlled primitive

An MCP server exposes tools so a language model can act on the world — query a database, call an API, run a computation. The defining property, and the one the exam loves: tools are model-controlled. The spec says tools "are designed to be model-controlled, meaning that the language model can discover and invoke tools automatically based on its contextual understanding and the user's prompts." The model decides when to call — nobody hand-picks the call.

Every tool is uniquely identified by a name and carries an inputSchema (JSON Schema) that tells the model what arguments it accepts. The client discovers tools with tools/list and the model triggers an invocation, which the client sends as tools/call.

AspectHow tools work
ControlModel-controlled — the LLM decides to call
Discoverytools/list → returns name, title, description, inputSchema
Invocationtools/call with name + arguments
Returncontent array (text / image / audio / resource) + isError flag
Change signalnotifications/tools/list_changed (if listChanged declared)
NatureAn action with side effects — not just data
🔑 Even though the model drives invocation, the spec insists there SHOULD always be a human in the loop able to deny a tool call. Model-controlled means the model chooses; it doesn't mean the app must execute blindly.

CONCEPT Two ways a tool reports failure

Distinguish the two error channels — a classic trap. A malformed or unknown call is a protocol error (standard JSON-RPC error, e.g. -32602 Unknown tool). A tool that ran but failed at its job (API down, bad business input) returns a normal result with isError: true inside it. The second kind is deliberately surfaced back to the model so it can read the error text and adapt.

Business/runtime failures → isError: true in the result (the model sees it and can retry). Protocol violations → JSON-RPC error object (the model never asked validly).

DIAGRAM Discover → model selects → call → result

sequenceDiagram participant LLM participant Client participant Server Note over Client,Server: Discovery Client->>Server: tools/list Server-->>Client: [get_weather, ...] + inputSchema Note over Client,LLM: Model-controlled selection LLM->>Client: "call get_weather(New York)" Note over Client,Server: Invocation Client->>Server: tools/call {name, arguments} Server-->>Client: {content:[...], isError:false} Client->>LLM: Process result Note over Client,Server: Updates Server--)Client: notifications/tools/list_changed classDef srv fill:#d4edda,stroke:#28a745,color:#155724; classDef cli fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class Server srv; class Client cli;

CODE A tool definition, a call, and its result

The server advertises get_weather via tools/list; the model triggers a tools/call; the server replies with a content array and isError.

// tools/list  → server advertises the tool (name + JSON Schema)
{
  "name": "get_weather",
  "title": "Weather Information Provider",
  "description": "Get current weather for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name or zip code" }
    },
    "required": ["location"]
  }
}

// tools/call  → the model invokes it
{ "method": "tools/call",
  "params": { "name": "get_weather", "arguments": { "location": "New York" } } }

// result  → content array + isError flag
{ "content": [ { "type": "text", "text": "72°F, partly cloudy" } ],
  "isError": false }
🔑 Compare with 6.2: a Resource named weather://forecast would return the same data as readable context with no side effect — a Tool does the fetch as an action the model chose. Same information, opposite control model.

TRADE-OFFS Model-controlled power vs. safety

✅ Tools (model-controlled)

  • Model can act autonomously — real agentic reach
  • Typed inputSchema lets the model call correctly
  • isError lets the model self-correct on failure

⚠️ The cost of that autonomy

  • Side effects: a wrong call can delete/charge/send
  • Needs human-in-the-loop confirm on sensitive ops
  • Annotations are untrusted unless the server is trusted

EXAM TRAPS

Trap: "The user picks which tool runs." → No. Tools are model-controlled; the LLM decides based on context. That's exactly what separates them from user-controlled Prompts (6.3).
Trap: Confusing the two error paths. → A failed job returns isError: true inside a normal result (model sees it); an invalid/unknown call returns a JSON-RPC error.
Trap: "Tools return data like resources." → Tools act (side effects); Resources expose readable data. Same info can appear as either — the control model is the difference.
Trap: Trusting tool annotations blindly. → The spec says clients MUST treat annotations as untrusted unless they come from a trusted server.

PRACTICE

Q1 · Which two protocol methods cover tool discovery and invocation?

tools/list to discover (returns each tool's name, description, and inputSchema), and tools/call to invoke (with name + arguments).

Q2 · A tool ran but the upstream API was rate-limited. How is that reported?

As a normal result with isError: true and the error text in the content array — so the model can read it and adapt. It is not a JSON-RPC protocol error (those are for unknown tools / invalid arguments).

Q3 · Why are tools called "model-controlled," and what safety follows?

Because the LLM decides when to invoke them from context. Since that autonomy can trigger side effects, the spec says there SHOULD always be a human able to deny an invocation, and clients SHOULD confirm sensitive operations.