Skip to main content

Class 20: Beyond Tool Enumeration

Duration: 25 minutes | Difficulty: Intermediate | Prerequisites: Class 18.

By the end of this lesson you will be able to describe the design pattern that Anthropic published as "Code Execution with MCP" in November 2025. You will also know why it is the most likely challenge to the tool-enumeration model that the previous nineteen lessons use, and which parts of your architecture would carry over or need rewriting. This is the only lesson without new code. Its goal is to help you judge what to watch over the next twelve to eighteen months.

This lesson uses several terms that may be new. Each one gets a fuller explanation where the lesson puts it to work:

  • Tool enumeration is the canonical MCP pattern this course built, where the model receives the full list of tool definitions and picks one.
  • Context window is the amount of text, measured in tokens, that a model can read in one request.
  • Code Execution with MCP, often called code mode, lets an agent use MCP tools by writing and running code in a sandbox.
  • Tool Search Tool is a Claude API feature that keeps tool definitions marked defer_loading: true out of the context until the model searches for them.
  • Programmatic tool calling is a Claude API feature where the model writes code that calls tools, so intermediate results stay out of the conversation.
  • Codegen generates typed client code, a typed SDK, from a GraphQL schema and its operations.
  • TSDoc is the documentation-comment format for TypeScript, the TypeScript equivalent of Javadoc.
  • GraphQL AI Working Group is the GraphQL Foundation group that works on standards for GraphQL and AI agents.
  • GAPs (GraphQL Auxiliary Proposals) are community proposals published next to the GraphQL specification.

The Pattern That Changes the Picture​

Two months after GraphQLConf 2025 ended, Anthropic published an engineering blog post titled Code Execution with MCP. The post makes a specific architectural argument and supports it with a specific benchmark.

The argument is that the canonical MCP pattern, which this tutorial built over nineteen lessons, is the wrong shape for large workloads. The canonical pattern lists every tool for the model up front. At every turn, the model reads the tool list (name, description, input schema), picks a tool and fills in its arguments, and the server runs it.

The tool list grows with the number of tools, and the measured numbers are higher than most people expect. With ten tools, the list reaches a few thousand tokens. In the setup Anthropic measured, with five servers and 58 tools, the definitions alone used roughly 55,000 tokens. With ten or more federated MCP servers, the list can fill much of the context window before the first user message arrives, and every conversation pays that cost on every turn.

The proposed alternative stops sending the tool list. The agent runs in a sandboxed code-execution environment, where the MCP servers appear as code modules it can import. The agent writes and runs code that imports the tools it needs and calls them as functions. Intermediate results stay in that environment, out of the conversation. The model sees only the final result that it asks the code to print. To discover tools, the agent browses a filesystem, so it pays for the definitions it reads, instead of the whole catalog on every turn. Anthropic's post has the current details of its reference implementation, including the runtime and language, and those details change over time.

The benchmark gives the argument weight. On a realistic agent task that Anthropic measured, the canonical pattern used about 150,000 tokens, and the code-execution pattern used about 2,000, a reduction of 98.7%. The post credits two mechanisms: loading tool definitions only when needed, and filtering intermediate results inside the runtime so they stay out of the conversation. The published numbers do not say how much each mechanism contributes. The 98.7% figure will keep this pattern in front of teams that build agents.

Why the argument is hard to dismiss

Two things make Anthropic's argument more solid than a typical prediction that everything will change:

  • The idea is already in use. Agents that write and run code are common, in Claude Code, Code Interpreter, Cursor and Cline. The only new piece is the sandboxed layer that turns MCP servers into modules.
  • The post has measurements. Anthropic presents the pattern with measured results.

The Middle Option: Tool Search and Programmatic Tool Calling​

Code execution is one alternative to listing every tool up front, and Anthropic released a middle option two weeks after the code-execution post. In November 2025 the Claude API added the Tool Search Tool and programmatic tool calling, announced together as "advanced tool use". This option keeps the canonical tool-calling model and avoids paying for the full tool list. Tool definitions marked defer_loading: true stay out of the context window, in a searchable catalog. The application that calls the Claude API sets that flag on the request's tools array, so your MCP server stays as it is. A Spring AI server keeps exposing its tools exactly as the lessons from Class 6 onward built them.

