1
Curious builder0 XP earned · 300 to level 2
0 daysFinish a lesson to begin
Badge collection0 of 6 unlocked
51 small wins to finish your pathNext question →
How is designing tools for agents (the agent-computer interface) different from designing APIs for developers?
30-second answerSay your answer out loud first, then reveal.
API for developers vs tool for agents
| API for developers | Tool for agents |
|---|---|
Fine-grained endpoints (GET /users/{id}, GET /orders?user=) | Task-level tools (get_customer_overview(email)) |
| Docs read once | Description read every run, so it must be precise and concise |
| Returns everything; client filters | Return only what's useful; offer detail: "concise" | "full" |
| IDs (UUIDs) everywhere | Human-meaningful fields plus IDs; the model reasons better over names |
| Error codes | Instructive errors ("did you mean ...?") |
| Pagination via cursors | Sensible defaults and limits; tell the model how to get more |
| Strict input formats | Accept reasonable variants (dates), validate, explain |
Principles
- Design around workflows the agent performs, e.g.
schedule_meetingthat checks availability and books, instead oflist_calendars,get_free_busyandcreate_event. - Namespacing to separate similar tools (
asana_search,jira_search). - Token efficiency: truncation, filtering and summaries built in.
- Make the right thing easy: use enums; disallow dangerous parameter combinations.
- Iterate with evals: watch traces for where agents misuse tools, and improve descriptions. Agents can even help rewrite their own tool descriptions based on failure transcripts.
Interview soundbite: "Spend as much effort on the agent-computer interface as you would on a human UI."
Related
Every expert started right here.