All chapters
  1. Start hereThe model proposes a call. Your code decides whether it runs
  2. Foundations · 1Functions: arguments, return values and side effects
  3. Foundations · 2Tool calling: how a model asks, and the loop that answers
  4. Foundations · 3Tool schemas: names, descriptions and argument constraints
  5. Foundations · 4Types and annotations: one source for the schema and the handler
  6. Foundations · 5Result contracts: success, error, partial result, reference
  7. Protocols · 6Discovery and selection: how the right tool gets chosen
  8. Protocols · 7MCP architecture: host, client, server, tools, resources, prompts
  9. Protocols · 8MCP on the wire: transports, lifecycle, authorization, notifications
  10. Protocols · 9Retrieval: a tool the model calls, or knowledge it is given
  11. Production · 10Implementing tools: API wrappers, database queries, files, code execution
  12. Production · 11Safety: least privilege, validation, idempotency, sandboxing
  13. Production · 12Reliability: timeouts, retries, rate limits, circuit breakers
  14. Production · 13Testing tools: contracts, stand-ins, faults and traces
  15. Reference · 14Frameworks and standards: what each one does for a tool
  16. Reference · 15Advanced: composition, pagination, streaming, binary content, observability
  17. Reference · 16The insurance lab: one submission, five tools, end to end
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Reference · 14

Frameworks and standards: what each one does for a tool

JSON Schema, JSON-RPC and the Model Context Protocol as standards; provider tool-calling APIs, MCP SDKs, LangChain tools, Spring AI and LangChain4j as libraries, each read on its own documentation.

What you will understand
Which named thing is a standard, which is a provider API, and which is a library, and why the difference decides what you can swap later.
What you can do
Read one section and know what a framework does for a tool, what it leaves to you, and when plain code is the better choice.
What you can trust
Every statement here was read on 2026-11-17 in the project's own documentation, with the link. No ranking, no prices.

The insurance example of this site has five tools and about a thousand lines of standard-library Python. It validates arguments with its own small JSON Schema validator, runs an execution adapter that it wrote itself, and speaks a teaching subset of the Model Context Protocol. That was deliberate: every mechanism is visible.

Now the team that owns the underwriting agent wants to ship it. Someone proposes Pydantic for the models. Someone else wants the official MCP SDK, so the cockpit team can reuse the tools. A third engineer works in the Java services that already hold the submissions and asks about Spring AI. Each proposal is reasonable. Together they raise a question that the names alone do not answer: which of these replaces which part of the example, and which part stays yours whatever you choose?

This page answers that question one framework at a time. It is a reference, so read the sections you need. Every section uses the same template, and every fact carries the date it was read, because these projects change monthly.

What this is not. This page does not compare quality or recommend a product. Measuring whether an agent built on any of these is good enough belongs to eval.sammuthu.com. Typed data contracts in depth, beyond tool arguments, belong to https://schema.sammuthu.com.

Four layers, kept apart#

A backend engineer already knows the layering from HTTP. HTTP and JSON are standards. A payment provider's REST API is a product built on them. A client library wraps that API in your language. A web framework such as Spring sits on top and decides how your code is organized. Each layer can change without the others, if you kept them apart.

Tools have the same four layers:

LayerWhat it fixesExamples on this page
StandardA format or protocol that anyone may implementJSON Schema, JSON-RPC 2.0, MCP, OpenTelemetry conventions
Provider APIHow one model vendor accepts tool definitions and returns tool callsAnthropic Messages, OpenAI Responses, Gemini
MCP SDKA library that implements MCP so you do not write the messagesPython, TypeScript and Java SDKs; FastMCP
LibraryHelpers that turn your types and functions into tools and run the loopPydantic, LangChain, Spring AI, LangChain4j

Diagram: Four layers around one tool · keep the contract in the standards, the adapter in your code

Read left to right, from the most stable layer to the most convenient. Your tool's contract lives in the first column; your execution adapter lives in your own code, wherever the last columns call it. Click a box for what that layer fixes and what it leaves to you.

  1. 1 · Standards
    1. JSON Schema: Describes which argument values are valid. Every provider API accepts it or a subset.
    2. MCP over JSON-RPC: A protocol, revision 2026-07-28, through which any host lists and calls a server's tools.
  2. 2 · Provider APIs
    1. Model vendor API: How one vendor accepts tool definitions and returns tool requests keyed by an id.
  3. 3 · MCP SDKs
    1. MCP SDK: A library that implements the protocol so a tool is written as a typed function.
  4. 4 · Libraries
    1. Tool library: Turns functions or typed models into tools and may run the loop; it must call your adapter.
  5. 5 · Your code
    1. Execution adapter: The part no framework replaces: validation as authority, scopes, the idempotency key, the result envelope.

The rule that keeps a design portable follows from the table. Write your tool's contract in the standard layer (a JSON Schema and a result envelope), keep the execution adapter in your own code, and let the provider API and the library be adapters at the edge. Then a change of vendor touches the edge, not the tool.

In our insurance agent. get_roof_assessment has one input schema, in examples/uw-tools/tools.py. The same schema is what the example's MCP-style server lists in tools/list, and what any provider API below would receive as input_schema or parameters. Only the wrapping around it differs.

The framework table#

The lab filters the table below by layer and by language. The table holds the same information for a reader without JavaScript.

NameKindWhat it does for a toolLanguageSection
JSON Schema 2020-12StandardDescribes valid arguments; validators reject the restanyread
JSON-RPC 2.0StandardRequest, response, notification and error messages under MCPanyread
Model Context ProtocolStandardLists and calls tools, reads resources, across applicationsanyread
OpenTelemetry GenAI conventionsStandard (in development)Names spans and attributes for tool executionanyread
Anthropic Messages API, tool useProvider APIAccepts tools; returns tool_use blocks; strict tool useanyread
OpenAI Responses API, function callingProvider APIAccepts function tools; returns function_call items; strict modeanyread
Gemini API, function callingProvider APIAccepts function declarations; returns function calls; modesanyread
MCP Python SDKMCP SDKBuilds an MCP server from typed functionspythonread
MCP TypeScript SDKMCP SDKBuilds an MCP server or client; schemas from zodtypescriptread
MCP Java SDKMCP SDKMCP servers and clients for the JVMjavaread
FastMCPMCP SDK (separate project)A higher-level Python framework for MCP serverspythonread
PydanticLibraryTyped models that validate input and generate JSON Schemapythonread
LangChain toolsLibraryTurns functions into tools; binds them to many modelspythonread
Spring AI tool callingLibraryAnnotated methods become tools in a Spring applicationjavaread
LangChain4j toolsLibraryAnnotated methods become tools for AI Servicesjavaread

Standards

A standard is a published document that any team may implement, with no product attached. The three below fix the shape of a tool's arguments, the envelope of its messages, and the protocol that moves tools between applications. A fourth names what a trace should record.

JSON Schema#

TemplateJSON Schema 2020-12
DefinitionA vocabulary for describing which JSON values are valid
Problem solvedThe model and your validator need one shared, machine-readable description of a tool's arguments
Data modelKeywords such as type, properties, required, enum, const, pattern, minimum, maximum, additionalProperties, items
StrengthsLanguage-neutral; every provider API on this page accepts it or a subset of it
Limitationspattern matches anywhere unless anchored with ^ and $; format is an annotation only by default and does not validate; providers support different subsets
SecurityA schema that allows extra properties lets a model smuggle fields; set additionalProperties: false
When plain code is betterRules across fields, such as "the roof age cannot exceed the building age", belong in code after validation
VerifiedRelease 2020-12 is current; read 2026-11-17 at json-schema.org/specification and its reference pages

The input schema of get_roof_assessment, from examples/uw-tools/tools.py, shown in the standard form. The example validates it with its own subset validator in schema.py; this block was checked as JSON by the build.

{
  "type": "object",
  "properties": {
    "submission_id": {"type": "string", "pattern": "^SUB-[0-9]{4}$",
                      "description": "The id of the submission, for example SUB-1004."}
  },
  "required": ["submission_id"],
  "additionalProperties": false
}

JSON-RPC 2.0#

