Tool Invocation Flow

+15 Mana ✨
MCP Tools Lifecycle(DOCUMENTATION)MCP Transports(DOCUMENTATION)

Introduction

Understanding the complete lifecycle of a tool invocation is essential for building robust MCP integrations. From the moment a user sends a message to when they receive a final response, multiple actors coordinate through well-defined steps. This lesson walks through the end-to-end flow, including progress tracking, cancellation, and multi-step tool use.

Key Concepts

The tool invocation flow involves four actors: the user, the LLM, the MCP client, and the MCP server. Each plays a specific role:

  1. The user sends a message to the LLM
  2. The LLM analyzes the message and decides a tool call is needed
  3. The client sends a tools/call request to the server
  4. The server executes the tool and returns the result
  5. The LLM incorporates the result into its final response

This flow is sequential and deterministic. The LLM is always the decision-maker — it chooses which tool to call based on the user's intent and the available tool descriptions.

Real World Context

Imagine asking an AI assistant: "What is the weather in Paris and should I bring an umbrella?" The LLM recognizes it needs weather data, selects the get_weather tool, the client sends the request, the server queries a weather API, and the result flows back. The LLM then uses the weather data to provide a natural-language recommendation. The user never interacts with the tool directly.

Deep Dive

Here is the detailed sequence of a tool invocation:

text
User: "What's the weather in Paris?"
  ↓
LLM: Analyzes message, selects get_weather tool
  ↓
Client: sends tools/call {name: "get_weather", arguments: {location: "Paris"}}
  ↓
Server: Executes tool, queries weather API
  ↓
Server: Returns {content: [{type: "text", text: "15°C, Rain"}], isError: false}
  ↓
LLM: "It's 15°C and rainy in Paris. Bring an umbrella!"

This text diagram shows the linear flow from user message to final response.

For long-running tools, the server can send progress notifications during execution. These notifications inform the client about completion percentage, allowing it to display a progress bar or status message to the user. Progress notifications use the notifications/progress method with a progressToken that the client includes in the original tools/call request.

Here is an example of a progress notification:

json
{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"abc-123","progress":50,"total":100,"message":"Processing records..."}}

The progress and total fields let clients calculate a percentage, while the optional message field provides human-readable status.

Cancellation allows the client to abort a long-running tool call. If the user navigates away or changes their mind, the client sends a notifications/cancelled notification with the request ID. The server should stop execution as soon as possible, though cancellation is best-effort — the server may have already completed the work.

Multi-step tool use occurs when the LLM needs to call multiple tools to answer a single question. For example, the LLM might call search_docs to find relevant articles, then call summarize to condense the results. Each tool call follows the same flow, and the LLM chains them together by incorporating each result before deciding on the next step.

Common Pitfalls

  • Assuming tool calls are instant: Long-running tools need progress tracking and cancellation support. Always design for the possibility of slow operations.
  • Forgetting multi-step flows: The LLM may need several tool calls to fulfill a single request. Each call is independent and follows the full invocation flow.
  • Ignoring cancellation: If a user aborts a request, the client should send a cancellation notification. Servers that ignore cancellation waste resources on abandoned work.

Best Practices

  • Include progressToken in tools/call requests for tools that might take more than a few seconds.
  • Implement cancellation handling in servers to clean up resources when a request is aborted.
  • Design tool descriptions to help the LLM chain tools effectively — mention what data each tool returns and what it can be combined with.
  • Log each step of the invocation flow for debugging and observability.

Summary

The tool invocation flow follows a clear sequence: user message, LLM decision, client request, server execution, and LLM response generation. Progress notifications keep users informed during long operations, cancellation lets them abort, and multi-step tool use enables complex workflows. The LLM always remains the orchestrator, deciding which tools to call and how to incorporate their results.

Code Examples

json
{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"abc-123","progress":50,"total":100,"message":"Processing records..."}}

{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":2,"reason":"User navigated away"}}
✓ Completed