How would you design an MCP server so agents use it well?

Summary

Design tools around the tasks agents perform rather than mirroring a REST API: filter and aggregate on the server, return small and relevant fields, paginate with cursors, give precise names, descriptions and schemas, return actionable errors, and annotate read-only and destructive tools.

Longer Answer

A thin list_customers() that returns 12,000 rows overflows the model's context; find_customers(city, has_overdue_invoices, limit, cursor) returns a page of three fields. Each response costs context tokens on every subsequent model call, so compactness matters more than for programmatic clients. Descriptions should say when to use and not use a tool. Annotations such as read_only_hint and destructive_hint let hosts auto-approve safe calls and ask before risky ones.

Key Points

• Task-shaped tools, not CRUD mirrors.
• Small outputs, pagination, server-side filtering.
• Clear schemas and actionable errors.
• Annotate read-only and destructive tools.

Deep dive: Designing MCP Servers Agents Use Well

What interviewers look for

Awareness that tool output consumes model context and drives cost and accuracy.

Follow-up questions

• How do you version tools without breaking agents?