菜单
Design an MCP server tool surface for an AI agent. Starts from common workflows, derives tool schemas, audits for completeness and safety. Use when designing a new MCP server or redesigning an existing one.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/agentydragon/ducktape --skill mcp-design命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | mcp-design |
| description | Design an MCP server tool surface for an AI agent. Starts from common workflows, derives tool schemas, audits for completeness and safety. Use when designing a new MCP server or redesigning an existing one. |
| argument-hint | [path to MCP server code or service being wrapped] |
Design or redesign the tool surface of an MCP server for AI agent use. The goal is a tool surface that is hard to misuse, natural for common workflows, and covers the full API of the service being wrapped.
Argument: $ARGUMENTS (path to MCP server code or description of
the service being wrapped)
Before starting, familiarize yourself with these:
Key takeaways from these resources:
Apply these throughout the design process:
If the agent omits something important, that should be an error — not a silent default. Validate inputs early. Use enums/Literal types for constrained values. Require explicit values for anything safety-critical (e.g., location when managing multi-location inventory, unit when dealing with quantities).
Common API footguns to watch for:
null meaning both "unchanged" and "clear this field"
in partial updates. Use a separate clear_fields: set[FieldEnum]
parameter for nullable fields.int | str where int=ID, str=name.The number of tool calls for a routine operation should be small. But consolidation must not come at the cost of safety — a single call that does too much implicitly is worse than two explicit calls.
Each tool description must answer:
Do NOT describe implementation details ("sends POST to /api/foo concurrently"). DO describe the agent-facing behavior.
detail: "brief" | "full" when
both overview and deep-dive use cases exist.days_until_expiry
instead of making the agent do date math).Accept int | str for entity references: int = ID, str = resolved by
name. Error on not-found with suggestions. Check whether the underlying
service enforces unique names — if so, resolution is unambiguous.
Every request and response involving quantities must name the unit. Never assume the agent (or user) knows what unit a number is in.
Every error should name what's wrong, suggest the fix, and list available options. The agent should be able to recover in one retry without a separate lookup call.
Do NOT start from the API endpoints. Start from user workflows — what will an agent actually be asked to do?
For each workflow:
Structure the design doc around these workflow scenarios. Example scenarios to consider (adapt to your domain):
From the workflow scenarios, derive the tool inventory:
Group related operations. Don't create create_foo, create_bar,
create_baz when a single create_entity(type, ...) works. But DO
create dedicated tools for complex entities that benefit from typed
schemas and validation.
Define input schemas using Pydantic models. Use:
int | str for entity references (ID or name)Literal / StrEnum for constrained valuesField(description=...) for every non-obvious parametermodel_validator for cross-field constraintsDefine output schemas. Use discriminated unions for results:
{kind: "ok", ...} | {kind: "error", error: str}. Always include
names alongside IDs. Keep responses compact.
Decide batch vs single. Batch tools (accept list[Item]) are
good for operations the agent often does N times. Each item succeeds
or fails independently. Single-item tools are fine for rare operations.
Systematically check that the tool surface is complete:
Schema field coverage: for each tool, check that input/output fields cover the important fields in the underlying service. Don't expose every field — but don't miss the ones that matter for common workflows.
Impossible operations: walk through the full API surface of the underlying service. Is there any common operation that's impossible with the proposed tools, even via escape hatches (generic CRUD)?
Data model coverage: for each entity type in the service, check: can you create it? Read it? Update it? Delete it? If not via a dedicated tool, via the generic escape hatch?
Partial update safety: for every "edit" tool, verify that omitting
a field means "keep unchanged", not "set to null". If some fields can
legitimately be cleared, use clear_fields: set[FieldEnum].
Conversion/validation: if the service has unit conversions, permission checks, or other validation that the agent might trigger, check that the MCP server handles it gracefully (server-side conversion, clear errors) rather than passing through opaque failures.
Check each tool against these antipatterns:
For each tool, write the description the agent will see. This is not the implementation docstring — it's the agent's instruction manual.
Template:
[What this tool does in one sentence.]
[When to use it — and when NOT to (use X instead).]
[What the response looks like — key fields and their meaning.]
[Common pitfalls: required fields, constraints, error cases.]
Test: could an agent that has never seen this service before use the tool correctly on its first try, given only the description and schema?
When the underlying service has a well-designed OpenAPI spec:
Strip output_schema from OpenAPI-generated tools if the service's
response schemas are unreliable. E2e tests are the real contract.
The design process should produce:
Design doc (docs/agent_interaction_design.md or similar):
Tool inventory with for each tool:
Audit checklist confirming: