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
About

About this site and its sources

What this site is, what it is not, where its ideas come from, the sister sites, and how the facts were checked.

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 isIt is not
A ladder: one idea per step, each word in plain English with a tiny example before it is usedA 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-T08A 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 togetherA 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 outputA 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 toolA ranking or a buying guide. No product is called best, and no price is quoted

What is original here and what is not#

PartStatus
Tool, tool call, tool result, tool definition, input schemaCommon 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, OAuthPublished 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 searchFrom 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 codesA 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 breakersEstablished practice in distributed systems, applied here to tools
The five tools, the policy fixture, the eighteen cases, the callers and scopesWritten for this site. All synthetic
The example code, its 62 tests, the Java fileWritten for this site
The interactive labs and the diagramsWritten 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 claimHow it was checked
A named product, protocol or libraryRead 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 exampleRun. 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 fileCompiled and run with JDK 23.0.1 as java TypedTool.java. Its output is in the example's README
The labsThey read data generated from the example. A parity test runs 186 checks that the JavaScript gives the same results as the Python
Other codeA block that was not run says so, for example "documented shape; not run here"
Links and structureA 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 exampleWhat it really is
The underwriting agent's modelA 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 providerA stand-in that answers from the case file, including scripted timeouts, rate limits and lost replies
The MCP server and clientA teaching subset of MCP revision 2026-07-28 over stdio, written from the specification. Not the official SDK, not conformance tested
TimesValues from a simulated clock, so every run prints the same numbers
Remote MCP, OAuth, streaming, progress, binary contentDescribed 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.

SiteWhat it owns
prompt.sammuthu.comInstructions: how they are written, composed and defended
context.sammuthu.comWhat the model can see now: selection, retrieval, budget
memory.sammuthu.comDurable information and saved execution state
a2a.sammuthu.comMessages between agents; A2A versus MCP
observe.sammuthu.comLogs, metrics, traces, audit events, replay
guardrails.sammuthu.comEnforceable checks around a probabilistic agent
schema.sammuthu.comTyped contracts: shape, validation, repair, evolution
orchestrate.sammuthu.comThe control plane: what runs next
reliable.sammuthu.comAcceptable outcomes despite failures and load
harness.sammuthu.comThe runtime around a model call
eval.sammuthu.comMeasurement: graders, golden sets, release gates
diff-to-deploy.sammuthu.comShipping 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#

SourceWhy read it
Model Context Protocol specification and the changelog of revision 2026-07-28Hosts, clients, servers, tools, resources, prompts, transports and authorization. Read the changelog first if you learned MCP before mid-2026
MCP security best practicesConfused deputy, token passthrough, state handle hijacking
JSON Schema specification and referenceThe language of input schemas
JSON-RPC 2.0 specificationThe message format under MCP
OpenTelemetry semantic conventions for generative AINames for tool execution spans and MCP spans; in development

Provider documentation and articles#

SourceWhy read it
Tool use with ClaudeTool definitions, tool_use and tool_result, strict tool use, tool search
Writing effective tools for agents, AnthropicHow to choose, name, describe and evaluate tools
Introducing advanced tool use, AnthropicTool search, programmatic tool calling, tool use examples
OpenAI function callingFunction tools, call ids, strict mode, tool choice
Gemini function callingFunction declarations, modes, parallel and compositional calling

Libraries and SDKs#

SourceWhy read it
MCP Python SDK, TypeScript SDK, Java SDKThe official implementations; check which protocol revision each implements
Pydantic: JSON SchemaOne typed model for the schema and the validation
Python typingType hints, Annotated, get_type_hints
JEP 395: Records and Jakarta Validation 3.1Java records with compact constructors, and constraint annotations
Spring AI tool calling and LangChain4j toolsTools in Java applications
LangChain toolsTools 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.