TemplateJSON-RPC 2.0
DefinitionA small protocol for calling a method on another program with JSON messages
Problem solvedTwo programs need to match each answer to its request and tell errors apart from results
Data modelA request has jsonrpc: "2.0", method, optional params, and an id; a response has the same id and either result or error; a request without id is a notification and gets no reply
StrengthsTransport-neutral and tiny. MCP is built on it
LimitationsNo schema for methods, no authentication, no ordering guarantees; those are left to the protocol on top
SecurityThe predefined error codes (-32700, -32600, -32601, -32602, -32603) say what failed without exposing internals; keep your messages that way
When plain code is betterInside one process, a function call needs no protocol
VerifiedSpecification last updated 2013-01-04; read 2026-11-17 at jsonrpc.org/specification

The page MCP architecture shows real JSON-RPC messages captured from the example.

Model Context Protocol#

TemplateModel Context Protocol (MCP), revision 2026-07-28
DefinitionAn open protocol through which an application (the host) connects to servers that offer tools, resources and prompts
Problem solvedTools written for one application can be reused by any application that speaks the protocol
Data modelJSON-RPC 2.0 methods such as server/discover, tools/list, tools/call, resources/read; each request carries its protocol version and client capabilities in _meta; every result carries resultType
StrengthsOne server, many hosts; two standard transports (stdio and Streamable HTTP); an authorization specification for remote servers
LimitationsIt moves tool definitions and calls; it does not decide which tool runs, validate your business rules, or make a write safe
SecurityA server's tools run with the server's privileges; remote servers need authorization, and the specification forbids passing a client's token through to other services
When plain code is betterOne application, one team, tools that nobody else will reuse
VerifiedCurrent revision 2026-07-28, read 2026-11-17 at modelcontextprotocol.io/specification
Production pitfall. Revision 2026-07-28 removed the initialize handshake that the earlier revision 2025-11-25 used, and made the protocol stateless. Many tutorials still show the handshake. Check which revision your SDK implements before you read a tutorial. The details are on MCP architecture and MCP on the wire.

OpenTelemetry conventions for tool execution#

TemplateOpenTelemetry semantic conventions for generative AI
DefinitionAgreed names for spans, attributes and metrics, so that traces from different tools and vendors read the same way
Problem solvedWithout shared names, every team invents its own attribute for "which tool ran"
Data modelA tool execution span named execute_tool {gen_ai.tool.name}, with gen_ai.operation.name set to execute_tool, gen_ai.tool.name, and gen_ai.tool.call.id when the model supplied one
StrengthsVendor-neutral; covers MCP client and server spans as well
LimitationsStatus is development; the conventions moved to a separate repository and have no tagged release yet; the MCP part still describes sessions that MCP 2026-07-28 removed
SecurityRecord outcomes and identifiers, not argument values that may hold personal data
When plain code is betterFor a teaching example, as here, own attribute names are fine if you map them before export
VerifiedRead 2026-11-17 at semantic-conventions-genai

Provider APIs

A provider API is the interface a model vendor offers for sending a request to its models. All three below follow the same loop that Tool calling explains: you send tool definitions, the model answers with structured tool requests, your code runs them and sends results back keyed by an id. The names of the fields differ, and the differences matter when you write the adapter at the edge.

FieldAnthropic MessagesOpenAI ResponsesGemini (Interactions)
Tool arguments schemainput_schemaparametersparameters
The model's requesttool_use block: id, name, inputfunction_call item: call_id, name, arguments (a JSON string)function_call step: id, name, arguments
Your replytool_result block: tool_use_id, content, is_errorfunction_call_output item: call_id, outputfunction_result step: call_id, name, result
Constrain to the schemastrict: true on the toolstrict: true on the functionmode validated

All values as documented on 2026-11-17.

Anthropic Messages API, tool use#

TemplateClaude tool use
DefinitionTools passed in the tools parameter of a Messages request; Claude answers with tool_use blocks and stop_reason: "tool_use"
Problem solvedLets a Claude model request work from your code in a structured, id-matched form
Data modelTool: name (pattern ^[a-zA-Z0-9_-]{1,128}$), description, input_schema, optional input_examples, strict, defer_loading. Results go back in a user message as tool_result blocks, first in that message
StrengthsStrict tool use constrains sampling to the schema; tool search loads deferred tools on demand; client tools run in your code and server tools run on the vendor's side
LimitationsStrict schemas accept a subset: the structured-outputs page lists minimum, maximum, minLength and maxLength as not supported. Forcing a tool with tool_choice any or tool returns an error on some current models, including Claude Opus 5.5
SecurityThe documentation advises keeping untrusted content inside tool_result blocks, never in the system prompt; validate input in your code even with strict mode
When plain code is betterA fixed sequence of calls that never needs the model's choice
VerifiedRead 2026-11-17 at platform.claude.com tool use overview (the old docs address now redirects there)

