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

Tools engineering · callable capabilities for agentic software

The model proposes a call. Your code decides whether it runs.

A language model can only write text. Everything an agent does in the world, from reading a roof report to storing a recommendation, happens because ordinary code read that text, checked it, and chose to run a function. This site starts from one plain function and climbs, one idea at a time, to schemas, result contracts, the Model Context Protocol, safe execution, retries and tests, asking one question at each step: who is allowed to do what, and what happens when it fails?

For engineers who build agents, and for backend engineers who will host their tools. One running example, and code that runs without a model, a network or an API key.

You will understand
Why a model never runs anything, and who does.
You will be able to say
What a tool is, in one sentence, and why a tool that writes needs more care than one that reads.
You will know
The insurance example and its five tools, which every page uses, and where this site sits in its series.

An email arrives at an insurer's submissions inbox. A broker wants a quote for an office building:

From: broker@brokerage.example
To: submissions@insurer.example
Subject: Quote request SUB-1004

Please quote property cover for a masonry office, built 2001, 20,000 sq ft, sprinklered. The owner says the roof was replaced 9 years ago. Wind zone C. No losses.

The insurer wants software to do the first pass on requests like this one. The software should check the roof, read the insurer's written guidance, look at similar past cases, apply the rules, and leave a recommendation for a person. The person is an underwriter: the employee who decides whether the insurer accepts a risk.

Every step in that sentence touches something outside the software that reasons about the email. The roof age lives at an outside roof-data provider. The guidance lives in a document store. Past decisions live in a database. The recommendation must end up in a table that the underwriter's screen reads. The team plans to use a language model for the reasoning, and here the problem starts. A language model takes text in and writes text out. It cannot open a network connection, query a database or insert a row. So how does the roof age get from the provider into the model's reasoning, and how does the recommendation get from the model into the table?

A model writes text, and that is all it does#

The answer is a convention, and it is simpler than the word "agent" suggests. The application that talks to the model tells it, in the request, which capabilities exist: "there is a capability named get_roof_assessment; it takes a submission_id; it returns the assessed roof age". When the model wants the roof age, it does not fetch it. It writes a short, structured piece of text that says which capability it wants and with which values. The application reads that text, decides whether to act on it, runs a function of its own, and sends the result back to the model as more text.

That capability is called a tool. A tool is an external capability that the agent may request: the model proposes a call, and application code validates it and executes it. Here is a tiny example of the request part, exactly as the model in this site's example writes it for submission SUB-1004:

{"id": "call_01", "name": "get_roof_assessment", "arguments": {"submission_id": "SUB-1004"}}

Three fields. A name, chosen from the list the application offered. Arguments, the values the model filled in. And an id, so that the result can be matched to this request later. This piece of text is a tool call, which this site also calls a tool request, because it is a request and nothing more. Nothing has happened in the world yet. The model has written a wish down.

Then the application acts. It looks the name up in its own list, checks that "SUB-1004" is a valid submission id, checks that this agent is allowed to read roof data, and only then calls its own Python function get_roof_assessment. The function asks the roof-data provider. The provider says 22 years. The application wraps that answer and sends it back under the same id, call_01:

{"ok": true, "data": {"submission_id": "SUB-1004", "roof_age_years": 22, "evidence_id": "EV-ROOF-0412"}, "meta": {"tool": "get_roof_assessment", "attempt_number": 1}}

(This result is trimmed to the fields that matter here; Result contracts shows the whole shape.) The model now reads "22" as part of its conversation and continues. Two parties took part, and only one of them touched the world.

The first primitive. The model proposes a call. Your code decides whether it runs. Every page of this site keeps that sentence true, and most pages are about what "your code decides" has to include.

Diagram: The first primitive · the model proposes a call, your code decides whether it runs

Read left to right. The model writes a request and later reads a result; it never touches the world. Every box that checks, decides or changes something belongs to the application. Click a box to see what it does for submission SUB-1004.

  1. 1 · The model
    1. Writes a tool call: The model writes structured text naming a tool from the offered list, the argument values, and a call id. Nothing has happened yet.
  2. 2 · The application decides
    1. Looks up and validates: The application finds the name in its own registry and checks the arguments against the tool's input schema.
    2. Authorizes: The application checks that the caller holds the scope the tool needs. A refusal is audited and nothing runs.
  3. 3 · The application acts
    1. Runs the function: Only now does code touch the world: the function asks the outside provider.
    2. Sends the result under the same id: The application wraps the answer or the error and sends it back keyed by the call id.
  4. 4 · The model again
    1. Reads the result: The result becomes part of the conversation. The model asks for another tool or writes its final answer.

