| name | agentic-interface-design |
| description | Interface design for the model as consumer: MCP tools, function-calling schemas, A2A contracts (Agent Cards). Human-vs-agent ergonomics, tool naming, error grammar, fat-vs-thin decomposition, progressive disclosure (lazy loading), idempotency (request_id), response pagination (next_cursor, has_more), JSON-schema craft. Triggers: designing/reviewing MCP tools, tool descriptions, function-calling schemas, agent error ergonomics, A2A contracts. Not for web/CLI (web-ui-design, tui-design) or REST/GraphQL quality (api-design-craft).
|
| allowed-tools | ["Read","Glob","Grep","Bash"] |
| compatibility | Claude Code |
| staleness_sensitive_sections | ["The Token Economy Problem","A2A Contract Design"] |
Agentic Interface Design
Interface design craft for one specific consumer: the language model. When the consumer is a model rather than a human, the ergonomics of the interface change fundamentally — and most API design instincts don't transfer.
Start with the shared canon in references/design-fundamentals.md — the Bloch principles apply directly here (minimal surface area, names matter, hard-to-misuse, fail-fast). Then apply the agentic-specific lens this skill provides.
Satellite files (loaded on-demand):
- references/design-fundamentals.md -- durable design canon (Rams, Norman, Nielsen, Bloch) — the first-principles foundation
- references/tool-design-for-models.md -- tool naming, description writing, parameter naming, granularity decisions
- references/mcp-primitives-as-design-surfaces.md -- when to use tool vs resource vs prompt; the do-not-mix rule
- references/agent-error-ergonomics.md -- error grammar, idempotency patterns, Stripe-style request_id
- references/progressive-disclosure-of-tools.md -- token economy problem, meta-tool pattern, domain bundles, 85–100× reduction
- references/agent-contracts.md -- JSON-schema design, response structure, pagination, A2A contracts
- references/design-review-checklist.md -- audit checklist for MCP servers, tool surfaces, A2A contracts
The Central Principle: Names and Descriptions ARE the Interface
A human reads documentation once and builds a mental model. A model reads the tool name and description on every single call, re-reasons over them each time, and cannot accumulate domain knowledge across sessions. The description is not documentation — it is the executable interface. It is the primary lever for correcting model behavior.
Consequence: a description change fixes broken model behavior. This is not a metaphor. When Anthropic's web search tool was causing Claude to append "2025" to queries, the fix was a description update, not a code change. The description told the model to stop, and it stopped.
Write tool descriptions as if onboarding a new team member who has never seen the system. Include what the tool does, what it does NOT do, its preconditions, and what the return value means.
Human-vs-Agent Ergonomics
The design decisions that follow from this distinction are not obvious without a side-by-side comparison:
| Dimension | Human consumer | Agent (LLM) consumer |
|---|
| Learning | Reads docs once; builds mental model | Re-reads description every invocation; no persistent learning |
| Error handling | Reads message, searches docs, asks for help | Must self-recover from the error alone, in the same turn |
| Context budget | Unlimited working memory | Fixed window; large responses displace reasoning tokens |
| Discovery | Browses API reference, tries curl | Works only with what is in its context at call time |
| Consistency | Prefers consistency | Inconsistency causes tool selection failures |
| Response size | Bigger is often more helpful | Smaller is better; paginate aggressively |
Fat Tool vs. Many Thin Tools
LLM decision quality degrades measurably when presented with more than ~20–25 tools at once. Two design philosophies address this at the decomposition level:
Consolidate (fat tool) when the agent would almost always call the tools in sequence with no intermediate reasoning. schedule_meeting(participants, time, duration, title) combines availability check, conflict resolution, and creation in one call. Reduces round-trips and keeps the tool count down.
Keep separate (thin tools) when the agent needs to branch based on intermediate results. check_availability, create_event, send_invite can be combined or omitted depending on what check_availability returns.
Decision rule: if the steps always occur together and the combined semantics are clear → fat tool. If the agent might do step A without step B → thin tools.
Progressive Disclosure of Tools
Token cost of tool schemas is significant. Production benchmarks:
- A typical 400-tool enterprise MCP server consumes >400K tokens in schema definitions alone — exceeding a 200K context window.
- LLM decision quality degrades measurably past ~20–25 tools presented at once.
- Lazy schema loading (serve schemas on demand) achieves 85–100× token reduction while maintaining selection accuracy.
If the surface has more than ~20 tools, it needs progressive disclosure. No exceptions. See references/progressive-disclosure-of-tools.md for patterns.
Agent Error Grammar
Errors must be actionable by the model in the same turn with no human intervention:
"Column 'user_id' not found in table 'orders'.
Available columns: id, order_id, customer_id, created_at."
The grammar: X failed because Y. To fix this: Z.
Never: a stack trace. Never: an error code alone. Never: "Internal server error." The model needs to know what to try next with the information currently in its context window. See references/agent-error-ergonomics.md for full patterns.
Tool Result Pagination Rules
Paginate every list tool result. The model's context window is a shared resource:
- Default page size: 10–20 items (not 100, not unlimited)
- Always include:
next_cursor (or next_page_token), total_count, has_more
- Return only what the agent needs for the next step — verbose results displace reasoning tokens
When to Reach for Which Reference
| Task | Reference file |
|---|
| Tool naming, description writing, parameter naming | tool-design-for-models.md |
| Deciding which MCP primitive (tool/resource/prompt) | mcp-primitives-as-design-surfaces.md |
| Error design, idempotency for retries | agent-error-ergonomics.md |
| Progressive disclosure, token economy | progressive-disclosure-of-tools.md |
| JSON-schema design, response structure, A2A contracts | agent-contracts.md |
| Reviewing an existing tool surface or MCP server | design-review-checklist.md |
| Shared design principles (Bloch, Rams, Nielsen) | design-fundamentals.md |
Related Skills
api-design-craft — the same taste/quality lens applied to REST/GraphQL/gRPC APIs; when an interface serves both human and model consumers, both skills apply.mcp-crafting — MCP server construction (FastMCP, transport config, Inspector testing); this skill covers design quality, mcp-crafting covers how to build it.agentic-sdks — wiring tools to the agent loop, framework selection, multi-agent orchestration; this skill covers design craft, agentic-sdks covers SDK mechanics.communicating-agents — Agent Card structure, A2A task lifecycle, interaction patterns; this skill covers contract design, communicating-agents covers protocol mechanics.llm-prompt-engineering — when a tool description is long enough to be a mini-prompt (few-shot examples, chain-of-thought cues).api-documentation — documenting an existing MCP server (render the tool catalog from live tools/list, surface schemas + annotations + error modes); this skill owns tool design, that one owns the doc artifact.
