Agentic AI networks module 2: prompts, structured output, tools and MCP

Day 15 · 17/11 — System prompts, and prompting 2

Goal: write a system prompt for an agent that is short, testable and stable.

Theory 1/2: what goes in the system prompt

The system message holds what stays true for the whole session: the role, the rules, the output format, what to do when unsure. It sits at the start of every request, so it is also the part the KV cache reuses (day 3): keep it stable, and put what changes in the user messages. Every token of it is paid at every turn: the site measured an agent where repeated instructions and tool descriptions were most of the bill (the context floor).

Theory 2/2: prompting for this module, weak and edited

Weak system prompt: "You are a helpful assistant. Be accurate and concise. Help with server stuff." What is wrong: "helpful" and "accurate" are wishes, not rules; "server stuff" is not a task; nothing says what to do when unsure or what format to return. Edited:

You classify support messages for a small self-hosted lab.
Task: for each message, return its category and urgency.
Categories: outage, slowness, access, question, other.
Urgency: high if a service is down for several users, else normal.
Rules: use only the message text; if it fits no category, use "other".
Format: one JSON object {"category": ..., "urgency": ..., "reason": "<12 words"}.
Example: "Nobody can open the wiki since 9am" -> {"category": "outage", "urgency": "high", "reason": "wiki down for everyone"}
Your answer is parsed by a program: output the JSON object only.

Practice (30 min)

1. Copy the edited prompt into prompts/triage.txt in ainet-lab.
2. Write ten test messages in bench/triage.jsonl with the expected category and urgency.
3. Adapt your day-12 runner to load the system prompt from the file and score category and urgency separately.
4. Change one rule, rerun, and note the effect in the notebook.

With your AI: "Here is my system prompt and three messages it misclassified, with the expected answers: [paste]. Tell me which rule or missing rule explains each mistake, and propose the smallest change to the prompt for each. Do not rewrite the whole prompt; I will test each change separately."

Let an agent do it: now that you have tuned a prompt by hand, a coding agent can run the loop: "Run bench/run.py with prompts/triage.txt, list the failing cases, propose one prompt change at a time, rerun after each, and report the score table; never edit triage.jsonl." Check the expected answers stayed untouched and reread the final prompt yourself.

Recap (10 min)

Three lines: what goes in a system prompt, why it stays stable, what makes a rule testable. Redo the second exercise without notes.

Day 16 · 18/11 — Examples and reasoning

Goal: use examples (few-shot) and step-by-step reasoning where they help, and measure whether they do.

Theory 1/2: few-shot

Showing two or three input/output pairs is often the fastest way to fix a format or a style: the model imitates. Choose examples that cover the hard cases and differ from each other; a single example tends to be copied too literally. Examples cost tokens at every call.

Theory 2/2: reasoning before answering

Wei and colleagues showed in 2022 that asking a model to write intermediate steps improves results on multi-step problems (chain-of-thought prompting). Since then, many models are trained to reason on their own (day 13). For an agent, reasoning helps on planning and arithmetic, and is wasted on simple classification. When you ask for reasoning, ask for it in a separate field so code reads only the answer.

Practice (30 min)

1. Add three varied examples to prompts/triage.txt as triage-fewshot.txt; run the bench on both.
2. Create bench/arith.jsonl: five small word problems with numeric answers. Run with and without "reason step by step in a 'reasoning' field, then give 'answer'".
3. Note scores, tokens used (from usage) and time for each variant.

With your AI: "Here are my bench scores and token counts for four prompt variants: [paste table]. Tell me which variant is the best value for money, defined as score per thousand tokens, show the arithmetic, and say whether the differences are large enough to trust with only ten cases."

Recap (10 min)

Three lines: when examples help, when reasoning helps, how to keep the answer parsable. Redo the first exercise without notes.

Day 17 · 19/11 — JSON and JSON Schema

Goal: describe the expected answer with a schema and validate every answer in code.

Theory 1/2: a contract for the answer

JSON Schema describes the shape of a JSON document: types, required keys, allowed values (enum), lengths. The same schema serves three purposes: you put it in the prompt, the runtime can enforce it (tomorrow), and your code validates the answer against it. Never trust an answer that has not been validated: a model can return valid-looking JSON with a missing key or an invented category.

{"type": "object",
 "properties": {
   "category": {"enum": ["outage", "slowness", "access", "question", "other"]},
   "urgency": {"enum": ["high", "normal"]},
   "reason": {"type": "string", "maxLength": 80}},
 "required": ["category", "urgency"]}

Theory 2/2: validate, then decide

In Python, the jsonschema package validates a document against a schema. When validation fails, the program decides: retry once with the error message, fall back, or report. It never "fixes" the meaning silently.

function valid(obj) {
}

function valid(obj) {
  const cats = ["outage", "slowness", "access", "question", "other"];
  return !!obj && typeof obj === "object"
    && cats.includes(obj.category)
    && ["high", "normal"].includes(obj.urgency);
}

Practice (30 min)

1. Save the schema as schemas/triage.json; uv add jsonschema.
2. In your runner, parse each answer with json.loads and validate it; count invalid answers separately from wrong ones.
3. Add one retry: when validation fails, send the error message back and ask for a corrected object. Measure how many retries succeed.

With your AI: "Here is my JSON Schema and five answers my model produced: [paste]. For each answer, say whether it validates and, if not, which rule it breaks, quoting the schema line. Then I will run the jsonschema package and compare with your verdicts."

Let an agent do it: once you have written validation by hand, an agent can generate schemas: "From these ten example objects, write a JSON Schema in schemas/, with enums where values repeat, and a test that validates all ten and rejects three broken variants." Check the enums against your real categories; an agent may add or drop one.

Recap (10 min)

Three lines: the three uses of a schema, what the program does on failure. Redo valid without notes.

Day 18 · 20/11 — Constrained decoding

Goal: make the runtime itself refuse tokens that would break the format.

Theory 1/2: grammars

Instead of hoping the model writes valid JSON, the runtime can forbid, at each step, every token that would leave the allowed format: this is constrained decoding. llama.cpp uses GBNF grammars and converts JSON Schemas to grammars. On /v1/chat/completions, llama-server accepts response_format with a schema; Ollama accepts a schema in its format field (structured outputs).

Theory 2/2: limits

Constraints can hurt quality when the format fights what the model wants to write; long free-text fields inside a schema are fine, odd structures less so. Ollama's documentation also recommends putting the schema in the prompt to ground the model. Keep validation in code anyway: a different runtime or a model change may drop the constraint.

Practice (30 min)

1. Send a triage request to llama-server with the schema:

   curl -s http://127.0.0.1:8080/v1/chat/completions -H 'Content-Type: application/json' -d '{
    "messages": [{"role": "user", "content": "Nobody can log in to the wiki."}],
    "response_format": {"type": "json_schema", "json_schema": {"name": "triage", "schema":
      {"type": "object", "properties": {"category": {"enum": ["outage","slowness","access","question","other"]},
       "urgency": {"enum": ["high","normal"]}}, "required": ["category","urgency"]}}}}'

   If your build rejects this shape, use the form shown in the server README ({"type": "json_schema", "schema": {...}}).
2. Do the same with Ollama's format field on /api/chat.
3. Run your bench with constraints on: compare invalid answers (should be zero) and wrong answers with day 17.

With your AI: "Explain what a GBNF grammar is, with a tiny grammar that only allows 'yes' or 'no'. Then show how llama.cpp's documentation says a JSON Schema becomes a grammar, quoting the documentation section name so I can find it. Mark anything you are not sure of."

Recap (10 min)

Three lines: what constrained decoding guarantees and what it does not, the field for each runtime. Redo the first exercise without notes.

Day 19 · 21/11 — Calling a model from code, robustly

Goal: wrap model calls with timeouts, retries and logs, as any network call deserves.

