An agent is only as good as its tools and what it remembers. Interviewers ask "how does tool calling work", "explain MCP's architecture", "an agent has 200 tools, what breaks" and "design memory for an assistant" because each has a concrete engineering answer. In real work, most agent bugs are not model bugs. They are a vague tool description, a tool that returns 5,000 tokens of raw JSON, an error message the model cannot act on, or a memory store that returns an old address. This lesson gives you the vocabulary and the numbers to answer all four questions aloud.

What a tool is, and the flow of one call

A tool is a function your application offers to the model. Each tool has a name, a description and a JSON schema for its arguments. The model cannot run anything. It only writes text, so a "tool call" is the model writing a tool name and JSON arguments in a structured format. Your code does the rest.

One tool call takes four steps:

1. Request. The application sends the conversation plus the tool definitions.
2. Tool call. The model replies with a call, not an answer: get_order with {"order_id": "A1042"}.
3. Execution. The application validates the arguments, runs the function and appends the output to the conversation as a tool-result message.
4. Answer. The application calls the model again. The model now sees the result and either answers or asks for another tool.

After those four steps the conversation holds four messages (simplified; field names differ between providers):

[
  {"role": "user", "content": "Where is order A1042?"},
  {"role": "assistant", "tool_call": {"id": "call_1", "name": "get_order", "arguments": {"order_id": "A1042"}}},
  {"role": "tool", "tool_call_id": "call_1", "content": "shipped, arrives Friday, total 1200 INR"},
  {"role": "assistant", "content": "Your order has shipped and arrives on Friday."}
]

The call id ties each result to its call, which matters when the model asks for several tools in one turn. One tool use costs two model calls, and the result stays in the context for the rest of the conversation.

What a good tool definition looks like

The model never sees your code. It sees only the definition, so the definition is a prompt. A good tool does one clear job and gets five parts right.

{
  "name": "get_order",
  "description": "Look up one order by its id. Use it when the user asks about status or delivery date. Do not use it to search by customer name.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "pattern": "^A[0-9]{4}$", "description": "Order id, for example A1042"}
    },
    "required": ["order_id"]
  }
}

The description says when to use the tool and when not to. Typed arguments (patterns, enums, ranges) let your code reject a bad call before it runs. Short results save context. An error that says how to fix the call lets the model correct itself in the next step, where a bare status code makes it guess or loop. The exact field name for the schema differs between providers, but the three parts are always there.

Design tools around what the user wants, not around your API. If answering "where is my order" needs three endpoints (order, shipment, courier), one get_order_status tool that calls all three is better than three tools the model must chain correctly. Keep read tools and write tools separate, so that approval rules can apply to the writes only.

Every tool definition costs context tokens

Tool definitions travel with every request. Assume one definition is about 150 tokens. Ten tools cost 1,500 tokens per model call, which is fine. Two hundred tools cost 30,000 tokens per call before the user has said a word. Two things break: the context and the bill fill up, and the model picks the wrong tool when many look alike.

The fixes:

• Many tools: load tool definitions on demand through a tool search step, not all at the start. Keep a small core set always loaded, plus one search_tools tool that returns the few definitions that match the current task.
• Group and namespace tools (orders.get, orders.refund) so related ones are easy to tell apart.
• Merge overlapping tools, and move specialised sets into sub-agents.

MCP: build a tool once, use it everywhere

MCP (Model Context Protocol) is an open standard for connecting models to tools and data. A server exposes tools, resources and prompts; any compatible client can use them. Build a tool once, reuse it across models and frameworks.

Function calling and MCP solve different problems. Function calling is how one model asks for one tool inside one app. MCP is a standard way to package and expose tools so any client can discover and use them. MCP sits on top of function calling; it does not replace it. Without a standard, 5 applications and 20 internal systems need up to 100 custom integrations. With MCP you write 20 servers and 5 clients.

MCP roles: host, client, server

MCP architecture: a host runs one client per server and the model never talks to a server directly

• Roles: the host is the AI application. It runs one client per server. The server exposes capabilities. The model never talks to the server directly.

