Five ways to hand a tool to an agent

Chapter two divided every tool into three layers: the contract (which includes the name, description, input schema, result, and errors), the implementation that runs the tool, and the knowledge of how to use it. A packaging is a choice about where each layer resides. We will ask the same four questions for each packaging we discuss:

1. Where does the contract come from?
2. Where does the implementation run?
3. Where does the knowledge live?
4. How does the model learn the tool exists at all?

Each section below will complete one row of our table. Then, it will explain what the packaging solves and what it does not, which a table cannot fully show.

Vendors also define these distinctions. Anthropic’s comparison table states that Skills offer “Procedural knowledge”, while MCP offers “Tool connectivity”². Their advice is: “Use both together: MCP for connectivity, Skills for procedural knowledge”². A CMU lecture notes that REST APIs and MCP share “Names, descriptions, and JSON Schema for structured inputs” but differ in discovery, invocation, and authentication¹. The contract itself looks largely consistent across different systems; the surrounding infrastructure is what changes.

Keep one ruler in your pocket. In his October 2 guest lecture, Yan Wang explained that “Every hot noun bundles a lasting problem with packaging from its year”³. Packaging, as he put it, “depreciates”³. This is why you should learn packagings by their components, not by their brand names.

We start small. You write a function in your program. Each API request carries its contract: a name, a description, and a JSON Schema for its parameters. When the model decides the function would help, it replies with a structured call instead of prose. Google’s documentation explains this division of labor: “The model doesn’t execute the function itself.”⁵. Your code runs the function and sends the result back for the model’s next turn⁵.

OpenAI launched this feature on June 13, 2023⁶. Anthropic adds one distinction: client tools run in your application, while server tools like web_search run on Anthropic’s infrastructure⁷.

Filling in the row:

• Contract: You write it, and it travels inside every request.
• Implementation: This is your code, in your process.
• Knowledge: This includes whatever you put in the description and the system prompt.
• Existence: The model sees every function you list, on every request.

This solves the format problem: arguments arrive as JSON that matches a schema, not as prose you need to parse.

What this approach does not solve becomes clear as you scale up. OpenAI notes that “callable function definitions count against the model’s context limit and are billed as input tokens”⁴. Its guide suggests “fewer than 20 functions available at the start of a turn at any one time, though this is just a soft suggestion”⁴. Also, the definitions live in your request code. This means another team’s agent cannot use them without copying your code.

Now the opposite extreme: give the model one general tool, a shell, and let it run command-line programs it learned in training. mini-swe-agent executes every action with subprocess.run and describes itself as “Just some 100 lines of python for the agent class”⁹. Yan Wang’s summary: “Shell-native agents read –help and drive the same CLIs you use”³.

The Claude Code team asked the question plainly: “Do you give it one general-purpose tool like bash or code execution? Or fifty specialized tools, one for each use case?”¹⁰. They replaced a pre-built code index with a Grep tool so Claude could “search for files and build context itself”¹⁰. As of April 2026 it had about 20 tools, and “The bar to add a new tool is high, because this gives the model one more option to think about.”¹⁰.

The instructions for these agents are in plain files. Claude Code reads CLAUDE.md “at the start of every conversation”⁸. Codex reads AGENTS.md files at several levels, and “If there’s a more specific file closer to your current directory, that guidance wins.”¹¹.

Filling in the row:

• Contract: This is the command’s --help text and what the model remembers from training.
• Implementation: This is an existing program, launched through the shell.
• Knowledge: This comes from the instruction file.
• Existence: The instruction file names the commands, or training already provided this information.

This approach solves integration. The model already knows git, gh, and curl. One tool can represent hundreds of others.

However, it does not solve control. A command line has no schema, so nothing validates the arguments the way a schema would; only a hook or a permission rule can inspect the command before it runs. The shell also holds whatever the command needs. CMU’s slide on calling APIs with curl states it clearly: “Direct REST access is simple, but the agent’s shell receives the API credential.”¹. The instruction file cannot close this gap, because Claude Code’s documentation calls CLAUDE.md instructions “advisory”⁸. Hooks, in contrast, “are deterministic and guarantee the action happens”⁸. Some harnesses leave containment entirely to you. Pi’s README says it “does not include a built-in permission system for restricting filesystem, process, network, or credential access”¹². This is why Sierra’s fix was structural. A read-only, repository-scoped token limits the damage, no matter what the agent types¹³.