Theory 1/2: a model is a slow, unreliable service

Treat a model call like any remote call: it can hang, fail, or return garbage. Set a timeout, retry with a growing delay (backoff) only on errors worth retrying (connection refused, 429, 503), cap the number of attempts, and log the request id, model, tokens and duration. The site's article one gateway for all your models describes three settings that froze agents for days.

function delays(attempts, base) {
}

function delays(attempts, base) {
  const out = [];
  for (let i = 0; i < attempts; i++) out.push(base * 2 ** i);
  return out;
}

Theory 2/2: what not to retry

Practice (30 min)

1. Write ainet/llm.py with one function ask(messages, schema=None): base URL and model from the environment, a timeout, three retries with backoff on connection errors and 5xx, a log line per call (model, tokens in/out, ms).
2. Test it: stop the server mid-run and check that it retries then fails cleanly.
3. Write one pytest test that runs ask against a fake server (a tiny http.server returning a fixed answer).

With your AI: "Review this Python function that calls an LLM API: [paste]. Check four things: timeout set, retries only on retryable errors, a cap on attempts, and nothing secret in the logs. For each, quote the line and say pass or fail. Then ask me what should happen when the response JSON is invalid."

Let an agent do it: now that you wrote ask by hand, an agent can harden it: "Add streaming support to ainet/llm.py behind a stream=True argument, keep the retry rules, and add a test with the fake server." Check that the retry rules are unchanged and that the test really executes the new path.

Recap (10 min)

Three lines: timeout, retry rules, what to log. Redo delays without notes.

Day 20 · 22/11 — Tool calling 1: the idea

Goal: understand the exchange where a model asks for a function and your code runs it.

Theory 1/2: the model asks, the program acts

With tool calling (or function calling), the request lists tools, each with a name, a description and a JSON Schema of its parameters. The model may answer with a tool call instead of text: a name and arguments. Your code runs the function, appends the result as a tool message, and calls the model again, which can then answer or call another tool. OpenAI introduced function calling in its API in June 2023; the format became the common one that llama.cpp and Ollama accept.

Theory 2/2: dispatching

The program keeps a table from tool names to functions, parses the arguments (JSON text), refuses unknown names, catches errors, and returns a short text result. Errors are returned to the model as results ("error: file not found"), so it can correct itself.

const TOOLS = { add: ({a, b}) => a + b };
function dispatch(call) {
}

const TOOLS = { add: ({a, b}) => a + b };
function dispatch(call) {
  const tool = TOOLS[call.name];
  if (!tool) return "error: unknown tool " + call.name;
  try {
    return String(tool(JSON.parse(call.arguments)));
  } catch (e) {
    return "error: " + e.message;
  }
}

Practice (30 min)

1. Read the Ollama tool calling page and llama.cpp's function calling doc; note the request and response fields.
2. On paper, write the full message list of a conversation where the user asks "what is 17 + 25?", the model calls add, your code returns 42, and the model answers.
3. Write ainet/tools.py with a TOOLS table and a dispatch function in Python mirroring the exercise.

With your AI: "Here is my hand-written message list for one tool-calling exchange: [paste]. Check it against the OpenAI chat completions format: roles, the tool_calls field, the tool_call_id link between call and result. List every mistake with the corrected line."

Recap (10 min)

Three lines: who decides, who executes, how errors return. Redo dispatch without notes.

Day 21 · 23/11 — Tool calling 2: with a local model

Goal: run a working tool loop against your local model, with a step limit.

Theory 1/2: the loop

The loop: send messages and tools; if the answer has tool calls, run each, append results, and loop; if it has text only, stop. Always cap the number of steps: a confused model can call tools forever. With llama.cpp, tool calling depends on the chat template (day 13); its documentation lists native formats and a generic fallback, which works but uses more tokens.

Theory 2/2: reading failures

Typical failures with small models: the call is written as text instead of a structured call, arguments are invalid JSON, a parameter is invented, the same call repeats. Log each step; most problems become obvious when you read the messages.