The full definitions are still sent with every request, because the API needs them on its side to run the search. defer_loading decides what enters the context, not what is sent. The model searches for the tools it needs, and the API expands only those into full definitions. In Anthropic's example, five servers with 58 tools used roughly 55,000 tokens of definitions, and that dropped to about 8,700, a reduction of about 85%, with every tool left unchanged.

Programmatic tool calling came in the same release. The model writes code that calls tools and processes their intermediate results inside an execution container, so only the final result enters the conversation. Both are standard features on current Claude models. Tool search works with MCP through the API's MCP connector, which can defer all of a server's tools with one configuration flag.

Tool search and programmatic tool calling are the incremental solution. They reduce the context cost of the tool-enumeration model, and the architecture you built in this tutorial stays as it is. Code execution with MCP is the radical option, and it replaces the enumeration model completely. If the incremental solution is enough for most workloads, teams have less reason to adopt the radical one, so watch for that. The search-then-load idea should look familiar. It is the approach that Class 4b used at the GraphQL layer, applied one level up, to the tool catalog.

How GraphQL Fits​

If the code-execution model replaces the tool-enumeration model, GraphQL keeps a role in a different place. In the new model, the agent works mainly with a typed code SDK on a filesystem, and the MCP server is no longer the main interface. The MCP server may remain for capability negotiation, authentication and the few operations that need streaming or two-way patterns that the SDK cannot easily provide. Most of the agent's work with your backend looks like ordinary code that calls typed functions.

A GraphQL codegen pipeline already produces the kind of typed SDK that this model needs, and several tools do it today:

Each one reads a schema and generates typed clients, inputs and results. An agent that imports such an SDK and writes code against it does what a frontend developer does, but on its own and inside a sandbox.

The diagram below compares the two shapes, with the canonical MCP pattern at the top and the code-execution pattern below it.

Both shapes use the same GraphQL backend and the same schema. Only the layer between the agent and the schema changes. In the canonical model, MCP is a thick layer that translates what the agent wants into GraphQL operations. In the code-execution model, MCP is a thin layer for the few things the typed SDK cannot do, and the SDK handles most of the agent's work.

Preparing for both futures

To stay ready for either future, keep your GraphQL schema clean, and build a good codegen pipeline next to your MCP server. Both futures depend on a good schema. If MCP stays, the work in Classes 1 to 19 was the right work. If code execution takes over, the same schema generates the TypeScript or Python SDK that the agent imports. Either way, the schema matters most, and good descriptions, accurate nullability and reviewed types help in both.

What Stays, What Changes​

Suppose you moved the same backend to the code-execution model. Some parts of what you built would keep their value, and some would need rewriting.

Stays valuable. Your schema descriptions keep their value in every future. They become the that the canonical pattern uses today, and they would become the comments in the generated SDK of the code-execution model.

The descriptions from Class 3 are the longest-lasting work in this tutorial. Other work also carries over:

  • Structured outputs from Class 9, because typed return shapes belong to the schema, not the transport.
  • Authorization from Class 15, because the agent needs an identity whichever pattern it uses to call the backend.
  • Observability from Class 17, because both patterns produce GraphQL traffic that your existing dashboards already measure.

Needs to change. The tool registration code from Classes 6 to 8 would go. A code-generation step that produces one typed module per operation would replace the @McpTool annotations and the schema-derived descriptions wired through the customizer. The deployment topology changes too, because the MCP server becomes a smaller layer for a few capabilities. The testing approach from Class 12 also changes. Tests stop checking that a tool called with certain arguments returns X, and start checking that agent code imported the SDK and produced output Y.

Becomes less important. Tool descriptions written to fit the canonical MCP tool_list matter less. Those descriptions are short, focused on the decision, and written for a model that has not seen the full schema. The agent in the code-execution model has the full SDK on the filesystem, so it can read the type definitions directly. Per-operation descriptions become TSDoc, which reads differently from the "use this when..." instructions that Class 5 covered.

As a rough estimate, 60 to 70 percent of what you built in this tutorial would carry over to the code-execution model without schema or code changes. Another 20 to 30 percent would be replaced by codegen output, and a small remainder would no longer be needed. That split is much better than it would be for the same interface built on REST or OpenAPI, because both futures use the typed schema.