Practitioners still debate this trade-off. They praise CLIs as “precision instruments” or respond that “Authorization, in my opinion, is the big problem you need MCP for”¹⁴. These are opinions based on experience, not measurements.

A function gives an agent an ability. A skill gives it know-how. The Agent Skills specification defines a skill as “a directory containing, at minimum, a SKILL.md file”, with optional scripts/, references/, and assets/ folders¹⁵. The file starts with metadata, a name, and a description, followed by plain-language instructions¹⁵.

The trick is how the agent reads it. The specification calls this progressive disclosure: “Agents load skills progressively, pulling in more detail only as a task calls for it”¹⁵. There are three levels¹⁵:

1. Metadata, about 100 tokens. Every installed skill’s name and description load at startup.
2. Instructions, under 5,000 tokens recommended. The full SKILL.md body loads when the skill is activated.
3. Resources, as needed. Other files load only when required.

Anthropic describes these same levels². In Codex, the starting list of skills “uses at most 2% of the model’s context window, or 8,000 characters when the context window is unknown”¹⁶. Because the agent picks a skill by matching the task against descriptions, OpenAI asks for “concise descriptions with clear scope and boundaries”¹⁶.

The mechanism is small. The Hermes agent implements it as two tools: skills_list for names and descriptions, and skill_view for full content¹⁷. CMU’s first assignment has students build the same thing with an invoke_skill tool¹⁸.

Scripts are where a skill borrows capability. Anthropic’s PDF skill ships a script that extracts form fields, which Claude can run “without loading either the script or the PDF into context”¹⁹.

Filling in the row:

• Contract: two lines, the name and the description.
• Implementation: optional scripts; otherwise the tools the agent already has.
• Knowledge: the SKILL.md body and its files. This is the point of the packaging.
• Existence: the name and description sit in context from the start.

A skill does not enforce anything. The specification checks the format of the metadata, not whether the instructions are correct; even its allowed-tools field is marked “(Experimental)”¹⁵. And because a skill can carry scripts, Anthropic warns that “malicious skills may introduce vulnerabilities in the environment where they’re used”¹⁹.

Does adding a skill actually improve an agent? SkillsBench ran 87 tasks under 18 model–harness configurations, with and without curated skills²⁰: “Curated Skills raise the average pass rate from 33.9% to 50.5% (+16.6 percentage points; 25.5% normalized gain), with configuration-level gains ranging from +4.1 to +25.7 pp.”²². It also found that “Focused Skills with at most three modules outperform larger or exhaustive bundles”²². The authors note their own limits. Adding a skill provides context “so observed gains could partly reflect ‘more context’ rather than procedural structure”²². Their tasks are terminal-based, so the results might not transfer to agents using a graphical user interface (GUI) or to long workflows²².

The average can hide losses. CMU’s slide on the same benchmark shows “Skills still hurt on 13 of 87 tasks.”²⁰. Their explanation is that “A skill can displace a better default strategy.”²⁰. A second paper measured each skill’s contribution by randomly masking skills and found that “individual skills routinely help on some task types while hurting on others”²¹. It also reports a null result: GPT-5.1 on τ-bench scored 62.6% with and without a skill library that had been curated on a different benchmark, AppWorld, which the authors read as a limit set by the model’s “baseline competence on the target domain”²¹.

Who should write skills? CMU outlines two pathways²⁰. People can write skills based on their existing expertise; the main challenge here is “expert time to write and maintain”²⁰. Agents can learn skills from their own experiences, which shifts the challenge to judging outcomes, verifying skills, and curating the library²⁰.

People who write skills by hand agree on keeping them short and concrete. Yan Wang’s recipe has three parts: success criteria instead of a step-by-step procedure, the specific pitfalls the model encountered, and deterministic tools²³. On pitfalls, he is strict: “Only record mistakes AI actually made.”²³. Garry Tan’s test is: “If a smart intern could follow it, an agent can run it.”²⁴. OpenAI found the cost of skipping this discipline: with many long skill descriptions installed, “Codex starts shortening their descriptions to fit”, so the model sees less of each description and has a harder time picking the right skill²⁵.