Practice (30 min)

1. Write loop.py:

   import json
   from openai import OpenAI
   from ainet.tools import TOOLS, dispatch   # your day-20 module
   
   client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="none")
   tools = [{"type": "function", "function": {"name": "add", "description": "Add two integers.",
             "parameters": {"type": "object", "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
                            "required": ["a", "b"]}}}]
   messages = [{"role": "user", "content": "What is 17 + 25? Use the tool."}]
   for step in range(5):
       msg = client.chat.completions.create(model="local", messages=messages, tools=tools).choices[0].message
       messages.append(msg.model_dump(exclude_none=True))
       if not msg.tool_calls:
           print(msg.content)
           break
       for call in msg.tool_calls:
           result = dispatch({"name": call.function.name, "arguments": call.function.arguments})
           messages.append({"role": "tool", "tool_call_id": call.id, "content": result})

2. Run it on your best model; print every message.
3. Add a second tool, word_count(text), and a question that needs both. Note how many steps it took.

With your AI: "Here is the full message log of my tool loop with a local model: [paste]. Identify at which step things went wrong, if anywhere, and whether it looks like a template, a tool description or a model capacity problem. Give one experiment to tell them apart."

Let an agent do it: having written the loop yourself, ask a coding agent: "Turn loop.py into a function run(question, tools, max_steps) in ainet/loop.py, keep the step cap, log each step as JSON lines, and add a test with a fake model that calls add once." Check the cap is still enforced by reading the code and running the test with a fake model that never stops.

Recap (10 min)

Three lines: the loop, the cap, the most common failure. Rewrite the loop from memory.

Day 22 · 24/11 — Designing good tools

Goal: write tools a model uses correctly and a program can trust.

Theory 1/2: the description is a prompt

The model chooses a tool from its name, description and parameter schema only. A good tool does one thing, has a verb-noun name (read_file, search_notes), says in its description when to use it and when not, constrains parameters (enums, ranges), and returns short, useful results with clear errors. Fewer, well-described tools beat many overlapping ones.

Theory 2/2: safe by construction

The program, not the model, enforces limits: a read_file tool accepts only paths inside one folder; a tool that changes things asks for confirmation or is not given at all. Prefer read-only tools; make changing tools idempotent when you can (running twice does no harm). Return a capped amount of text: a tool that dumps a 2 MB log fills the context.

function inside(root, path) {
}

function inside(root, path) {
  const norm = p => {
    const out = [];
    for (const part of p.split("/")) {
      if (part === "" || part === ".") continue;
      if (part === "..") out.pop(); else out.push(part);
    }
    return out;
  };
  const r = norm(root), p = norm(path);
  return p.length >= r.length && r.every((seg, i) => seg === p[i]);
}

Practice (30 min)

1. Write three tools in ainet/tools.py for a folder of Markdown notes: list_notes(), read_note(name) (only inside the folder, at most 4,000 characters), search_notes(query) (returns at most five file names with a line each).
2. Write pytest tests, including one that tries ../ and one with a missing file.
3. Use them in your loop with three questions about your own notebook.

With your AI: "Here are the names, descriptions and parameter schemas of my three tools: [paste]. Pretend you are a small model seeing them for the first time. For each of these five user requests [paste], say which tool you would call with which arguments, and point out any description that left you unsure."

Let an agent do it: now you know what a safe tool looks like, an agent can write the next ones: "Add a tool recent_notes(days) to ainet/tools.py following the existing pattern (folder limit, output cap, error strings), with tests for 0 days and a negative value." Check the folder limit is used and run the ../ test yourself.

Recap (10 min)

Three lines: what makes a good description, where limits are enforced, why cap output. Redo inside without notes.

Day 23 · 25/11 — MCP 1: why a protocol

Goal: explain what the Model Context Protocol standardises and who plays which role.

Theory 1/2: the N × M problem