Concrete Things to Watch For​

Three signals will show whether the field is really moving toward the code-execution model, and whether shipped implementations follow what people write about it.

The first is platform support. Since the original post, "code mode" has become the common name for the pattern, and more platforms support it. Cloudflare's Code Mode compiles MCP servers into TypeScript APIs for a sandboxed runtime. It started as a blog post and now has its own page in the Cloudflare Agents documentation. The Claude API's tool search and programmatic tool calling moved part of the idea into the API itself.

At GraphQLConf 2026, WunderGraph's talk "Search and Execute with Code Mode Backed by the Graph" showed the pattern applied to a GraphQL API, which is the closest example to what this course teaches. If three or more major agent platforms support the full pattern as a built-in option by late 2026, the pattern has arrived, and your team should plan for it. The likely candidates are Cursor, Cline, Continue, LangGraph, the Vercel AI SDK and the major coding-agent products from other vendors. If only a few platforms support it by then, treat it as a promising optimization that has yet to spread across the field.

The second is the maturity of codegen tools. The pattern needs good typed-SDK generation from GraphQL schemas. That tooling exists today, for example graphql-codegen's client preset, Apollo's clients, and ariadne-codegen or sgqlc for Python, but it was designed for use by developers and applications. Watch for new codegen targets aimed at agents, such as output with rich TSDoc, runtime introspection helpers and error shapes that agents expect. When the first major codegen project ships a "for agents" preset, the field has made its choice.

The third is the GraphQL AI Working Group's standards activity. Recent working-group discussions have covered schema-design guidance for the canonical pattern. Topics include:

  • subschema directives
  • semantic introspection, which Hot Chocolate v16 has since shipped as a product feature
  • an @mock directive proposal, since published as GAP-10 among the community GraphQL Auxiliary Proposals
  • open-source embedding approaches for schema navigation

If the working group starts publishing guidance for typed SDKs, the standards work is following the field. Examples would be conventions for the fields a typed SDK selects by default, or for how error unions look in TypeScript or Python. If the working group stays focused on the canonical pattern, the field has not made its choice yet.

Whichever way these signals go, the architecture you built in this tutorial can adapt. The schema keeps its value, the descriptions carry over, and the auth and observability work is independent of the agent transport. The work you would redo sits in Classes 6 to 8 (the tool-registration layer) and in part of Class 18 (the agent client). That part is small enough to rewrite when the time comes.

Closing Thought​

This tutorial started from one idea: the schema is the contract, and everything else is wiring around it. That idea still holds with Anthropic's pattern. Tools, transports, registration patterns, host applications and agent frameworks will probably all change more than once over the next five years. The schema you wrote is the most stable part of your agent stack, more stable than the SDK, the MCP server, the agent framework or the model. Spend your effort on it.

GraphQL was designed before AI agents existed. People building agents keep choosing it, because agents need a typed, documented, introspectable and validated contract, and GraphQL has provided that since 2015. Anthropic's pattern and the patterns that follow it will all be wiring around the same kind of contract.

You finished a long tutorial. Thank you for reading it. However the field changes in 2027, the work you did here will still be useful, because the schema is the part that lasts.

Summary​

This lesson looked at where the field may go. Anthropic's "Code Execution with MCP" post argues that listing every tool up front is the wrong shape for large workloads. It shows a 98.7% token reduction from letting the agent import MCP servers as code modules in a sandbox. Between that radical option and the current model sits an incremental one: the Claude API's tool search and programmatic tool calling, which keep the canonical model but load tool definitions only when needed. In either future, the schema, its descriptions, the auth and the observability all carry over, and only the small tool-registration layer would need rewriting. Watch platform adoption, codegen maturity and the GraphQL AI Working Group's output to decide whether and when to change course.

Further Reading​

What's Next​

This is the last lesson of the course. Next comes your own project: pick a track, apply the lessons that every track shares, and watch the three signals from this lesson. This course kept the MCP server inside the GraphQL application to keep the lessons simple. We plan a follow-up course that builds a more capable standalone MCP server, the production shape that Class 17 describes. The GraphQL AI Working Group meets in public, and reading its agendas is an easy way to follow the standards work. If the field changes, you now know which parts of your stack would need to change with it.