The last sentence is the one to remember. The model writes a tool call. The host validates it, asks the user to approve if needed, and passes it to the client for that server. The host stays in control of what is called. A server also cannot read the whole conversation or see other servers; it receives only what the host sends.

Three primitives, and who controls each

Control matters for safety. A resource cannot act. A prompt runs only when a person chooses it. Tools are the risky primitive, because the model chooses them.

Messages, transports and the rest of the protocol

• Messages: JSON-RPC 2.0, with methods such as tools/list and tools/call.
• Transports: stdio for local servers started as a subprocess; Streamable HTTP for remote servers. The older HTTP plus SSE transport is deprecated.
• Authorization: an OAuth-based framework for remote servers; local stdio servers read credentials from the environment.
• Latest revision (2026-07-28): the protocol became stateless. The initialize handshake and sessions were removed, each request carries its version, and state is passed through explicit handles. Tutorials written before this may be out of date.
• Governance: maintained under the Linux Foundation's Agentic AI Foundation, not by one vendor.
• Practical limit: every tool definition costs context tokens on every request, so a small set of well-described tools beats one tool per API endpoint.

A JSON-RPC request is a JSON object with a method name, parameters and an id. The reply carries the same id and either a result or an error. A tool call looks like this (the _meta field that carries the protocol version is left out):