Without a standard, every AI application writes its own integration for every tool: N applications times M tools. The Model Context Protocol (MCP), published by Anthropic in November 2024 (announcement), defines one way for an application to discover and use external tools and data; it borrows the idea from the Language Server Protocol of code editors. In December 2025, Anthropic donated MCP to the Agentic AI Foundation, a fund under the Linux Foundation co-founded with Block and OpenAI (MCP blog).

Theory 2/2: roles and primitives

Three roles: the host (the AI application, such as a coding agent), the client (the connector inside the host, one per server), the server (the program that offers capabilities). Messages are JSON-RPC 2.0. Servers offer three primitives: tools (functions the model can call, via tools/list and tools/call), resources (data to read) and prompts (templates for users). The specification (latest) states that hosts must obtain the user's consent before invoking a tool, and that tool descriptions from untrusted servers are themselves untrusted.

function call(id, name, args) {
}

function call(id, name, args) {
  return { jsonrpc: "2.0", id: id, method: "tools/call",
           params: { name: name, arguments: args } };
}

Practice (30 min)

1. Read the MCP introduction and the specification overview.
2. Draw host, clients and two servers in your notebook, with the messages for listing and calling a tool.
3. Browse the reference servers and pick two you would use, noting what each tool can read or change.

With your AI: "Quiz me on the Model Context Protocol with eight questions, one at a time: roles (host, client, server), primitives (tools, resources, prompts), message format, and the security principles of the specification. After each answer, correct me and point to the specification section to read."

Recap (10 min)

Three lines: the problem MCP solves, the three roles, the three primitives. Redo call without notes.

Day 24 · 26/11 — MCP 2: transports, versions, the Inspector

Goal: know how MCP messages travel and test a server with the official Inspector.

Theory 1/2: two standard transports

stdio: the client launches the server as a subprocess and exchanges newline-delimited JSON-RPC on its standard input and output; nothing listens on the network, which suits local tools. Streamable HTTP: each message is an HTTP POST to one endpoint, replies come back as JSON or a stream; it suits remote servers and needs authentication. The specification is versioned by date; the latest at the time of writing is 2026-07-28, which moved protocol metadata into every request, while revisions up to 2025-11-25 opened a session with an initialize handshake. Libraries handle both; tutorials written for older revisions show the handshake.

Theory 2/2: the Inspector

The MCP Inspector is the official testing tool: it connects to a server, lists its tools, resources and prompts, and lets you call them by hand. npx @modelcontextprotocol/inspector opens its web interface; it also has --cli and --tui modes.

Practice (30 min)

1. Install Node.js if needed, then run npx @modelcontextprotocol/inspector.
2. Connect it to a reference server over stdio, for example the filesystem server limited to one test folder (see its README in the servers repository for the exact command).
3. List the tools, read their schemas, call two of them, and note what each returns.
4. Try to read a file outside the allowed folder and note the error.

With your AI: "Here are the tool names and descriptions an MCP server exposes: [paste from the Inspector]. For each, tell me whether it only reads, changes something, or reaches the network, and which ones I should never give an agent without confirmation. Explain your reasoning in one line each."

Let an agent do it: now that you have used the Inspector by hand, its --cli mode lets an agent run checks: "Use the MCP Inspector CLI to list the tools of this server and call read-only tools with these arguments; save the outputs to mcp-check.md." Check that it called no tool that changes files.

Recap (10 min)

Three lines: the two transports and when to use each, what the Inspector is for. Redo the first exercise without notes.

Day 25 · 27/11 — MCP 3: write a server

Goal: expose your note tools as an MCP server with the official Python SDK.

Theory 1/2: the Python SDK

The official Python SDK (package mcp, version 2 in 2026) turns typed Python functions into tools: the type hints become the input schema, the docstring becomes the description. Tutorials written for version 1 import FastMCP; version 2's README uses MCPServer:

from mcp.server import MCPServer

mcp = MCPServer("Notes")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

Theory 2/2: keep the logic outside