The definition of get_roof_assessment in this API's shape. Documented shape; not run here (the example calls no model).

{
  "name": "get_roof_assessment",
  "description": "Ask the roof-data provider for the assessed roof age of one submission. Reads only.",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {"submission_id": {"type": "string", "pattern": "^SUB-[0-9]{4}$"}},
    "required": ["submission_id"],
    "additionalProperties": false
  }
}

OpenAI Responses API, function calling#

TemplateOpenAI function calling
DefinitionFunction tools passed to a Responses request; the model returns function_call output items
Problem solvedLets an OpenAI model request work from your code
Data modelTool: type: "function", name, description, parameters, strict. Call: call_id, name, arguments as a JSON-encoded string that you parse. Reply: function_call_output with call_id and output
Strengthstool_choice can force, forbid, or restrict to an allowed_tools subset; parallel_tool_calls: false limits a turn to one call; namespaces and deferred loading for large catalogs
LimitationsStrict mode needs additionalProperties: false on every object and every property in required; optional fields become a type that allows null. When strict is omitted, the Responses API tries to make the schema strict and falls back if it cannot
Securityarguments is a string written by the model: parse it, then validate it; never eval it
When plain code is betterAs above: a fixed sequence
VerifiedRead 2026-11-17 at developers.openai.com function calling (moved from the earlier platform address)

Gemini API, function calling#

TemplateGemini function calling
DefinitionFunction declarations passed to a Gemini request; the model returns function calls
Problem solvedLets a Gemini model request work from your code
Data modelThe default page uses the Interactions API: a tool with type: "function", name, description, parameters; a function_call step with id; your function_result with call_id. The older generateContent shape uses functionCall and functionResponse parts, documented on a separate page
StrengthsModes auto, any, none, validated; parallel and compositional calling; the Python SDK can build declarations from type hints and run calls automatically
LimitationsA subset of the OpenAPI schema; very large or nested schemas can be rejected; automatic calling hides the loop, and with it your adapter, unless you disable it
SecurityThe documentation tells you to validate calls before executing them
When plain code is betterWhen automatic function calling would run a write tool without your adapter in between
VerifiedRead 2026-11-17 at aistudio.google.com function calling (moved from the earlier ai.google.dev address)
Production pitfall. Every provider SDK that offers to "run the tools for you" removes the point where your execution adapter sits. For read tools that may be acceptable. For record_recommendation, which needs scope uw.recommend and an idempotency key, keep the loop in your code or plug the adapter into the library's hook.

MCP SDKs

An MCP SDK is a library that implements the protocol, so you write tools as functions and the SDK writes the JSON-RPC messages. The official SDKs are listed on the MCP site in tiers: TypeScript, Python, C#, Go, Rust and Ruby in tier 1, Java in tier 2, and Swift, PHP and Kotlin in tier 3, as documented on 2026-11-17. Each SDK adopts a new protocol revision on its own schedule.

MCP Python SDK#

Templatemcp (Python), version 2.3.0
DefinitionThe official Python SDK for MCP servers and clients
Problem solvedBuilds an MCP server from typed Python functions, with schemas generated from type hints
Data modelClass MCPServer with decorators @mcp.tool(), @mcp.resource(...), @mcp.prompt(); a Client that connects over stdio or Streamable HTTP
StrengthsImplements revision 2026-07-28 and still serves clients of the 2025 revisions from the same app
LimitationsVersion 2 renamed FastMCP to MCPServer; the documentation says the old name is gone. Code written for version 1 does not import
SecurityThe schema comes from your signature; business rules and authorization still go in your function or adapter
When plain code is betterFor an in-process tool that no other application uses
VerifiedRelease v2.3.0 (2026-10-02); read 2026-11-17 at github.com/modelcontextprotocol/python-sdk

