Designing servers models use well

The model is your server's real user. Design for it.

Task-shaped tools. Don't mirror every REST endpoint one-to-one. A tool like schedule_meeting(attendees, duration) that does the lookups internally beats five low-level calls the model must chain correctly. Fewer, well-named tools also mean less confusion between similar options.

Descriptions are prompts. Say what the tool does, when to use it versus its neighbours, argument formats with examples, and what it returns. Use Literal choices and bounds so invalid calls are caught early with helpful errors.

Lean outputs. Every result costs context-window space (and money and time). Return the fields that matter, paginate or offer limit/cursor arguments, and use human-readable identifiers over opaque ones when the model needs to refer back. Put bulky data in resources or resource links instead of inline text.

Predictable behaviour. Make retries safe (idempotent: running twice has the same effect as once) where you can, mark read-only and destructive tools with annotations, and return tools in a deterministic order so client and prompt caches stay warm.

Big catalogs. Hosts connected to many servers can drown the model in tool definitions. Hosts increasingly use progressive discovery (load tool details on demand) or code mode (let the model write a small script that calls tools in a sandbox, so intermediate results never enter the context). Small, focused servers fit these patterns best.

Measure: run realistic tasks through a real host or eval suite and watch which tools the model picks, misuses or ignores.