{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_order", "arguments": {"order_id": "A1042"}}}

Choosing a transport is simple. With stdio the host starts the server as a child process on the same machine and they exchange messages over standard input and output. Nothing listens on a network port. Use it for local files and developer tools. With Streamable HTTP the server is a service at a URL and each client message is an HTTP POST. Use it for shared company tools with many users.

"Explicit handles" means that a server needing state between calls, such as a shopping basket, returns an id from one tool and takes that id as an argument in the next. With no handshake, a client that wants to know a server's supported versions and capabilities up front calls server/discover. A failed tool run comes back as a normal result marked as an error, with readable text, so the model can fix the call.

These protocol details follow the MCP guide listed in the resources, checked against the 2026-07-28 specification.

One safety rule: a tool description is text that goes into your model's context. If the server is not yours, treat its descriptions and its results as untrusted input, not as instructions.

MCP and A2A

A2A (Agent2Agent) is a protocol for agents to discover and talk to other agents. MCP connects an agent to tools; A2A connects agents to each other. A tool is a function with a schema: you call it and get a result. An agent is a peer that takes a goal, may work for minutes, and may ask questions back. A travel agent that calls search_flights uses MCP. A travel agent that hands "book a hotel near the venue" to a separate hotel agent built by another team uses A2A.

Short-term and long-term memory

A model keeps nothing between calls. Whatever it "remembers" is text your application put into the prompt again.

• Short-term memory is the context window and run state. It lasts one conversation or one run. Keep the working state in the context, and summarise or drop old turns as it fills.
• Long-term memory is an external store (vector database, files, a key-value store) that the agent reads and writes. It survives across sessions. Write durable facts to it and retrieve them when relevant.

Decide what is worth remembering, because storing everything pollutes later retrieval.

There are two ways to run the reads and writes. In the first, the application does it: after each conversation a background step extracts facts and saves them, and before each model call the application searches the store and adds the hits to the prompt. This is predictable and easy to test. In the second, memory is a pair of tools (save_memory, search_memory) and the model decides when to use them. This is more flexible, but the model sometimes forgets to save or to search. Many systems mix them: an always-loaded profile from the application, plus a search tool for the model.

Four types of memory

The design questions are the same for each: what to write, when to retrieve, how to resolve conflicting facts, and how to delete on request.

The four memory design questions

1. What to write. Only durable, useful facts: preferences, decisions, stable profile data. Not small talk, not guesses, not secrets such as card numbers. Run an explicit write step that extracts candidate facts and stores each with a user id, a timestamp and its source.
2. When to retrieve. Load a small profile (a few hundred tokens) at the start of every session. Search the rest only when the request needs it, and return the top 3 to 5 items, not everything.
3. How to resolve conflicts. "I live in Pune" in January and "I moved to Bengaluru" in March cannot both be current. Prefer the newest and keep its source. Mark the old fact as superseded; never blend the two. A fact the user stated beats one the system inferred.
4. How to delete. The user must be able to see, correct and delete what is stored. A delete must reach every copy: the record, its embedding in the vector index, and any summary built from it.

What 200 tools cost. A company wraps every internal API endpoint as a tool and ends up with 200. Assume each definition is 150 tokens, an average task takes 12 model calls, and the agent runs 10,000 tasks a day.

• Definitions per model call: 200 x 150 = 30,000 tokens.
• Definitions per task: 30,000 x 12 = 360,000 tokens.
• Per day: 360,000 x 10,000 = 3.6 billion input tokens. At an assumed 1 USD per million input tokens that is 3,600 USD a day spent only on describing tools.

Now load tools on demand. Keep 5 core tools plus one search_tools tool always loaded: 6 x 150 = 900 tokens. Each step also carries the 5 definitions that the search returned: 5 x 150 = 750 tokens.

• Definitions per model call: 900 + 750 = 1,650 tokens.
• Definitions per task: 1,650 x 12 = 19,800 tokens.
• Per day: 19,800 x 10,000 = 198 million tokens, or 198 USD at the same assumed price.

That is 94.5% less. If the search costs one extra model call, a task takes 13 calls: 13 x 1,650 = 21,450 tokens, still 94% less. Prompt caching can make a stable block of definitions cheaper, but it does not give the context space back, and the model still has to choose among 200 similar names. Fewer visible tools fixes cost and tool choice together.

One memory conflict. The store holds city = Pune (written 5 January, source: user message). On 20 March the user says "I moved to Bengaluru". The write step stores city = Bengaluru with the new timestamp and marks the old record superseded. A later request, "find a dentist near me", retrieves only the newest city. If a batch job later replays the January message, its older timestamp loses, so the stale value cannot come back.

"""A tool registry that validates arguments, and a small long-term memory store.

Standard library only. The registry sits between the model's tool call and your
real function: it rejects bad calls with errors the model can act on. The memory
store shows the four decisions: what to write, when to retrieve, how to resolve
conflicts (newest wins) and how to delete.
"""
import re


class ToolRegistry:
    def __init__(self):
        self.tools = {}

    def register(self, name, description, schema, fn):
        self.tools[name] = {"description": description, "schema": schema, "fn": fn}

    def definitions(self):
        """What is sent to the model on every request."""
        return [{"name": n, "description": t["description"], "arguments": t["schema"]}
                for n, t in self.tools.items()]

    def validate(self, name, args):
        if name not in self.tools:
            return [f"Unknown tool '{name}'. Available tools: {', '.join(sorted(self.tools))}."]
        schema, errors = self.tools[name]["schema"], []
        for key in args:
            if key not in schema:
                errors.append(f"Unknown argument '{key}'. Allowed arguments: {', '.join(schema)}.")
        for key, rule in schema.items():
            if key not in args:
                if rule.get("required"):
                    errors.append(f"Missing required argument '{key}' ({rule['hint']}).")
                continue
            value = args[key]
            types = {"string": str, "number": (int, float)}[rule["type"]]
            if isinstance(value, bool) or not isinstance(value, types):
                errors.append(f"'{key}' must be a {rule['type']}. You sent {value!r}.")
            elif "pattern" in rule and not re.fullmatch(rule["pattern"], value):
                errors.append(f"'{key}' must be {rule['hint']}. You sent {value!r}.")
            elif "enum" in rule and value not in rule["enum"]:
                errors.append(f"'{key}' must be one of {rule['enum']}. You sent {value!r}.")
            elif "max" in rule and not (rule.get("min", 0) <= value <= rule["max"]):
                errors.append(f"'{key}' must be between {rule.get('min', 0)} and {rule['max']}. You sent {value}.")
        return errors

    def call(self, name, args):
        """Always returns text for the model. Never raises into the agent loop."""
        errors = self.validate(name, args)
        if errors:
            return {"is_error": True, "content": " ".join(errors) + " Fix the call and try again."}
        return {"is_error": False, "content": self.tools[name]["fn"](**args)}


class MemoryStore:
    def __init__(self):
        self.records = {}   # (user, key) -> list of versions, newest first

    def write(self, user, key, value, timestamp, source):
        versions = self.records.setdefault((user, key), [])
        versions.append({"value": value, "timestamp": timestamp, "source": source})
        versions.sort(key=lambda v: v["timestamp"], reverse=True)   # ISO dates sort as text
        return versions[0]

    def retrieve(self, user, query, k=2):
        words = set(re.findall(r"[a-z0-9]+", query.lower()))
        scored = []
        for (owner, key), versions in self.records.items():
            if owner != user:
                continue                       # never mix users
            newest = versions[0]               # conflict rule: the newest fact wins
            text = set(re.findall(r"[a-z0-9]+", f"{key} {newest['value']}".lower()))
            overlap = len(words & text)
            if overlap:
                scored.append((overlap, key, newest))
        scored.sort(key=lambda s: (-s[0], s[1]))
        return [(key, rec["value"], rec["timestamp"], rec["source"]) for _, key, rec in scored[:k]]

    def delete(self, user, key):
        return self.records.pop((user, key), None) is not None


def get_order(order_id):
    return f"Order {order_id}: shipped, arrives Friday, total 1200 INR."


def issue_refund(order_id, amount, reason):
    return f"Refund of {amount} INR queued for {order_id} ({reason})."


if __name__ == "__main__":
    reg = ToolRegistry()
    order_rule = {"type": "string", "required": True, "pattern": r"A\d{4}", "hint": "the letter A then 4 digits, like A1042"}
    reg.register("get_order", "Look up one order by id. Use for status or delivery questions.",
                 {"order_id": order_rule}, get_order)
    reg.register("issue_refund", "Refund an order. Use only after the policy check passed.",
                 {"order_id": order_rule,
                  "amount": {"type": "number", "required": True, "min": 1, "max": 5000, "hint": "INR, 1 to 5000"},
                  "reason": {"type": "string", "required": True, "enum": ["damaged", "wrong_item", "late"], "hint": "why"}},
                 issue_refund)
    print("tools sent to the model:", [d["name"] for d in reg.definitions()])

    calls = [
        ("get_ordr", {"order_id": "A1042"}),
        ("get_order", {"id": "A1042"}),
        ("get_order", {"order_id": "1042"}),
        ("issue_refund", {"order_id": "A1042", "amount": 9000, "reason": "angry"}),
        ("issue_refund", {"order_id": "A1042", "amount": 1200, "reason": "damaged"}),
        ("get_order", {"order_id": "A1042"}),
    ]
    for name, args in calls:
        result = reg.call(name, args)
        print(f"\ncall  : {name}({args})")
        print("error :" if result["is_error"] else "result:", result["content"])
    assert reg.call("get_order", {"order_id": "1042"})["is_error"]
    assert not reg.call("get_order", {"order_id": "A1042"})["is_error"]

    print("\n--- memory ---")
    mem = MemoryStore()
    mem.write("u1", "city", "Pune", "2026-01-05", "user message")
    mem.write("u1", "diet", "vegetarian food only", "2026-01-09", "user message")
    mem.write("u2", "city", "Chennai", "2026-02-01", "user message")
    print("retrieve 1:", mem.retrieve("u1", "which city should the dentist be in"))
    current = mem.write("u1", "city", "Bengaluru", "2026-03-20", "user message")
    print("after the move, current city:", current["value"])
    stale = mem.write("u1", "city", "Pune", "2026-01-05", "replayed import")
    print("after replaying the old fact, current city:", stale["value"])
    print("retrieve 2:", mem.retrieve("u1", "which city should the dentist be in"))
    print("retrieve 3:", mem.retrieve("u1", "book a table, vegetarian food, in my city"))
    assert mem.retrieve("u1", "city")[0][1] == "Bengaluru"
    print("delete city:", mem.delete("u1", "city"))
    print("retrieve 4:", mem.retrieve("u1", "which city should the dentist be in"))
    assert mem.retrieve("u1", "city") == []
    assert mem.retrieve("u2", "city")[0][1] == "Chennai"
    print("other users untouched:", mem.retrieve("u2", "city"))