Tonight, explained in plain English

A model is a text predictor. Everything useful comes from the code you wrap around it.

• An AI model (Claude, GPT, Llama, DeepSeek) reads text and predicts the next text. On its own it can't check a calendar, read a database, or click a button.
• A harness is the code around the model: it sends the prompt, reads the reply, and decides what happens next. Claude Code, Cursor, and goose are all harnesses.
• Model routing means picking the right-sized model for each job. A small, cheap model can sort or classify; save the big model for hard reasoning.

Your job is shifting from writing every line of code to writing the spec and checking the result.

• Complexity: break a big task into small, clear steps the model can't misread.
• Context: give the model exactly what it needs (what each input means, what's allowed, what isn't) and nothing more.
• Criticism: never trust the first answer. Test it, try to break it, and fix the spec when it fails.
• 'The spec is the product, the code is the receipt' means the valuable thinking lives in the description of what you want. Code can be regenerated; a good spec is what makes it right.

The model never runs your code. It asks your code to run a function, then reads the result.

• A tool is a normal function, like query_events(track, date). You describe it to the model: its name, what it does, and its inputs.
• When the model wants data, it doesn't answer yet. It replies with a request: 'please call query_events with track = Builders.'
• Your code runs the function, sends the result back, and asks the model again. Repeat until the model gives a final answer.
• That repeat-until-done while-loop is what people mean by an agent. It's about 20 lines of code.

1. Send the user's question + the list of tools
2. Model replies: a final answer, or a tool request
3. If it's a tool request, your code runs the function
4. Send the result back to the model
5. Go back to step 2 until there's a final answer

The tool description is the model's only instruction manual, so make wrong inputs impossible or clearly explained.

• Tools are described in JSON Schema: a list of inputs, their types, which are required, and a plain-English description of each.
• Use an enum (a fixed list of allowed values) whenever you can. If track can only be 'Builders' or 'Citizens', say so and the model can't invent 'builder-track'.
• When something goes wrong, never crash. Return a short error message that tells the model what to fix, like 'Unknown borough. Use one of: Bronx, Brooklyn, Manhattan, Queens, Staten Island.' The model reads it and tries again.

"name": "query_events"
"track": { "type": "string", "enum": ["Builders", "Citizens"] }
"date":  { "type": "string", "description": "YYYY-MM-DD" }
"required": ["track"]

LangChain, LangGraph, Strands, and the AI SDK all run the loop you just learned. They add convenience, not magic.

• Model-driven frameworks (like Strands) let the model decide the next step. Graph frameworks (like LangGraph) let you draw the steps in advance.
• Learn the raw loop first. When a framework breaks, knowing what's underneath is how you debug it.

MCP is a standard plug, like USB-C for tools. Wrap your function once and any MCP app can use it.

• Without MCP, you'd rewrite your tool's wiring for every app: once for Claude, again for Cursor, again for your own script.
• An MCP server is a small program that says 'here are my tools' in a standard format. server.py wraps the same query_events function with a few lines using FastMCP.
• An MCP client is any app that can plug servers in: goose, Claude Desktop, Claude Code, Cursor. You register the server once per client and its tools just show up.

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("events")
@mcp.tool()
def query_events(track: str, date: str | None = None): ...
mcp.run()

A tool is a capability. A Skill is the step-by-step playbook for a job that uses it.

• A Skill is a folder with a SKILL.md file: a short name and description at the top, then plain-English steps.
• The agent reads only the description until a task matches. Then it loads the full steps and follows them, like an employee pulling up the SOP.
• Example: an event-report Skill says 'call query_events for this week, group by track, and write a three-bullet summary.' The tool fetches data; the Skill says what to do with it.

---
name: event-report
description: Use when asked for a weekly events summary.
---
1. Call query_events for each track
2. Group results by date
3. Write three bullets, newest first

You build the whole stack on real NYC open data: a tool, the loop, an MCP server, and a Skill.

• Milestone 1, the loop: get the agent to call get_pumpkin_patches and answer with real NYC community gardens.
• Milestone 2, break it: ask about 'Astoria' and watch it fail. Add an enum and a helpful error so the agent fixes itself.
• Milestone 3, MCP: run src/server.py and plug it into goose (or Claude Desktop).
• Milestone 4, Skill: write a SKILL.md that turns the data into a Halloween garden report.
• Stuck? Stopping after Milestone 2 is fine. That's the core lesson. Finish the rest at home.