Documented shape; not run here (the SDK is not installed in this repository; the example's own server is examples/uw-tools/mcp_server.py).

from mcp.server import MCPServer

mcp = MCPServer("uw-tools")

@mcp.tool()
def get_roof_assessment(submission_id: str) -> dict:
    """Ask the roof-data provider for the assessed roof age of one submission. Reads only."""
    ...

MCP TypeScript SDK#

TemplateTypeScript SDK, version 2
DefinitionThe official TypeScript SDK, split in version 2 into @modelcontextprotocol/server and @modelcontextprotocol/client
Problem solvedMCP servers and clients in Node.js and similar runtimes
Data modelnew McpServer({ name, version }), server.registerTool(name, { description, inputSchema }, handler) with zod schemas, StdioServerTransport
StrengthsImplements revision 2026-07-28; optional middleware packages for common web frameworks
LimitationsVersion 1 (@modelcontextprotocol/sdk) lives on a separate branch; examples written for it use other package names
SecurityThe documentation lists host-header validation helpers in its middleware packages
When plain code is betterAs for Python
VerifiedRelease v2.4.0 (2026-10-23); read 2026-11-17 at github.com/modelcontextprotocol/typescript-sdk

Documented shape; not run here and not type-checked.

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const server = new McpServer({ name: "uw-tools", version: "0.1.0" });
server.registerTool(
  "get_roof_assessment",
  { description: "Assessed roof age of one submission. Reads only.",
    inputSchema: z.object({ submission_id: z.string().regex(/^SUB-[0-9]{4}$/) }) },
  async ({ submission_id }) => ({ content: [{ type: "text", text: "..." }] })
);
await server.connect(new StdioServerTransport());

The McpServer import path and server.connect are as the README example reads; z.string().regex is zod's own method and was not verified on the SDK page.

MCP Java SDK#

Templateio.modelcontextprotocol.sdk:mcp, version 2.2.0
DefinitionThe official Java SDK for MCP servers and clients, maintained in collaboration with Spring AI
Problem solvedMCP on the JVM, next to the services that already hold the data
Data modelStdio and Streamable HTTP transports (client on the JDK HttpClient, server on the Servlet API)
StrengthsSupports both the stateless 2026-07-28 revision and the earlier revisions; reports conformance-suite results in its README
LimitationsSpring WebFlux and WebMVC transports are not in this SDK; Spring AI provides them. The documentation read here shows class names only for the earlier revision's server
SecurityJava 17 or later; the same server privileges rule applies
When plain code is betterA Java service with one internal caller can expose a REST endpoint and let the agent's host wrap it
VerifiedRelease v2.2.0 (2026-11-16); read 2026-11-17 at github.com/modelcontextprotocol/java-sdk

No code is shown, because the documentation read here did not show the server class names for revision 2026-07-28.

FastMCP#

TemplateFastMCP, version 4.2.1
DefinitionA separate open-source Python framework for MCP servers and clients, not part of the official SDK
Problem solvedA higher-level way to write MCP servers in Python
Data modelfrom fastmcp import FastMCP, decorator @mcp.tool
StrengthsIts project site says version 4 is generally available
LimitationsIts high-level API was taken into the official SDK in 2024, and the official SDK has since renamed that class MCPServer. The name FastMCP now refers to this separate project only. Check which one a tutorial means
SecuritySame as any MCP server
When plain code is betterAs for the official SDK
VerifiedPyPI fastmcp 4.2.1; read 2026-11-17 at gofastmcp.com

Libraries

A library here is code that sits between your functions and the provider API or MCP. It turns a function or a typed model into a tool definition, and often runs the loop. That convenience is also the risk: where the library runs your tool is where your execution adapter must be.

Pydantic#

TemplatePydantic, version 2.14.3
DefinitionA Python library that validates data against models declared with type hints
Problem solvedOne typed class produces both the JSON Schema the model sees and the validation your handler needs, so they cannot drift
Data modelBaseModel classes; Field(...) with description, pattern, min_length, ge, le and other constraints; model_json_schema() returns a JSON Schema 2020-12 dictionary; validate_call validates a function's arguments
StrengthsGenerated schemas follow JSON Schema 2020-12; the same model validates at run time
LimitationsValidation and serialization schemas can differ; validate_call coerces by default, so "1004" may become 1004 unless strict mode is on
SecurityTurn on strict mode where a coerced value would change meaning
When plain code is betterA tool with one string argument; the example's 250-line validator module teaches the mechanism, Pydantic is the production choice for many fields
VerifiedRead 2026-11-17 at pydantic.dev JSON Schema and the Field API reference (moved from docs.pydantic.dev)

Documented shape; not run here. The page Types compares it with the example's own schema generation.

from pydantic import BaseModel, Field

class RoofAssessmentArgs(BaseModel):
    submission_id: str = Field(pattern=r"^SUB-[0-9]{4}$", description="The id of the submission, for example SUB-1004.")

schema = RoofAssessmentArgs.model_json_schema()

LangChain tools#

TemplateLangChain, version 1.5.0
DefinitionA Python framework for model applications; its @tool decorator turns a function into a tool
Problem solvedOne tool definition, bound to many model providers through one interface
Data model@tool from langchain.tools: name from the function, description from the docstring, schema from type hints or args_schema. model.bind_tools([...]); calls arrive as tool_calls entries with name, args, id; results go back as a ToolMessage with tool_call_id
StrengthsProvider-neutral binding; a ToolRuntime parameter gives a tool state and context without showing it to the model
LimitationsAnother layer between you and the provider's fields; the pages read do not describe every error-handling option
SecurityErrors can be caught with @wrap_tool_call middleware; put authorization there or in the function, never only in the description
When plain code is betterOne provider and a short loop: the example's loop.py is about 110 lines
VerifiedRead 2026-11-17 at docs.langchain.com tools (moved from python.langchain.com)

Spring AI tool calling#

TemplateSpring AI, version 2.0.2
DefinitionSpring's framework for model applications; methods annotated @Tool become tools
Problem solvedJava teams expose existing Spring beans as tools without writing schemas by hand
Data model@Tool(name, description, returnDirect), @ToolParam(description, required); a ToolCallback with getToolDefinition() and call(...); schemas from a JsonSchemaGenerator; ToolContext passes data such as a tenant id to a tool without sending it to the model
StrengthsFits Spring's dependency injection; ToolCallingManager can cap calls per tool and in total
LimitationsAll parameters are required by default; the attribute that earlier versions used to take over execution does not appear on the current page, which documents a per-request advisor setting instead
SecurityToolContext keeps tenant and identity out of the model's view; a ToolExecutionExceptionProcessor decides what an exception tells the model
When plain code is betterA Spring controller with bean validation already does the adapter's first two steps; a thin tool over it may be enough
VerifiedRead 2026-11-17 at docs.spring.io Spring AI tools

Documented shape; not compiled here. The page Types shows a Java record that was compiled and run with the local JDK.

class RoofTools {
    @Tool(description = "Assessed roof age of one submission. Reads only.")
    RoofAssessment getRoofAssessment(@ToolParam(description = "The id, for example SUB-1004") String submissionId) {
        return roofService.assess(submissionId);
    }
}

LangChain4j tools#

TemplateLangChain4j
DefinitionA Java library for model applications; @Tool methods become tools for its AI Services
Problem solvedTyped Java tools with low-level control when you need it
Data modelHigh level: @Tool, @P for parameters, attached with AiServices.builder(...).tools(...). Low level: ToolSpecification, ToolExecutionRequest with id, name, arguments as a JSON string
StrengthsThe page states plainly that the model does not run tools, your code does; concurrency for parallel calls is opt-in; MCP tools via McpToolProvider
LimitationsThe default error handler sends the exception message to the model, which the documentation itself warns may leak sensitive data
SecurityReplace the default error handler; set the strategy for a tool name the model invented (it throws by default)
When plain code is betterAs for Spring AI
VerifiedRead 2026-11-17 at docs.langchain4j.dev tools; the page shows no version number
In a coding agent. The same layering holds. A coding agent's run_tests tool may be an MCP server written with an SDK, called through a provider API, inside a harness that runs the loop. The harness is the layer that decides whether git_push needs a person's approval; see harness.sammuthu.com and, for the review and CI side, diff-to-deploy.sammuthu.com.
Where your execution adapter lives in each frameworkThe one question to ask before adopting any library that runs tools

Every framework on this page has a point where a model's request becomes a call to your function. Find it before you adopt the framework, because that is where validation, authorization, the idempotency key and the result envelope must happen.

In a provider API with your own loop, the point is your loop: you receive tool_use or function_call, and you call the adapter. Nothing is hidden.

In an MCP server built with an SDK, the point is the tool function the SDK calls. The SDK validates against the schema it generated; authorization by caller is yours. For a remote server the caller's identity comes from the authorization layer of the transport, and the function must read it, not trust an argument.

In a library that runs the loop (LangChain agents, Spring AI's default execution, LangChain4j AI Services, Gemini's automatic function calling), the point is inside the library. Each one offers a hook: middleware that wraps a tool call, a callback interface, an error processor, a tool provider. Put the adapter there. If a library offers no hook for a write tool, do not register the write tool with it; call that tool from your own code after the model's recommendation.

A test makes this concrete: register record_recommendation, call it twice with the same idempotency key through the framework, and count rows. Case UW-T04 in the example expects one row. If the framework's retry runs underneath your adapter, you will see two.

Portability: what survives a change of vendorSchema subsets, id fields, and the cost of strict modes

The JSON Schema you write is portable only to the intersection of what the providers accept. Anthropic's strict tool use, as documented on 2026-11-17, does not support minimum, maximum, minLength or maxLength. OpenAI's strict mode requires every property to be listed in required. Gemini accepts a subset of the OpenAPI schema. A schema that uses pattern and minimum together therefore needs a decision: keep the constraint in the schema for the model's guidance and validate it in code anyway, or drop it from the schema sent to a strict provider and keep it only in code.

The design that survives a change is the one this site uses throughout: the schema is guidance and a first filter; the validator in your adapter is the authority. Then a provider that ignores a keyword costs some failed calls, never a wrong execution.

Ids differ too. Anthropic's tool_use has an id and your reply uses tool_use_id. OpenAI's call has both an item id and a call_id, and the reply uses call_id. Gemini's function call carries an id that the generateContent page says is now always returned for its version 3 models. LangChain4j notes that some providers omit the id. Your loop should key results by the provider's call id and fall back to position only where a provider gives none.

Strict modes add a cost that is easy to miss: a schema compiled for constrained generation is cached by the provider, and a large or deeply nested schema can be rejected. Keep tool schemas flat and small. That is good practice for the model's understanding as well.

SDK revisions and the stateless MCPDual-era support, renamed classes, and what to pin

MCP revision 2026-07-28 is a breaking change at the protocol level: no initialize, no protocol sessions, version and capabilities on every request, and a mandatory server/discover. The documentation names three kinds of implementation: modern, legacy, and dual-era, which serves both. A legacy-only client cannot talk to a modern-only server.

The SDKs read on 2026-11-17 handle this differently. The Python SDK version 2 implements the new revision and serves older clients from the same app. The Java SDK supports both and says the legacy API is not deprecated in the SDK. The TypeScript SDK version 2 implements the new revision, with version 1 kept on its own branch.

What to pin, in order: the protocol revision your servers advertise, the SDK major version, and the host applications you support. Test one modern and one legacy client against each server before a release. The OpenTelemetry MCP conventions still describe the older, session-based revision, so trace attributes such as a session id will be empty on a modern server.

Checklist before adopting a framework#

QuestionWhy it matters
Which layer is it: standard, provider API, MCP SDK or library?Standards outlive products; keep your contract in the standard layer
Where does it call your function, and can your adapter run there?Validation, authorization and idempotency must not be skipped
Which JSON Schema subset does it accept, and does it coerce values?A silently coerced or dropped constraint changes what reaches your code
What does an exception tell the model?Default error handlers can leak internals
Which protocol revision and SDK major version does it implement?MCP 2026-07-28 broke the handshake that older code expects
What did you read, and when?Every fact on this page is dated 2026-11-17; read again before you build

In one breath#

Keep the four layers apart: standards for the contract, provider APIs and MCP SDKs at the edge, libraries for convenience. Write the schema once in JSON Schema, and keep validation, authorization, idempotency and the result envelope in your own adapter, wherever the framework calls your function. Before you adopt anything, find that point, check the schema subset and the error handling, and pin the protocol revision.

You can now place any named framework in the picture and say what it does for a tool and what it leaves to you. The last concepts are the less tidy tools: tools that call tools, results too large for one answer, and the traces that show what really happened. That is Advanced.