Agents can also write their own skills. ASI induces skills as programs and verifies them by running them. On the WebArena web-browsing benchmark, with a Claude model, it reached a 40.4% success rate, against 32.7% for a static agent and 36.3% for a text-skill version: relative gains of 23.5% and 11.3%²⁶. The catch is over-specialization. PolySkill tested ASI and SkillWeaver on unseen websites and found skill reuse “less than 9% for ASI and less than 3% for SkillWeaver”²⁷. This line of research continues through workflow memory, code-skill libraries, learning from experience, and older program-library learners^{28,29,30,31,32,33,34}.

Anthropic introduced the Model Context Protocol on November 25, 2024, with a one-line diagnosis: “Every new data source requires its own custom implementation, making truly connected systems difficult to scale.”³⁷. MCP separates the program that offers tools from the application that uses them, and standardizes the conversation between them.

MCP defines three roles. The host is “The AI application that coordinates and manages one or multiple MCP clients”³⁶. A client is “A component that maintains a connection to an MCP server”³⁶. A server is “A program that provides context to MCP clients”³⁶. The host creates “one MCP client for each MCP server”³⁶. The messages exchanged are JSON-RPC 2.0³⁵, which is a “stateless, light-weight remote procedure call (RPC) protocol”³⁸.

A server offers resources (context and data), prompts (templated messages) and tools (“Functions for the AI model to execute”)³⁵. Tools are meant to be “model-controlled”: the model discovers and invokes them based on the task³⁹. The client discovers them at run time with tools/list and invokes one with tools/call¹. Since 2025-06-18 a server can also ask the user for more information, which the specification calls elicitation⁴⁰.

MCP spread quickly. OpenAI’s Agents SDK added support for MCP on March 26, 2025⁴¹. Google’s Agent Development Kit listed MCP tools at its launch on April 9, 2025⁴². Microsoft announced “broad first-party support” on May 19, 2025⁴³.

Filling in the row:

• Contract: This is written by the server’s author and sent to the host at run time.
• Implementation: This is the server process itself, which can be local or remote.
• Knowledge: This includes the tool descriptions and any instructions the server provides⁴⁴.
• Existence: tools/list.

Now what MCP leaves out. The overview states “it does not dictate how AI applications use LLMs or manage the provided context”³⁶. The specification acknowledges “MCP itself cannot enforce these security principles at the protocol level” and asks implementers to build consent and authorization flows into their applications³⁵. The host decides whether a call actually runs. CMU puts this in perspective: “MCP is an alternative agent-facing interface—not a requirement for calling REST APIs.”¹.

A transport moves messages. The specification’s transport overview defines two: stdio “newline-delimited messages over the standard streams of a client-launched subprocess” and Streamable HTTP “each message is an HTTP POST to a single MCP endpoint”⁴⁷. A transport “does not define what the messages mean”⁴⁷. The core protocol defines the message meaning.

The transport and session rules changed often:

• 2024-11-05. Two transports: stdio and “HTTP with Server-Sent Events (SSE)”⁴⁸.
• 2025-03-26. OAuth 2.1 authorization is added; Streamable HTTP replaces HTTP+SSE; JSON-RPC batching and tool annotations are added⁴⁹.
• 2025-06-18. Batching is removed; structured tool output, OAuth resource servers, and elicitation are added⁴⁰.
• 2025-11-25. Experimental tasks and OAuth Client ID Metadata Documents are added⁵⁰.
• 2026-07-28. The protocol-level session and the initialize handshake are removed⁴⁶.

The last change was the biggest. Earlier revisions opened a connection-scoped session with an initialize handshake. This meant a server had to remember each client⁴⁷. The 2026 release notes explain the benefits of removing it: “Any request can now land on any server instance behind a plain round-robin load balancer without needing shared storage.”⁴⁵. Cloudflare, which hosts MCP servers, said they “can now run in just a Worker”⁵¹.

If a server still needs state across calls, it must make that state explicit: “mint an explicit handle from a tool and have the model pass it back as an argument”⁴⁵. This is a tool-design lesson, not an MCP feature. It applies to a plain function too.

One 2026 change addresses the oldest question in this book: whether a call actually ran. A broken response stream now “loses the in-flight request; clients MUST re-issue it as a new request with a new request ID”⁴⁶. The client still does not know if the lost request completed its work.

The Python SDK’s v1.x line “is in maintenance mode and will only receive security fixes”⁵². The specification now promises “a minimum twelve-month deprecation window” for features it removes⁴⁶.

Read the five change lists side by side. Notice what none of them removes: tools as named operations, JSON Schema inputs, listing tools, and calling them. That stable core is worth learning in depth. Look up the transport details only when you need them.

A remote MCP server needs to know who is calling. The answer to this question evolved over four revisions.

• 2025-03-26. Authorization was optional⁵⁴. HTTP implementations should follow an OAuth 2.1 flow⁵⁴. Stdio servers should “retrieve credentials from the environment”⁵⁴.
• 2025-06-18. A protected server became “an OAuth 2.1 resource server”⁵³. It must “only accept tokens specifically intended for themselves”⁵³. It “MUST NOT pass through the token it received from the MCP client” to an upstream API⁵³.
• 2025-11-25. Client ID Metadata Documents became the recommended way for a client to register^50,55.
• 2026-07-28. Dynamic Client Registration, where a client registers itself on the fly, was deprecated and kept only for backwards compatibility⁵⁶. Clients now check which authorization server issued a token, so a malicious one cannot pass off a code from an honest one (a “mix-up attack”)^57,58.

All of this answers one question: is this client who it claims to be, and is this token meant for this server? Servers can also request narrow scopes “following the principle of least privilege”⁵⁷. What it does not answer is a different question: should this call, with these arguments, run right now? A valid token does not tell you that sending this email to this address is a good idea. That decision belongs to the host’s permission system and to the server’s own code, which the tools specification says must “Implement proper access controls”³⁹.

The most useful pattern here is one CMU teaches with FastMCP. The harness authenticates to the MCP server with one key. The server calls the upstream API with another key. CMU calls this credential brokering: “the server accepts one credential and uses a different credential upstream. The model sees neither secret.”¹. Compare this to the CLI section, where the shell holds the API key itself¹. FastMCP supports both ends: token verification on the server⁵⁹ and bearer tokens on the client⁶⁰.

Companies can add one more layer: an enterprise-managed authorization extension lets “the organization’s IT or security team” manage access to MCP servers in one place⁶¹.

MCP has three features that sound like safety controls. None of them actually are.

Annotations. Since 2025-03-26 a tool can carry annotations describing “whether it is read-only or destructive”⁴⁹. The maintainers explain four hints, readOnlyHint, destructiveHint, idempotentHint and openWorldHint, with pessimistic defaults: a tool with no annotations is treated as possibly destructive⁶⁴. The catch is in the word hint. The specification says “clients MUST consider tool annotations to be untrusted unless they come from trusted servers”⁶². The maintainers put it plainly: “A server can claim readOnlyHint: true and delete your files anyway.”⁶⁴. A guarantee against data leaving the machine is “a job for network controls or sandboxing, not a boolean hint”⁶⁴.

Hosts still use annotations. Codex, for example, requires approval for destructive MCP calls “when the tool advertises a destructive annotation (unless the tool advertises a read annotation, which takes priority)”⁶⁵. ChatGPT’s developer mode states “We respect the readOnlyHint tool annotation”⁶⁶. This approach works if you trust the servers. However, if you do not trust a server, a false read-only hint could disable your prompt for confirmation.

The registry. The official MCP Registry is “the official centralized metadata repository for publicly accessible MCP servers”⁶³. It is currently in preview⁶³. This registry hosts metadata that points to packages on npm, PyPI, or Docker Hub. It leaves the curation of these packages to downstream marketplaces⁶³. Its moderation process involves format validation and manual takedowns for spam or malicious servers⁶³. A listing in the registry simply means someone published metadata that passed format checks. It does not mean anyone has reviewed the server’s actual behavior.