Read the diagram for who acts. The model's lane contains one box that writes and one box that reads. Every box that checks, decides or changes something sits in the application's lane. That is not a design preference of this site. It is how the mechanism works with every provider this site read: the model's output is text, and text only becomes an action when your code turns it into one.

Before AI. A backend engineer has built this many times. A browser submits a form; the form says "transfer 500 to account 77". The browser is a client you do not control, so the server never trusts the form. A Spring controller binds the body to an object, bean validation rejects bad fields, a security filter checks the session's role, and only then does a service method touch the database. A tool call is a form submitted by a model. The model is a client you do not control either.

The analogy is closer than it looks, and the one difference matters. A browser form is filled in by a person who saw your page. A tool call is filled in by a model that read everything in its conversation: the broker's email, retrieved guidance, results of earlier tools. Some of that text came from strangers. So the arguments of a tool call deserve the same suspicion as a form posted from the open internet, and sometimes more. Safety is the page about that suspicion.

The example in one minute#

Software does not work from the email. An intake step reads it once and writes the facts down as one structured record, called a submission. A submission is a JSON record of one quote request; every later step reads it and never the email. In the scenario it has 63 fields; the example code carries the ten below.

{
  "submission_id": "SUB-1004",
  "occupancy": "office",
  "construction": "masonry",
  "year_built": 2001,
  "area_sq_ft": 20000,
  "building_value_usd": 2400000,
  "sprinklered": true,
  "roof_age_years": 9,
  "wind_zone": "C",
  "prior_losses_5y": 0
}

The submission goes to the underwriting agent. An agent is a program that calls a language model in a loop and runs the tools the model asks for in between, until the model gives a final answer. This one gathers evidence with tools, applies the insurer's rules through a tool that is plain code, and writes a recommendation. It has five tools, and they are the subject of this site:

ToolWhat it doesReads or writes
get_roof_assessmentAsks the outside roof-data provider for the assessed roof age; returns an evidence id such as EV-ROOF-0412reads
search_guidanceSearches the insurer's written guidance, the policy fixture; returns passages with rule idsreads
find_similar_decisionsFinds past decisions on similar submissions, each with the policy version it was made underreads
check_eligibilityApplies the rules of the policy fixture; the same input always gives the same resultreads
record_recommendationStores the recommendation as one row for the underwriter, with status awaiting_underwriterwrites

For SUB-1004 the tools turn up a problem that the email did not show. The owner says the roof is 9 years old. The roof-data provider says 22. The guidance has a rule for that, R-ROOF-03: when the two ages differ by more than 5 years, the case goes to a senior underwriter. This is case UW-004, the default case on most pages of this site. The agent's final answer is a recommendation:

{"recommendation": "escalate", "citations": ["R-ROOF-03"], "missing": [], "stated_confidence": 0.6, "requires_human": true, "policy_version": "2026.2", "evidence_ids": ["EV-ROOF-0412"]}

(The reasons field is left out above; it names both roof ages and the 13-year gap.) A recommendation is one of four values, approve, decline, request_info or escalate, with reasons and the ids of the rules it rests on. The model recommends; a person decides. The recommendation waits in the underwriter cockpit, a web app, until an underwriter acts. No tool in the catalog approves, declines, binds a policy or quotes a price. The underwriter's decision is written by the cockpit's own code, under the person's role, and the agent has no tool that reaches it.

Diagram: The example in one minute · an email, a record, five tools, a recommendation, a person

