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:
| Layer | What it fixes | Examples on this page |
|---|---|---|
| Standard | A format or protocol that anyone may implement | JSON Schema, JSON-RPC 2.0, MCP, OpenTelemetry conventions |
| Provider API | How one model vendor accepts tool definitions and returns tool calls | Anthropic Messages, OpenAI Responses, Gemini |
| MCP SDK | A library that implements MCP so you do not write the messages | Python, TypeScript and Java SDKs; FastMCP |
| Library | Helpers that turn your types and functions into tools and run the loop | Pydantic, 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 · Standards
- JSON Schema: Describes which argument values are valid. Every provider API accepts it or a subset.
- MCP over JSON-RPC: A protocol, revision 2026-07-28, through which any host lists and calls a server's tools.
- 2 · Provider APIs
- Model vendor API: How one vendor accepts tool definitions and returns tool requests keyed by an id.
- 3 · MCP SDKs
- MCP SDK: A library that implements the protocol so a tool is written as a typed function.
- 4 · Libraries
- Tool library: Turns functions or typed models into tools and may run the loop; it must call your adapter.
- 5 · Your code
- 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_assessmenthas one input schema, inexamples/uw-tools/tools.py. The same schema is what the example's MCP-style server lists intools/list, and what any provider API below would receive asinput_schemaorparameters. 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.
| Name | Kind | What it does for a tool | Language | Section |
|---|---|---|---|---|
| JSON Schema 2020-12 | Standard | Describes valid arguments; validators reject the rest | any | read |
| JSON-RPC 2.0 | Standard | Request, response, notification and error messages under MCP | any | read |
| Model Context Protocol | Standard | Lists and calls tools, reads resources, across applications | any | read |
| OpenTelemetry GenAI conventions | Standard (in development) | Names spans and attributes for tool execution | any | read |
| Anthropic Messages API, tool use | Provider API | Accepts tools; returns tool_use blocks; strict tool use | any | read |
| OpenAI Responses API, function calling | Provider API | Accepts function tools; returns function_call items; strict mode | any | read |
| Gemini API, function calling | Provider API | Accepts function declarations; returns function calls; modes | any | read |
| MCP Python SDK | MCP SDK | Builds an MCP server from typed functions | python | read |
| MCP TypeScript SDK | MCP SDK | Builds an MCP server or client; schemas from zod | typescript | read |
| MCP Java SDK | MCP SDK | MCP servers and clients for the JVM | java | read |
| FastMCP | MCP SDK (separate project) | A higher-level Python framework for MCP servers | python | read |
| Pydantic | Library | Typed models that validate input and generate JSON Schema | python | read |
| LangChain tools | Library | Turns functions into tools; binds them to many models | python | read |
| Spring AI tool calling | Library | Annotated methods become tools in a Spring application | java | read |
| LangChain4j tools | Library | Annotated methods become tools for AI Services | java | read |
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#
| Template | JSON Schema 2020-12 |
|---|---|
| Definition | A vocabulary for describing which JSON values are valid |
| Problem solved | The model and your validator need one shared, machine-readable description of a tool's arguments |
| Data model | Keywords such as type, properties, required, enum, const, pattern, minimum, maximum, additionalProperties, items |
| Strengths | Language-neutral; every provider API on this page accepts it or a subset of it |
| Limitations | pattern matches anywhere unless anchored with ^ and $; format is an annotation only by default and does not validate; providers support different subsets |
| Security | A schema that allows extra properties lets a model smuggle fields; set additionalProperties: false |
| When plain code is better | Rules across fields, such as "the roof age cannot exceed the building age", belong in code after validation |
| Verified | Release 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#
| Template | JSON-RPC 2.0 |
|---|---|
| Definition | A small protocol for calling a method on another program with JSON messages |
| Problem solved | Two programs need to match each answer to its request and tell errors apart from results |
| Data model | A 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 |
| Strengths | Transport-neutral and tiny. MCP is built on it |
| Limitations | No schema for methods, no authentication, no ordering guarantees; those are left to the protocol on top |
| Security | The predefined error codes (-32700, -32600, -32601, -32602, -32603) say what failed without exposing internals; keep your messages that way |
| When plain code is better | Inside one process, a function call needs no protocol |
| Verified | Specification 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#
| Template | Model Context Protocol (MCP), revision 2026-07-28 |
|---|---|
| Definition | An open protocol through which an application (the host) connects to servers that offer tools, resources and prompts |
| Problem solved | Tools written for one application can be reused by any application that speaks the protocol |
| Data model | JSON-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 |
| Strengths | One server, many hosts; two standard transports (stdio and Streamable HTTP); an authorization specification for remote servers |
| Limitations | It moves tool definitions and calls; it does not decide which tool runs, validate your business rules, or make a write safe |
| Security | A 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 better | One application, one team, tools that nobody else will reuse |
| Verified | Current revision 2026-07-28, read 2026-11-17 at modelcontextprotocol.io/specification |
Production pitfall. Revision2026-07-28removed theinitializehandshake that the earlier revision2025-11-25used, 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#
| Template | OpenTelemetry semantic conventions for generative AI |
|---|---|
| Definition | Agreed names for spans, attributes and metrics, so that traces from different tools and vendors read the same way |
| Problem solved | Without shared names, every team invents its own attribute for "which tool ran" |
| Data model | A 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 |
| Strengths | Vendor-neutral; covers MCP client and server spans as well |
| Limitations | Status 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 |
| Security | Record outcomes and identifiers, not argument values that may hold personal data |
| When plain code is better | For a teaching example, as here, own attribute names are fine if you map them before export |
| Verified | Read 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.
| Field | Anthropic Messages | OpenAI Responses | Gemini (Interactions) |
|---|---|---|---|
| Tool arguments schema | input_schema | parameters | parameters |
| The model's request | tool_use block: id, name, input | function_call item: call_id, name, arguments (a JSON string) | function_call step: id, name, arguments |
| Your reply | tool_result block: tool_use_id, content, is_error | function_call_output item: call_id, output | function_result step: call_id, name, result |
| Constrain to the schema | strict: true on the tool | strict: true on the function | mode validated |
All values as documented on 2026-11-17.
Anthropic Messages API, tool use#
| Template | Claude tool use |
|---|---|
| Definition | Tools passed in the tools parameter of a Messages request; Claude answers with tool_use blocks and stop_reason: "tool_use" |
| Problem solved | Lets a Claude model request work from your code in a structured, id-matched form |
| Data model | Tool: 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 |
| Strengths | Strict 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 |
| Limitations | Strict 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 |
| Security | The 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 better | A fixed sequence of calls that never needs the model's choice |
| Verified | Read 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#
| Template | OpenAI function calling |
|---|---|
| Definition | Function tools passed to a Responses request; the model returns function_call output items |
| Problem solved | Lets an OpenAI model request work from your code |
| Data model | Tool: 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 |
| Strengths | tool_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 |
| Limitations | Strict 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 |
| Security | arguments is a string written by the model: parse it, then validate it; never eval it |
| When plain code is better | As above: a fixed sequence |
| Verified | Read 2026-11-17 at developers.openai.com function calling (moved from the earlier platform address) |
Gemini API, function calling#
| Template | Gemini function calling |
|---|---|
| Definition | Function declarations passed to a Gemini request; the model returns function calls |
| Problem solved | Lets a Gemini model request work from your code |
| Data model | The 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 |
| Strengths | Modes auto, any, none, validated; parallel and compositional calling; the Python SDK can build declarations from type hints and run calls automatically |
| Limitations | A 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 |
| Security | The documentation tells you to validate calls before executing them |
| When plain code is better | When automatic function calling would run a write tool without your adapter in between |
| Verified | Read 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. Forrecord_recommendation, which needs scopeuw.recommendand 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#
| Template | mcp (Python), version 2.3.0 |
|---|---|
| Definition | The official Python SDK for MCP servers and clients |
| Problem solved | Builds an MCP server from typed Python functions, with schemas generated from type hints |
| Data model | Class MCPServer with decorators @mcp.tool(), @mcp.resource(...), @mcp.prompt(); a Client that connects over stdio or Streamable HTTP |
| Strengths | Implements revision 2026-07-28 and still serves clients of the 2025 revisions from the same app |
| Limitations | Version 2 renamed FastMCP to MCPServer; the documentation says the old name is gone. Code written for version 1 does not import |
| Security | The schema comes from your signature; business rules and authorization still go in your function or adapter |
| When plain code is better | For an in-process tool that no other application uses |
| Verified | Release 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#
| Template | TypeScript SDK, version 2 |
|---|---|
| Definition | The official TypeScript SDK, split in version 2 into @modelcontextprotocol/server and @modelcontextprotocol/client |
| Problem solved | MCP servers and clients in Node.js and similar runtimes |
| Data model | new McpServer({ name, version }), server.registerTool(name, { description, inputSchema }, handler) with zod schemas, StdioServerTransport |
| Strengths | Implements revision 2026-07-28; optional middleware packages for common web frameworks |
| Limitations | Version 1 (@modelcontextprotocol/sdk) lives on a separate branch; examples written for it use other package names |
| Security | The documentation lists host-header validation helpers in its middleware packages |
| When plain code is better | As for Python |
| Verified | Release 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#
| Template | io.modelcontextprotocol.sdk:mcp, version 2.2.0 |
|---|---|
| Definition | The official Java SDK for MCP servers and clients, maintained in collaboration with Spring AI |
| Problem solved | MCP on the JVM, next to the services that already hold the data |
| Data model | Stdio and Streamable HTTP transports (client on the JDK HttpClient, server on the Servlet API) |
| Strengths | Supports both the stateless 2026-07-28 revision and the earlier revisions; reports conformance-suite results in its README |
| Limitations | Spring 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 |
| Security | Java 17 or later; the same server privileges rule applies |
| When plain code is better | A Java service with one internal caller can expose a REST endpoint and let the agent's host wrap it |
| Verified | Release 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#
| Template | FastMCP, version 4.2.1 |
|---|---|
| Definition | A separate open-source Python framework for MCP servers and clients, not part of the official SDK |
| Problem solved | A higher-level way to write MCP servers in Python |
| Data model | from fastmcp import FastMCP, decorator @mcp.tool |
| Strengths | Its project site says version 4 is generally available |
| Limitations | Its 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 |
| Security | Same as any MCP server |
| When plain code is better | As for the official SDK |
| Verified | PyPI 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#
| Template | Pydantic, version 2.14.3 |
|---|---|
| Definition | A Python library that validates data against models declared with type hints |
| Problem solved | One typed class produces both the JSON Schema the model sees and the validation your handler needs, so they cannot drift |
| Data model | BaseModel 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 |
| Strengths | Generated schemas follow JSON Schema 2020-12; the same model validates at run time |
| Limitations | Validation and serialization schemas can differ; validate_call coerces by default, so "1004" may become 1004 unless strict mode is on |
| Security | Turn on strict mode where a coerced value would change meaning |
| When plain code is better | A tool with one string argument; the example's 250-line validator module teaches the mechanism, Pydantic is the production choice for many fields |
| Verified | Read 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#
| Template | LangChain, version 1.5.0 |
|---|---|
| Definition | A Python framework for model applications; its @tool decorator turns a function into a tool |
| Problem solved | One 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 |
| Strengths | Provider-neutral binding; a ToolRuntime parameter gives a tool state and context without showing it to the model |
| Limitations | Another layer between you and the provider's fields; the pages read do not describe every error-handling option |
| Security | Errors can be caught with @wrap_tool_call middleware; put authorization there or in the function, never only in the description |
| When plain code is better | One provider and a short loop: the example's loop.py is about 110 lines |
| Verified | Read 2026-11-17 at docs.langchain.com tools (moved from python.langchain.com) |
Spring AI tool calling#
| Template | Spring AI, version 2.0.2 |
|---|---|
| Definition | Spring's framework for model applications; methods annotated @Tool become tools |
| Problem solved | Java 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 |
| Strengths | Fits Spring's dependency injection; ToolCallingManager can cap calls per tool and in total |
| Limitations | All 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 |
| Security | ToolContext keeps tenant and identity out of the model's view; a ToolExecutionExceptionProcessor decides what an exception tells the model |
| When plain code is better | A Spring controller with bean validation already does the adapter's first two steps; a thin tool over it may be enough |
| Verified | Read 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#
| Template | LangChain4j |
|---|---|
| Definition | A Java library for model applications; @Tool methods become tools for its AI Services |
| Problem solved | Typed Java tools with low-level control when you need it |
| Data model | High level: @Tool, @P for parameters, attached with AiServices.builder(...).tools(...). Low level: ToolSpecification, ToolExecutionRequest with id, name, arguments as a JSON string |
| Strengths | The page states plainly that the model does not run tools, your code does; concurrency for parallel calls is opt-in; MCP tools via McpToolProvider |
| Limitations | The default error handler sends the exception message to the model, which the documentation itself warns may leak sensitive data |
| Security | Replace the default error handler; set the strategy for a tool name the model invented (it throws by default) |
| When plain code is better | As for Spring AI |
| Verified | Read 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'srun_teststool 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 whethergit_pushneeds 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#
| Question | Why 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.