This is a knowledge site about the tools of agentic software: the capabilities outside a model that an agent may ask for. It starts from one plain function and climbs to a tool definition, a typed handler, a result contract, an MCP server, and a tool that is safe, reliable and tested in production. At every step it asks one question: who is allowed to do what, and what happens when it fails? It is written for engineers and architects who build agent systems, and for backend engineers who know services well and meet tool calling for the first time.
One example runs through every page. An insurer receives a broker's request for a quote. An underwriting agent gathers evidence with five tools: four that read and one that writes a recommendation. A human underwriter decides. The model recommends; a person decides.
What it is and is not#
| It is | It is not |
|---|---|
| A ladder: one idea per step, each word in plain English with a tiny example before it is used | A standard, or the only way to build tools |
One running example with the series cases UW-001 to UW-010 and this site's own cases UW-T01 to UW-T08 | A record of any real insurer. The cases, the rules, the fields and the provider are invented |
| A demonstration of mechanism: how a definition, a validator, an adapter, a result envelope and a trace fit together | A measurement of any model or product. No page reports how good a real system is |
| Code that was run: a small tool layer in standard-library Python and one Java file, with their real output | A framework to install. It is short so that it can be read whole, and it leaves things out |
| Products and protocols described from their own documentation, read on 2026-11-17, by what each does for a tool | A ranking or a buying guide. No product is called best, and no price is quoted |
What is original here and what is not#
| Part | Status |
|---|---|
| Tool, tool call, tool result, tool definition, input schema | Common vocabulary of the provider documentation read for this site. This site separates the model's request (a proposal) from execution (what the application does) more strictly than most sources |
| JSON Schema, JSON-RPC 2.0, the Model Context Protocol, OAuth | Published standards, described from their specifications. The MCP pages follow revision 2026-07-28 |
| The advice on tool names, descriptions, namespaces, token-efficient results and tool search | From the provider documentation and Anthropic's articles on writing tools for agents and on advanced tool use, used with attribution. Their prose, examples and figures are not used |
The result envelope (ok, data or error, meta) and its error codes | A design proposed on this site. MCP and the provider APIs have their own result shapes; the pages show both |
| The execution adapter as one ordered path (validate, authorize, idempotency, timeout and retry, breaker, execute, shape the result) | A design proposed on this site, assembled from common practice in service engineering |
| Idempotency keys, retries with backoff and jitter, circuit breakers | Established practice in distributed systems, applied here to tools |
| The five tools, the policy fixture, the eighteen cases, the callers and scopes | Written for this site. All synthetic |
| The example code, its 62 tests, the Java file | Written for this site |
| The interactive labs and the diagrams | Written for this site. The labs' logic is a second implementation of the Python code, and a test fails if the two differ |
Where a page takes an idea from a source, the page says so. Where this site proposes something, it calls it a design.
How the facts were checked#
| Kind of claim | How it was checked |
|---|---|
| A named product, protocol or library | Read in its own documentation on 2026-11-17 and logged with the address and the date in the page's fact log (docs/facts/ in the repository). Where the documentation is silent, the page says so. Surprising items, such as a protocol change or a moved page, were fetched a second time before they were published |
| The example | Run. Every command shown from examples/uw-tools/ was executed in a copy of the folder, and the output on the page is the output it printed. 18 cases match their expected blocks; 62 unit tests pass |
| The Java file | Compiled and run with JDK 23.0.1 as java TypedTool.java. Its output is in the example's README |
| The labs | They read data generated from the example. A parity test runs 186 checks that the JavaScript gives the same results as the Python |
| Other code | A block that was not run says so, for example "documented shape; not run here" |
| Links and structure | A build step checks every internal link, every diagram, every glossary reference and every JSON block before the site is published |
Documentation changes, and in this field it changes monthly. During the writing of this site, the Model Context Protocol published a revision that removed its connection handshake, and several documentation sites moved to new addresses. Treat every statement about a product as true on the day it was read, and read the product's page again before you build on it.
What the example does not show#
The insurance example is an illustrative reconstruction for teaching. It follows the shape of a real project by the author, but the cases, the rules, the fields, the provider and every number are invented. Nothing here reports the quality of a real system or model. Example roof thresholds are synthetic, not insurance practice.
The model here is a scripted stand-in, so these results show how the tool layer works, not how good any model is.
| In the example | What it really is |
|---|---|
| The underwriting agent's model | A script that emits tool requests and a final recommendation per case. No model is called. There is no network and no key |
| The roof-data provider | A stand-in that answers from the case file, including scripted timeouts, rate limits and lost replies |
| The MCP server and client | A teaching subset of MCP revision 2026-07-28 over stdio, written from the specification. Not the official SDK, not conformance tested |
| Times | Values from a simulated clock, so every run prints the same numbers |
| Remote MCP, OAuth, streaming, progress, binary content | Described from the specifications; not implemented in the example |
The sister sites#
This site is one of a series on AI-native engineering. Each owns one subject and links the others at the seams.
| Site | What it owns |
|---|---|
| prompt.sammuthu.com | Instructions: how they are written, composed and defended |
| context.sammuthu.com | What the model can see now: selection, retrieval, budget |
| memory.sammuthu.com | Durable information and saved execution state |
| a2a.sammuthu.com | Messages between agents; A2A versus MCP |
| observe.sammuthu.com | Logs, metrics, traces, audit events, replay |
| guardrails.sammuthu.com | Enforceable checks around a probabilistic agent |
| schema.sammuthu.com | Typed contracts: shape, validation, repair, evolution |
| orchestrate.sammuthu.com | The control plane: what runs next |
| reliable.sammuthu.com | Acceptable outcomes despite failures and load |
| harness.sammuthu.com | The runtime around a model call |
| eval.sammuthu.com | Measurement: graders, golden sets, release gates |
| diff-to-deploy.sammuthu.com | Shipping a change with coding agents |
Sources and reading list#
Each link below was opened on 2026-11-17. The fact logs in the repository list every claim with the exact page it came from.
Protocols and standards#
| Source | Why read it |
|---|---|
| Model Context Protocol specification and the changelog of revision 2026-07-28 | Hosts, clients, servers, tools, resources, prompts, transports and authorization. Read the changelog first if you learned MCP before mid-2026 |
| MCP security best practices | Confused deputy, token passthrough, state handle hijacking |
| JSON Schema specification and reference | The language of input schemas |
| JSON-RPC 2.0 specification | The message format under MCP |
| OpenTelemetry semantic conventions for generative AI | Names for tool execution spans and MCP spans; in development |
Provider documentation and articles#
| Source | Why read it |
|---|---|
| Tool use with Claude | Tool definitions, tool_use and tool_result, strict tool use, tool search |
| Writing effective tools for agents, Anthropic | How to choose, name, describe and evaluate tools |
| Introducing advanced tool use, Anthropic | Tool search, programmatic tool calling, tool use examples |
| OpenAI function calling | Function tools, call ids, strict mode, tool choice |
| Gemini function calling | Function declarations, modes, parallel and compositional calling |
Libraries and SDKs#
| Source | Why read it |
|---|---|
| MCP Python SDK, TypeScript SDK, Java SDK | The official implementations; check which protocol revision each implements |
| Pydantic: JSON Schema | One typed model for the schema and the validation |
| Python typing | Type hints, Annotated, get_type_hints |
| JEP 395: Records and Jakarta Validation 3.1 | Java records with compact constructors, and constraint annotations |
| Spring AI tool calling and LangChain4j tools | Tools in Java applications |
| LangChain tools | Tools in a Python framework that binds many providers |
Who wrote it#
Written by Sam Muthu, an engineer who builds agentic systems. The example follows the shape of a real project by the author; everything in it is synthetic. Corrections are welcome.