Stage 6 of 12 · about 2.9 h

Tools and agents

Let the model ask for tools, run them in a bounded loop, guard them, and share them over MCP.

A model cannot run code, but it can ask your code to. You define tools with JSON Schema, read the model's tool_use blocks, run the functions yourself, and send the results back. Then you wrap that in a loop with a stated invariant, every stop condition handled, and step and token budgets, so Pocket can search, read, and count on its own. Because notes can carry injected instructions, you threat-model the agent and add guards that hold even when the model is fooled: no write tools by default, a path allowlist, and human approval. Last, you serve Pocket's tools over MCP and test them with a client you write.

Before you start

You can call an LLM API from Python, force a structured reply with a JSON Schema, handle retries, and chunk and search your notes by headings, as in stages 4 and 5.

When you finish

pocket/stage6/ holds tools.py, agent.py, guarded.py and pocket_mcp.py: an agent that decides when to search and read your notes, stops within set budgets, cannot write without your approval, and serves its note tools to any MCP host.

1. Lesson 1 · 40 min

   Tool calling: the model asks, your code acts

   You can define tools with JSON Schema, read a tool_use block off the wire, run the function it names, and send back a tool_result so the model can answer a question that needs two notes.

2. Lesson 2 · 45 min

   The agent loop

   You can write an agent loop with a stated invariant and every stop condition handled, bound it with step and token budgets, return tool failures as error results, and read its step log.

3. Lesson 3 · 45 min

   Guardrails: data is not instructions

   You can threat-model an agent by source, sink, and privilege, mark tool output as data, keep write tools off by default and behind human approval, refuse paths outside an allowlist, and prove the guards hold against a real injected note.

4. Lesson 4 · 45 min

   MCP: tools any client can use

   You can name the MCP roles and transports, read a JSON-RPC exchange, serve Pocket's note tools with the official Python SDK, and test the server with a client you write yourself.