Governance. Microsoft and GitHub joined the MCP Steering Committee in May 2025⁴³. On December 9, 2025, Anthropic donated MCP to the Agentic AI Foundation, which is a directed fund under the Linux Foundation⁶⁷. The announcement clarifies that “For MCP little changes”: the same maintainers will continue to make decisions through the specification’s public proposal process (SEPs)⁶⁷. Neither of these facts tells you anything about the trustworthiness of a specific server.

If the service you want to give an agent already has a web API, you may already have most of a contract. The standard description is OpenAPI, which “defines a standard, programming language-agnostic interface description for HTTP APIs”⁶⁹. Its purpose is to let people and programs discover a service’s capabilities “without requiring access to source code”⁶⁹. Each operation can carry an operationId, a unique name that tools and libraries may use to identify it, and the document declares security schemes such as API keys and OAuth2⁷⁰. You rarely write it by hand: “FastAPI generates a ‘schema’ with all your API using the OpenAPI standard”⁷¹.

This looks like an MCP tool list, and the overlap is real. A comparison from CMU starts with the shared elements—names, descriptions, and JSON Schema—then lists the differences¹:

CMU’s summary: “OpenAPI describes a web API; MCP standardizes how an AI host discovers and invokes capabilities.”¹.

So why not convert one into the other? You can. FastMCP “can automatically generate an MCP server from any OpenAPI specification”⁶⁸. By default it “converts every endpoint in your OpenAPI specification into an MCP Tool”⁶⁸. Its own documentation then advises against doing that for real use: “in practice LLMs achieve significantly better performance with well-designed and curated MCP servers than with auto-converted OpenAPI servers”⁶⁸. FastMCP gives no benchmark for “significantly”⁶⁸. The reasoning still holds: an API is shaped for programmers who read documentation once, while an agent’s tools are shaped for a model that chooses among them on every turn. Use the converter to bootstrap, then cut and rename.

Imagine an agent that checks expenses for 20 employees. Anthropic’s documentation describes two ways to do this. With direct calls, “the traditional approach requires 20 separate model round-trips, pulling thousands of expense line items into the context along the way”⁷³. With programmatic tool calling, “a single script runs all 20 lookups, filters the results, and returns only the employees who exceeded their limits”⁷³.

In this setup, the model gets one tool that runs code. The other tools become functions inside a sandbox. In Cloudflare’s Code Mode, “our agent is presented with just one tool, which simply executes some TypeScript code”⁷⁴. The sandbox’s “only access to the outside world is through the TypeScript APIs representing its connected MCP servers”⁷⁴. Cloudflare argues that tool-call tokens are “things LLMs have never seen in the wild”, while ordinary code is everywhere⁷⁴.

Filling in the row:

• Contract: These are function signatures inside the sandbox.
• Implementation: These are the real tools, called back from the sandbox.
• Knowledge: This is the program the model writes for the task.
• Existence: The agent loads the tool definitions it needs on demand, rather than loading all of them upfront⁷⁵.

The numbers are real but narrow, so keep their conditions attached. Anthropic’s code execution with MCP reports one example where it dropped “from 150,000 tokens to 2,000 tokens”⁷⁵; the post does not name a model or report accuracy. On the BrowseComp and DeepSearchQA search benchmarks, adding Anthropic’s programmatic tool calling on top of basic search tools “improved performance by an average of 11% while using 24% fewer input tokens”⁷³; the page does not name the model. Its launch post reports usage falling “from 43,588 to 27,297 tokens, a 37% reduction on complex research tasks”⁷⁶, but it names neither the tasks nor the model. OpenAI runs each program “in a fresh, isolated V8 runtime” without direct network or filesystem access⁷². CMU’s first assignment builds the same idea as a run_python tool¹⁸.