Keep your tool logic in plain functions (ainet/tools.py, already tested) and make the MCP layer a thin wrapper. You can then test the logic without MCP, and swap the protocol layer if it changes.

Practice (30 min)

1. uv add "mcp[cli]" in ainet-lab.
2. Write mcp_notes.py exposing list_notes, read_note and search_notes from your module, with clear docstrings. The notes folder comes from an environment variable.
3. Run uv run mcp dev mcp_notes.py, which opens it in the Inspector, and call each tool.
4. Commit.

With your AI: "Here is my MCP server in Python: [paste]. Review it as a security-minded colleague: can any tool read outside the notes folder, return unbounded output, or leak an environment variable? Quote the line for each risk you find, and say 'none found' rather than inventing one."

Let an agent do it: now that you have written one server, an agent can add a resource: "Expose each note as an MCP resource notes://{name} in mcp_notes.py, reusing read_note, and add a test that lists and reads one." Check in the Inspector that the resource honours the folder limit.

Recap (10 min)

Three lines: what the SDK infers, why the logic stays outside. Write the five-line server from memory.

Day 26 · 28/11 — MCP 4: plug it into a client

Goal: let a real agent use your server, and decide which third-party servers you trust.

Theory 1/2: clients

Most agent harnesses are MCP hosts: coding agents such as Claude Code, Kimi Code or OpenFox, desktop chat applications, and workflow tools. Each has a configuration listing servers: a command for stdio, or a URL for HTTP. llama-server itself can also load stdio MCP servers from a configuration file (--mcp-servers-config, a recent feature: check that your build has it). Your own loop from day 21 can be an MCP client too with the SDK's Client.

Theory 2/2: trusting a server

An MCP server is code running with your rights, and its tool descriptions go straight into the model's context. Before installing one: read its source or at least its tool list, prefer official or well-known ones, pin a version, give it the narrowest folder or token, and turn off tools you do not need. A description can contain instructions aimed at the model; module 4 comes back to this.

Practice (30 min)

1. Add mcp_notes.py to one MCP client you use (its documentation shows the configuration format), pointing at a test notes folder.
2. Ask the agent three questions answered by your notes; check in the server's log which tools were called.
3. If you use a local model behind that client, compare with a hosted model on the same three questions (optional).
4. Write a "trust sheet" in the notebook for one third-party server: source, version, tools, what each can read or change, your decision.

With your AI: "Here is the README and tool list of a third-party MCP server I am considering: [paste]. Fill in a trust sheet: who publishes it, what each tool can read, change or send out, which permissions it needs, and three questions I should answer by reading its code before installing it."

Let an agent do it: once you have written one trust sheet by hand, an agent can draft the next: "Read the source of this MCP server repository, list every tool and every network call or file write in the code with its file and line, and fill trust-sheet.md." Check a few of the cited lines yourself.

Recap (10 min)

Three lines: how a client starts a server, the trust checks. Redo the third exercise without notes.

Day 27 · 29/11 — Instruction files and skills

Goal: give agents durable project instructions and on-demand procedures, without bloating every prompt.

Theory 1/2: project instruction files

Coding agents read an instruction file at the root of a repository: AGENTS.md is an open format, now also a project of the Agentic AI Foundation; some tools use their own name for it. It holds what a newcomer must know: how to build, test, the conventions, what never to do. Short and specific beats long and vague: every line is read at every session.

Theory 2/2: skills, loaded when needed

A skill is a folder with a Markdown file describing when to use it and how, loaded only when the task calls for it, so many skills cost little until needed. The site's article skills: teach your agent a procedure once shows the ones used daily.

Practice (30 min)

1. Write AGENTS.md for ainet-lab: how to install, run the tests, run the bench, the folder limit rule for tools, what never to commit (keys, personal notes).
2. Write one skill folder skills/run-bench/ with a SKILL.md: when to use it, the exact commands, how to read the results.
3. Ask a coding agent to run the bench and see whether it follows your file.

