A3.4 · LESSON 4 OF 6

Tools

Explain MCP roles and lifecycle and trace a tool-discovery and tool-call exchange under a pinned protocol version.

THE IDEA

Tools

Discover a server's tools with tools/list, then invoke one by name with tools/call. A result has a content array and an isError flag. Failures come in two separate kinds. A protocol error (an unknown tool, a malformed request) is a JSON-RPC error object such as -32602. A tool execution error (bad arguments, a failing API) is a normal result with isError true, so the model can read it and correct the call.

request: { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "add", "arguments": { "a": 2, "b": 3 }, "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} } } } response: { "jsonrpc": "2.0", "id": 2, "result": { "resultType": "complete", "content": [ { "type": "text", "text": "5" } ], "isError": false } }

success: content array with isError false

Two kinds of failure stay separate. A malformed request or an unknown tool is a protocol error; bad arguments or a failing API inside a tool is a result flagged isError.

Try a good call and two different failures.

Predict first. Which method invokes a tool in the examined specification?

Chapter context

MCP defines a protocol for applications to connect models with external capabilities. It standardizes exchanges; it does not grant a server universal authority or make every discovered tool appropriate for every user request.

TRY IT YOURSELF

Live lab

List the server's tools, call one, then make it fail in two different ways. The protocol separates errors in the request itself from errors that happen while a tool runs.

TRY IT YOURSELF

Discover and call a tool

List the server's tools, call one, then make it fail in two different ways. The protocol separates errors in the request itself from errors that happen while a tool runs.

Your goal

Observe tools/list, a successful tools/call, an unknown tool (a protocol error), and bad arguments (a tool execution error).

This simulated server speaks protocol revision 2026-07-28. Edit the JSON freely, then send it.

List the tools
Call add and get 5 back
Call a tool that does not exist (protocol error)
Call add with a string argument (tool execution error)

Request (JSON-RPC)

Exercises

Part 1. Do it hands-on

Name the methods and classify two failures by hand, then write the tool handlers.

success: content array with isError false

Two kinds of failure stay separate. A malformed request or an unknown tool is a protocol error; bad arguments or a failing API inside a tool is a result flagged isError.

method that lists tools method that invokes one unknown tool: protocol or tool? string argument: protocol or tool?

To do: Which method lists a server's tools?
To do: Which method invokes a tool by name?
To do: tools/call names a tool that does not exist. Is that a protocol error (a JSON-RPC error object) or a tool execution error (a normal result with isError)? Type protocol or tool
To do: tools/call add with arguments {a: "2", b: 3} (a string). Protocol error or tool execution error? Type protocol or tool

Part 2. Do it in code

check_envelope(text) and error_response(id, code, message, data=None) are PROVIDED (the stateless envelope checks from the previous lesson: -32700, -32600, -32601 for initialize, -32602 for missing _meta, -32022 for an unsupported version). check_envelope returns an error response or the parsed request.
tools_list(req): the success response whose result has resultType "complete" and tools = [ADD], where ADD has name add, description "Add two numbers." and an inputSchema requiring numbers a and b.
tools_call(req): params carry name and arguments. An unknown tool name is a PROTOCOL error: -32602 "Unknown tool: <name>". For add, arguments that are not both numbers (bool is not a number) are a TOOL EXECUTION error: a normal success response whose result has content [{"type": "text", "text": "Invalid arguments: ..."}] and isError True. Otherwise content [{"type": "text", "text": str(a + b)}] and isError False (resultType "complete" in all of them).
handle(text): run check_envelope; return its error if any; None for a notification; otherwise dispatch tools/list and tools/call; any other method → -32601.

import json

VERSION = "2026-07-28"
VKEY = "io.modelcontextprotocol/protocolVersion"
CKEY = "io.modelcontextprotocol/clientCapabilities"
ADD = {"name": "add", "description": "Add two numbers.", "inputSchema": {"type": "object", "properties": {"a": {"type": "number"}, "b": {"type": "number"}}, "required": ["a", "b"]}}

def error_response(id, code, message, data=None):
    e = {"code": code, "message": message}
    if data is not None:
        e["data"] = data
    return {"jsonrpc": "2.0", "id": id, "error": e}

def check_envelope(text):
    try:
        req = json.loads(text)
    except Exception:
        return error_response(None, -32700, "Parse error")
    if not isinstance(req, dict) or req.get("jsonrpc") != "2.0" or not isinstance(req.get("method"), str):
        return error_response(req.get("id") if isinstance(req, dict) else None, -32600, "Invalid request")
    if "id" not in req:
        return req
    if req["method"] == "initialize":
        return error_response(req["id"], -32601, "initialize belongs to older revisions", {"supported": [VERSION]})
    meta = (req.get("params") or {}).get("_meta") or {}
    missing = [k for k, ok in ((VKEY, VKEY in meta), (CKEY, isinstance(meta.get(CKEY), dict))) if not ok]
    if missing:
        return error_response(req["id"], -32602, "Invalid params: missing required _meta field(s): " + ", ".join(missing))
    if meta[VKEY] != VERSION:
        return error_response(req["id"], -32022, "Unsupported protocol version", {"supported": [VERSION], "requested": meta[VKEY]})
    return req

def tools_list(req):
    pass

def tools_call(req):
    pass

def handle(text):
    pass

Ctrl/⌘ + Enter runs it

Both the live lab and the exercises must be solved to finish this lesson.

Stuck, or something not working? You can come back to it any time.

CHECK YOUR UNDERSTANDING

Which method invokes a tool in the examined spec?

Atools/listBtools/runCtools/call.

Chapter reference: math, worked example & code

This section belongs to the whole chapter, so it is the same on every lesson in it and may cover a different lesson's topic. The code for the experiment you just ran is inside the experiment itself.

Math and notation

The MCP specification revision examined here is 2026-07-28. Request envelopes use JSON-RPC 2.0, an ID for response correlation, a method, and method-specific parameters that include _meta with the required io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities. A successful result carries resultType, here "complete". Do not treat this date as a claim about every installed client or SDK.

Worked example

A tools/call request with id 7 names add, supplies a=2,b=3 and carries the protocol version and client capabilities in _meta. The server runs the permitted operation and answers with the same id and a content array holding the text 5. The offline example below checks envelope fields and arithmetic; a production server must also implement discovery, schema validation, errors and transport behavior.

Reference code

The following example uses the Python standard library and does not call a remote service.

meta={'io.modelcontextprotocol/protocolVersion':'2026-07-28','io.modelcontextprotocol/clientCapabilities':{}}
request={'jsonrpc':'2.0','id':7,'method':'tools/call','params':{'name':'add','arguments':{'a':2,'b':3},'_meta':meta}}
args=request['params']['arguments']
total=args['a']+args['b']
response={'jsonrpc':'2.0','id':request['id'],'result':{'resultType':'complete','content':[{'type':'text','text':str(total)}],'isError':False}}
assert request['method'] == 'tools/call'
assert request['params']['_meta']['io.modelcontextprotocol/protocolVersion'] == '2026-07-28'
assert response['id'] == 7
assert response['result']['content'][0]['text'] == '5'
assert response['result']['isError'] is False

Python examples are provided for study and local execution; this page does not execute Python.

Common mistakes

MCP is not a language model or an automatic permission system. Resource, prompt and tool capabilities differ. Do not assume an initialize handshake: that belongs to revisions before 2026-07-28. Protocol versions and SDK releases must be matched when turning this draft into runnable setup instructions.