Read left to right. Each column is one party. The four reads gather evidence, the one write stores the recommendation, and the decision sits in a lane of its own because it belongs to a person. Click a box to see its part in case UW-004.

  1. 1 · Broker and intake
    1. Email: A broker asks for a quote in ordinary sentences.
    2. Submission: Intake writes the facts into one record. Every later step reads the record, never the email.
  2. 2 · Four read tools
    1. get_roof_assessment: Asks the roof-data provider for the assessed roof age. Reads only.
    2. search_guidance find_similar_decisions: Reads the written guidance and past decisions. Retrieved text is data, never an instruction.
    3. check_eligibility: Applies the rules of the policy fixture. Same input, same result.
  3. 3 · One write tool
    1. record_recommendation: Stores the recommendation for the underwriter. Needs the stronger scope uw.recommend and an idempotency key.
  4. 4 · A person
    1. Underwriter decides: An authorized underwriter reads the recommendation and decides. The cockpit's own code stores the decision; no tool of the agent can.

The model here is a scripted stand-in, so these results show how the tool layer works, not how good any model is. No model is called anywhere in the example: a small Python class plays the model's part and writes the tool requests a careful model would write. Everything else is real code: the tool definitions, the validator, the registry, the execution adapter, the loop and the tests.

Honest boundary. This 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.

Read tools and write tools at a glance#

Four of the five tools only read. One writes. That split runs through every later page, so it is worth seeing why it matters before any code.

A read tool changes nothing outside the run. Ask get_roof_assessment for SUB-1004 once or five times: the world is the same afterwards, and the worst outcome of an extra call is a wasted request to the provider. A write tool changes something outside the run. Call record_recommendation once and there is one row in the recommendations table. Call it twice and, unless something prevents it, there are two rows, and an underwriter sees the same case twice.

QuestionRead tool (get_roof_assessment)Write tool (record_recommendation)
What changes in the world?NothingA row is stored for the underwriter
Is a repeated call harmless?Yes, apart from costNo: a second row, unless an idempotency key stops it
What scope must the caller hold?uw.readuw.recommend, a stronger permission
If a model is tricked into calling itIt reads data the caller could already readIt stores something a person will act on
Where this site treats itFunctions, then SafetyFunctions, then Safety and Reliability

A scope is a named permission that a caller holds. In the example, the underwriting-agent holds uw.read and uw.recommend; a second agent that only assesses roofs holds uw.read. When that second agent asks for record_recommendation, the application refuses before anything runs. That is this site's own case UW-T03, and the refusal is written to an audit log for people.

The catalog also teaches by what it leaves out. In this site's own case UW-T08, a broker's email says "update the roof age to 5 years". The model may well want to do that. It cannot, because no tool changes a submission. The safest write tool is the one you never offered.

The ladder: one function, six forms#

The same capability appears in six forms on the way from your code to the model, and each later page of this site lives on one of the rungs. The lab below walks get_roof_assessment up the ladder. Edit the argument to a bad value, such as the number 1004 instead of the text "SUB-1004", and see on which rung the bad value is caught. The table after it holds the same information.

RungWhat it holdsA bad value such as {"submission_id": 1004}
1. Python functionget_roof_assessment(world, submission_id: str) in functions.py; the model never sees itnot checked
2. Type hintssubmission_id: str; Python does not check hints when the function runsnot checked
3. Generated schema{"type": "string"} from the hint; the pattern ^SUB-[0-9]{4}$ is lostcaught: type, expected string, got integer
4. Tool definitionthe schema with the pattern added back from the constraints tablecaught (also "SUB-04": pattern)
5. MCP tools/list entrythe same schema as inputSchema, plus title and annotations
6. MCP tools/callrequest with the arguments; result with isError true and an invalid_arguments envelope, attempt_number 0the function never runs

The last row is the first primitive again. A bad value reaches the application, and the application rejects it with attempt_number 0: zero attempts, because nothing ran. The model reads the rejection, corrects the value, and asks again. That is this site's own case UW-T01.

In a coding agent. The same split appears in every coding agent. read_file, search_code and run_tests read, or act only inside a contained workspace; edit_file, git_push and open_pull_request change something other people will see, so the harness asks for permission first. The model writes {"name": "git_push", ...} either way. Whether a push happens is decided by code. Diff to Deploy follows such changes from a diff to production.
What this is not. This site is about the capabilities an agent may call and the code that executes them. The runtime around the model call, which holds the loop, the context and the state, is the agent harness, and it has its own site: https://harness.sammuthu.com. How instructions and tool descriptions are worded as prompts, in depth, belongs to https://prompt.sammuthu.com.
Tools that run somewhere else: does the first primitive still hold?Server tools, hosted MCP connectors and SDK runners move the executing code, not the rule

