Module 2 · Designing servers agents use well · Lesson 3

Designing tools, not endpoints

Turn an endpoint-per-tool server into a few task-shaped tools a model uses well, with names, schemas, structured results, errors and annotations designed for a reader that decides at run time.

60 min 2 videos 3 exercises 8-question quiz Answers

Setup for the exercises:Install Claude Code Node.js, pnpm and TypeScript MCP servers in Claude Code The Larchmere Desk mock API

By the end of this lesson you can

Redesign an endpoint-per-tool server into task-shaped tools by consolidating reads and splitting writes by their consequence
Write names, descriptions, server instructions and input schemas around what a model knows when it makes a call
Return compact structured results, and weigh what an output schema adds to the definitions against what it buys
Turn failures into protocol errors or tool execution errors whose text tells a model how to recover
Choose tool annotations by comparison with HTTP's safe and idempotent methods, and explain why they stay hints

The naive server from MCP and REST: two mental models gives an agent fourteen tools, one per Desk endpoint, each answering with Desk's raw JSON. To learn whether Orrin & Vale's stuck sync is a known incident, the model has to find the customer's id, list their tickets and fetch the incident, reading 1.3 KB representations full of _links on the way. To leave a note, it has to choose which member of staff the note claims to be from. None of this is wrong as REST. It is wrong for a reader who chooses actions at run time, from text, and pays for every character. This lesson redesigns the server for that reader: seven tools instead of fourteen, and the reasoning behind each one.

Designing tools, not endpoints

Turn an endpoint-per-tool server into a few task-shaped tools a model uses well, with names, schemas, structured results, errors and annotations designed for a reader that decides at run time.

Designing tools, not endpoints

Designing tools, not endpoints

Sign in to keep reading.

Sign in to keep reading.