// Before you start
This guide builds on this one:
This is the lesson where it comes together. You will write one file that does everything from lesson 1: a model, a loop and a tool. Read the code first, then we go through it piece by piece.
Give it something to look at#
The agent needs notes to search. A short list in the file is plenty for now; later you could swap it for files or a database without touching the loop.
Describe the tool, then write it#
A tool has two halves. The description is what the model sees: a name, a plain sentence about what it does, and the shape of its input. The function is your own code, which the model never sees.
Write the description as if you were explaining the tool to a new colleague. A vague description is the most common reason an agent picks the wrong tool, or searches with a whole sentence instead of keywords.
Tip
Put guidance in the description, not only in the prompt. "A few keywords, not a full sentence" next to the query field changes how the model fills it in.
Write the loop#
Save this as agent.ts (or the Python version as agent.py). Notice the three things that keep it honest: it stops when the model stops asking for tools, it caps the number of steps, and it never lets the model run anything directly.
TypeScript
import Anthropic from '@anthropic-ai/sdk'const client = new Anthropic()const MODEL = 'claude-sonnet-5-5'const MAX_STEPS = 6const SYSTEM = "You answer questions using the user's notes. Search the notes before you answer. " + 'If the notes do not contain the answer, say so instead of guessing.'const notes = [ { id: 1, title: 'Team standup', text: 'Standup moved to 9:30 on Mondays. Priya runs it.' }, { id: 2, title: 'Launch checklist', text: 'Before launch: run the tests, check the contact form, update the sitemap.' }, { id: 3, title: 'Book list', text: 'To read: The Pragmatic Programmer, Designing Data-Intensive Applications.' },]// The tool itself is plain code. The model never sees this function, only its description.function searchNotes(query: string) { const words = query.toLowerCase().split(/\s+/).filter(Boolean) return notes .filter((note) => words.some((word) => `${note.title} ${note.text}`.toLowerCase().includes(word))) .slice(0, 3)}const tools: Anthropic.Tool[] = [ { name: 'search_notes', description: "Search the user's notes. Returns up to 3 notes whose title or text contains any of the words in the query.", input_schema: { type: 'object', properties: { query: { type: 'string', description: 'A few keywords, not a full sentence.' }, }, required: ['query'], }, },]export async function ask(question: string) { const messages: Anthropic.MessageParam[] = [{ role: 'user', content: question }] for (let step = 0; step < MAX_STEPS; step++) { const response = await client.messages.create({ model: MODEL, max_tokens: 1024, system: SYSTEM, tools, messages, }) // No tool request means the model has its answer. if (response.stop_reason !== 'tool_use') { const text = response.content.find((block) => block.type === 'text') return text?.type === 'text' ? text.text : '(no answer)' } // Keep the model's turn in the history, then answer each tool request. messages.push({ role: 'assistant', content: response.content }) const results: Anthropic.ToolResultBlockParam[] = [] for (const block of response.content) { if (block.type !== 'tool_use') continue const { query } = block.input as { query: string } console.log(`step ${step + 1}: search_notes("${query}")`) results.push({ type: 'tool_result', tool_use_id: block.id, content: JSON.stringify(searchNotes(query)), }) } messages.push({ role: 'user', content: results }) } throw new Error(`Gave up after ${MAX_STEPS} steps`)}Python
import jsonimport anthropicclient = anthropic.Anthropic() # reads ANTHROPIC_API_KEY from your environmentMODEL = "claude-sonnet-5-5"MAX_STEPS = 6SYSTEM = ( "You answer questions using the user's notes. Search the notes before you answer. " "If the notes do not contain the answer, say so instead of guessing.")NOTES = [ {"id": 1, "title": "Team standup", "text": "Standup moved to 9:30 on Mondays. Priya runs it."}, {"id": 2, "title": "Launch checklist", "text": "Before launch: run the tests, check the contact form, update the sitemap."}, {"id": 3, "title": "Book list", "text": "To read: The Pragmatic Programmer, Designing Data-Intensive Applications."},]# The tool itself is plain code. The model never sees this function, only its description.def search_notes(query): words = query.lower().split() found = [n for n in NOTES if any(w in (n["title"] + " " + n["text"]).lower() for w in words)] return found[:3]TOOLS = [ { "name": "search_notes", "description": "Search the user's notes. Returns up to 3 notes whose title or text contains any of the words in the query.", "input_schema": { "type": "object", "properties": {"query": {"type": "string", "description": "A few keywords, not a full sentence."}}, "required": ["query"], }, }]def ask(question): messages = [{"role": "user", "content": question}] for step in range(MAX_STEPS): response = client.messages.create( model=MODEL, max_tokens=1024, system=SYSTEM, tools=TOOLS, messages=messages ) # No tool request means the model has its answer. if response.stop_reason != "tool_use": return next((b.text for b in response.content if b.type == "text"), "(no answer)") # Keep the model's turn in the history, then answer each tool request. messages.append({"role": "assistant", "content": response.content}) results = [] for block in response.content: if block.type == "tool_use": query = block.input["query"] print(f'step {step + 1}: search_notes("{query}")') results.append( {"type": "tool_result", "tool_use_id": block.id, "content": json.dumps(search_notes(query))} ) messages.append({"role": "user", "content": results}) raise RuntimeError(f"Gave up after {MAX_STEPS} steps")if __name__ == "__main__": print(ask("When is standup, and who runs it?"))Run it and read the trace#
For TypeScript, add a tiny run.ts that calls the function with a question from the command line:
import { ask } from './agent.ts'const question = process.argv[2] ?? 'When is standup, and who runs it?'console.log(await ask(question))Then run npx tsx run.ts "When is standup, and who runs it?". You should see one or two lines like step 1: search_notes("standup") followed by an answer that mentions 9:30 and Priya. Those lines are your trace: the agent's own account of what it did.
Paste it as the SYSTEM text in agent.ts. Change the highlighted part to suit you.
Why the step limit matters#
Without MAX_STEPS, a confused model can keep calling the same tool forever, and you pay for every round. A limit turns an unbounded failure into a clear error you can read. Six is generous for a one-tool agent; start low and raise it only when a real task needs it.
// Try it
Add a second tool
Give the agent a way to list the titles of all the notes, so it can answer "what notes do I have?".
- Write a
listNotesfunction that returns the title of every note. - Add a
list_notesentry to the tools list with a clear description and no inputs. - Handle it inside the loop, next to
search_notes. - Ask: "What notes do I have?" and check the trace.
Show a solutionHide the solution
// Solution
The description is the important part. The loop only needs one new branch.
const listNotes = () => notes.map((note) => note.title)// in the tools list:{ name: 'list_notes', description: 'List the titles of every note the user has. Use it when they ask what notes exist.', input_schema: { type: 'object', properties: {} },},// in the loop, replacing the single search_notes handling:const output = block.name === 'list_notes' ? listNotes() : searchNotes((block.input as { query: string }).query)results.push({ type: 'tool_result', tool_use_id: block.id, content: JSON.stringify(output) })