This approach does not solve the sandbox itself. Running agent-written code “requires a secure execution environment with appropriate sandboxing, resource limits, and monitoring”⁷⁵. CMU lists these controls: “Use sandboxing, resource limits, permissions, and audit logs.”¹. Vendors also draw a line at write operations. For “Writes or approval-sensitive actions”, OpenAI’s decision table says: “Use direct tool calling by default to preserve a clear authorization boundary.”⁷². Anthropic’s equivalent setting comes with a bold warning: “Do not rely on allowed_callers as a security boundary.”⁷³.

In Code Mode, the sandbox reaches each server through a binding; every call on it goes to the agent supervisor, which holds the access tokens and adds them to the request⁷⁴. That is why “the AI cannot possibly write code that leaks any keys”⁷⁴. This is credential brokering again.

Each host decides how MCP servers are configured, how many tools it will take, and when a call needs your approval. The defaults differ by host.

Consider another example: OpenAI’s Responses API MCP tool “defaults to requiring approvals of each MCP tool call”⁸². Its own example of deferred loading sets "require_approval": "never"⁸². A default is only effective if people maintain it.

The names in this chapter are young. On March 23, 2023, OpenAI launched ChatGPT plugins: you built an API, described it with an OpenAPI specification, and added a manifest file⁸⁴. The same post reported that red teamers found ways for plugins “to perform sophisticated prompt injection, send fraudulent and spam emails, bypass safety restrictions”⁸⁴. In October 2023, Semantic Kernel renamed its skills to plugins⁸³. There, a skill had meant a function “called by the same process that’s running your kernel”⁸³. In November 2023, GPTs gained actions that could reuse an existing plugin manifest⁸⁵. In October 2025, OpenAI released the Apps SDK, “an open standard built on the Model Context Protocol (MCP)”⁸⁶.

We can learn two things here. First, read definitions, not just labels. The word ‘skill’ has had two different meanings. Second, the risks were identified on day one, more than a year before MCP existed^37,84.

This chapter focuses on one key judgment: cost. Every packaging method beyond a plain function adds something you need to run, secure, and keep current. So, you must name what each method adds that a local function would not provide.

• CLI plus instructions adds zero integration for tools the model already knows. This costs you the schema, and the shell holds the credential.
• A skill adds reusable know-how that loads only when needed. This costs text the model may ignore, and it can hurt performance on some tasks.
• An MCP server adds one server that many hosts can discover and call, and it provides a clean place to broker credentials. This costs another process and a specification that has had five revisions in twenty months.
• Code execution adds fewer tokens and round trips for many calls. This costs a sandbox you must build and watch.

Now apply it. Imagine your team builds a tool server for one agent with three tools: searching the course catalog, reading a syllabus, and posting a question. If one agent in one harness is the only consumer, a local function gives you the same contract with less to run. CMU states it directly: MCP is “not a requirement for calling REST APIs”¹. Now, change one fact. Five teams’ agents across three different hosts need these same tools, and the posting tool requires a key no agent should hold. In this scenario, MCP adds real benefits: one server every host can discover, and a broker that keeps the upstream key away from the model¹.

Sierra chose gh over GitHub’s MCP server because the agents already knew the command¹³. The authors of FastMCP advise you to curate a server rather than mirror an API⁶⁸. Yan Wang’s default approach is a sequence, not a winner: “Start with a CLI and an instruction file; add MCP when distribution requires it”³.

Now run the ruler. Yan Wang identifies MCP’s lasting problem as “Giving agents clear, safe interfaces and deciding what plain code should handle”³. He names its packaging as “Routing every tool definition and result through the context window, MCP-first”³. If models were 10 times better, the lasting problem would still matter: someone still decides what an agent may touch and which work belongs in plain code. Much of the packaging would matter less. However, the cost of switching would not disappear. The 2026-07-28 revision removed sessions and the handshake⁴⁶, and a partner quoted in the release said “The biggest changes are breaking ones”⁴⁵. Whatever you choose, you will pay to move off it later.

1. Draw the five-by-four table from memory. For each packaging type, show where the contract, the implementation, and the knowledge live. Explain how the model learns that the tool exists.
2. Explain to a classmate the difference between this client may talk to this server and this call should run now. Which question does MCP authorization answer? Who answers the other?
3. Pick a tool you have used. Name its packaging. What is one thing it adds over a local function? What is one thing it costs?