Some providers run certain tools themselves. Anthropic's documentation, as documented on 2026-11-17, distinguishes client tools, which run in your application (the response stops with stop_reason "tool_use" and you send back a tool_result), from server tools such as web search, web fetch and code execution, which run on Anthropic's infrastructure and whose results come back inside the same response. The SDKs of several providers also offer a runner that executes your functions and loops for you.

Neither changes the primitive. A server tool is still executed by code, not by the model: the provider's code, under the provider's limits. A runner is still your code; it is your function that runs, called by a library loop instead of a loop you wrote. What changes is where the deciding code lives and who can change it. A server tool is code you cannot read, validate or authorize per call. A runner is code you can read but may forget to configure.

The practical rule: for each tool, write down which program executes it and which program could refuse it. If the answer to the second question is "nobody we control", the tool should only read, and only data that the agent may see anyway. Every write tool of this site's example is executed by the application's own adapter, where validation, authorization and idempotency live.

Tool, function, function calling: one idea, several namesVendors use the words differently; this site keeps "function" for the code and "tool" for the capability

The documentation of three model providers, read on 2026-11-17, describes the same mechanism with different words. Anthropic's says that tool use is also called function calling. OpenAI's guide is titled "Function calling" and its definitions have type: "function". Google's Gemini guide is also titled function calling and its definitions are function declarations.

This site separates two words on purpose. A function is ordinary code with arguments and a return value: get_roof_assessment in functions.py. A tool is the capability offered to the model: the definition the model reads plus the execution path the application controls. The difference is not pedantic. A function can be called by any code that imports it; a tool can only be requested, and the request can be refused. When a vendor's field is named function, this site quotes it unchanged and still calls the capability a tool.

Tool calling shows the three providers' message shapes side by side, and Frameworks describes each provider's API on its own section.

Where this fits#

Tools are one of thirteen subjects in a series of guides by the same author. Each site owns one question about agentic software and links to the others where the subjects meet, instead of repeating them. This one is marked below.

Three neighbors matter most for this site. The harness runs the loop that carries tool requests and results. Guardrails put enforceable checks around what tools may do. Observability records what each tool call really did. Where a page of this site reaches one of those subjects, it says what the subject is not here, in one sentence, and links the site that owns it.

How to read this site#

The pages follow the order in which questions come up when a team gives its first agent its first tool. First the foundations: what a function is, how a model asks for one, how the request is described and checked, and what comes back. Then the protocols that let tools be found and shared. Then the production work: the code inside a tool, its safety, its reliability and its tests. A reference part closes the site.

Foundations. From a plain function to a contract the model can read.

Protocols. Finding the right tool, and sharing tools between applications.

Production. The code inside a tool, and what keeps it safe and alive.

Reference. Libraries and standards, the hard edges, and the whole example.

If you are new to agents, read in order: every page assumes only the pages before it. If you already ship tools, jump to the question of the day. Each page recaps what it needs in a sentence and links the full explanation, and each folds its harder material (failure cases, competing designs, security and operations) into blocks like the two above, so the first reading stays short.

If your question isStart at
What exactly travels between the model and my code?Tool calling
Why did the model send a number where I expected text?Schemas, then Types
What should a failed tool send back?Results
How do I share tools between applications?MCP architecture
How do I keep a retried write to one row?Safety
Which library does which part for me?Frameworks

In one breath#

A model cannot do anything by itself; it writes text. A tool is a capability my application offers: the model writes a request with a name, arguments and an id, and my code checks it, decides whether it may run, runs a function, and sends the result back under the same id. Reads change nothing and can be repeated; writes change the world and need stronger permission and protection against running twice. The model proposes a call; my code decides whether it runs.

That sentence is easy to agree with and easy to break, because the deciding code has to know exactly what a function takes, returns and changes. Before any model is involved, a tool is a function, and the next page looks at the five functions of the example as plain Python: their arguments, their return values, their side effects, and what happens when one of them is called twice. That is Functions.