With your AI: "Here is my AGENTS.md: [paste]. Mark each line as 'actionable and checkable', 'vague' or 'useless for an agent'. For each vague line, propose a precise replacement with a command or a measurable rule."

Recap (10 min)

Three lines: what goes in the instruction file, what goes in a skill, why short wins. Redo the first exercise without notes.

Day 28 · 30/11 — Prompting for tool use

Goal: fix tool descriptions and instructions until a small model calls the right tool with the right arguments.

Theory 1/2: weak and edited tool descriptions

Weak: search(q) — "Searches." What is wrong: searches what? Returns what? When to prefer it over read_note? No limits on q. Edited:

name: search_notes
description: Find notes whose text contains all the given words.
  Use it when you do not know the note's name; use read_note when you do.
  Returns at most 5 lines "name: first matching line". Returns "no match" if none.
parameters: {"query": {"type": "string", "minLength": 2, "maxLength": 100,
             "description": "2 to 5 plain words, no quotes or operators"}}

And in the system prompt, one rule per tool family: "Answer questions about notes only from tool results; if no tool returns the answer, say you did not find it."

Theory 2/2: measure tool choice

Test tool use like any other output: a case is a question plus the expected tool name and key arguments. Score the first tool call by code. This is the bench that tells you whether a model is fit to be an agent.

function rightTool(call, expectedName, mustContain) {
}

function rightTool(call, expectedName, mustContain) {
  if (call.name !== expectedName) return false;
  let args;
  try { args = JSON.parse(call.arguments); } catch (e) { return false; }
  return Object.values(args).join(" ").toLowerCase().includes(mustContain.toLowerCase());
}

Practice (30 min)

1. Write bench/tools.jsonl: twelve questions with the expected first tool and a keyword.
2. Score your best local model with the current descriptions.
3. Rewrite the descriptions with the pattern above; rerun; note both scores and which cases changed.

With your AI: "Here are my tool descriptions and the four cases where my local model chose the wrong tool, with the tool it chose: [paste]. For each case, say which words in the descriptions could have misled it, and propose one change per description. Do not change the tools themselves."

Let an agent do it: now that you have improved descriptions by hand, an agent can iterate: "Run bench/tools.jsonl against the local model, propose one description change at a time, rerun, and keep a log of score per change; stop after five changes." Check the final descriptions are still true about what each tool does.

Recap (10 min)

Three lines: the parts of a good description, how you score tool choice, your before/after scores. Redo rightTool without notes.

Day 29 · 01/12 — Module 2 deliverable: your MCP server

Goal: publish a tested MCP server with three tools, measured with a local model.

Theory 1/2: what makes it portfolio-worthy

A reviewer looks for: a README that says what it does and how to run it, tests that execute the tools (including the refused cases), a security section (what each tool can reach), and a measured result ("model X chose the right tool in 11 of 12 cases"). Version pins and a licence complete it.

Theory 2/2: the module in one picture

Prompt with schema → constrained answer → validation in code; tools described for the model → dispatched by your program within limits; the same tools exposed over MCP so any host can use them.

Practice (30 min)

1. Finish mcp_notes.py: three tools, environment-configured folder, tests for normal use, missing file, path escape and output cap.
2. Write docs/mcp-notes.md: what it does, how to run it with the Inspector and in one client, the security section, the tool-choice score from day 28.
3. Run all tests, commit, tag module-2.

With your AI: "Act as a reviewer for a junior AI engineer's portfolio. Here is the README and test list of my MCP server: [paste]. List up to five concrete gaps (missing test, unclear setup, unmeasured claim, security hole), each with the fix. Do not comment on style."

Let an agent do it: an agent can now check your deliverable from the outside: "Clone this repository into a temporary folder, follow docs/mcp-notes.md exactly, run the tests and the Inspector CLI, and report each step that failed or was unclear." Fix the documentation yourself from its report.

Recap (10 min)

Three lines: what you built, what you measured, what you would add. Redo the exercise of day 23 on call without notes.