Topic 3: Descriptions as prompts
Writing for the model, not for a developer
A tool description is a prompt: text the model reads, every turn, to decide what to do. It is not a docstring for a colleague who can open the source. A developer reading Runs NoteStore.search over the markdown corpus learns something useful. A model learns nothing about when to pick this tool over another.
Compare the two styles on the same tool:
| Question the model needs answered | Developer-facing description | Model-facing description |
|---|---|---|
| What does it do? | "Runs NoteStore.search over the markdown corpus and returns ranked hits." | "Search the user's research notes by keyword and return the best matching notes." |
| When should I use it? | (not said) | "Use this first for any question about what the user has written down." |
| What do I do with the result? | (not said) | "Each hit has a uri; read it with the notes resource to see the full note." |
| What does an empty result mean? | (not said) | "Returns an empty list when nothing matches, which means the notes do not cover the topic." |
| Any side effects or limits? | (not said) | For create_note: "Only call this when the user explicitly asks... Never overwrites." |
A checklist that works for most tools: say what it does in the user's words; say when to use it and, if another tool is close, when not to; say what comes back and what empty or partial results mean; say what it changes and what it refuses to do. Put argument-specific guidance in Field(description=...) next to the argument, with an example value, because models copy examples.
Descriptions also shape behavior after the call. The sentence about empty results is what lets the course host abstain ("I could not find this in your notes.") instead of inventing an answer.