Module 3 — Tool design: the API contract for models
Prompt & Tool Design for .NET Teams · Part 1 — Fundamentals · Module 3 of 12
This is the one. If the course had a single takeaway, it would be this module. A tool definition is just an API — the agreed contract for how one piece of software asks another to do something — except here the consumer is a model that read your description exactly once, took it completely literally, and will never raise a clarifying ticket.
Objective
Learn what makes a tool definition good. The model sees only your name, your description, and your JSON schema (a precise description of the data’s shape). It cannot read the implementation, it cannot ask what you meant, and it will not give you the benefit of the doubt.
Read (~12 min)
- Anthropic’s tool-use guide, especially the concepts and best-practices section.
- AWS Converse API tool use.
Key principles
- Tool descriptions are prompts. Write them like docs for a sharp but painfully literal junior dev who will never ask a follow-up question.
- Fewer, well-scoped tools beat many overlapping ones. Two tools that do almost the same thing are two tools the model can pick wrongly.
- Return errors as text the model can recover from, not stack traces.
No comic found for that topic; try a broader keyword like "deployment"is worth more to the model than a 500 and a wall of red. - Schema constraints are cheaper than prose. An
enumor arequiredfield enforces what a paragraph of careful instructions only suggests.
Lab (~18 min)
No code yet. Design tool definitions for a small, self-contained example — a tech-comic finder, say, returning a relevant strip from xkcd, CommitStrip, or MonkeyUser — writing the name, description, JSON input schema, and example output for two or three operations (find a comic by topic, fetch a random one), as if you were handing them to a model. Then peer-review in pairs with one question in mind: could a literal-minded stranger misuse this? Commit as module-03/tool-contracts.md.
This is the peer review worth slowing down for. It’s also where someone discovers your “obvious” parameter name meant something different to everyone in the room.
Done when
Your reviewer can predict exactly when the model would call each tool, and with what arguments, from the definition alone. If they have to ask “what does this one do?”, so would the model, and the model would guess rather than ask.