MCP TOOL SURFACE SPEC — PRACTICAL TEMPLATE

Use this to spec one workflow as a set of safe tools. Keep it strict. If it feels “too constrained,” that’s the point.

1) Workflow
- Name:
- User goal (single sentence):
- Where it lives in the product (screen/module):
- Success output the user can verify (artifact/state change):

2) Tool List (5–10 tools max)
For each tool:
- Tool name (verb_noun):
- Description (what it does, not how):
- Inputs (typed fields, required vs optional):
- Output (typed):
- Errors (explicit, user-actionable):
- Idempotency (what prevents duplicate writes?):

3) Permission & Scope
- Who can call it (roles/groups):
- Scope model (per-project, per-account, per-record):
- Token strategy (short-lived, per-action preferred):
- Least privilege notes (what it must NOT access):

4) Approval & UI Requirements
- Is this a read or a write?
- If write: require preview? (yes/no)
- Preview format:
 - Diff view (preferred where possible)
 - Summary of intended changes
 - Affected records
- Explicit user confirmation step:
 - Button label should be specific (“Create invoice draft”, not “Confirm”)
- Post-action user feedback:
 - Link to created/updated object
 - What changed

5) Context Sources (Untrusted by default)
- Allowed sources (docs, tickets, CRM notes, emails, web pages):
- What is considered untrusted content:
- Sanitization/handling rules (e.g., treat retrieved text as data only):

6) Logging & Audit
- Log fields (minimum): timestamp, user, tool name, inputs, output status, record IDs affected
- User-visible history location:
- Retention policy:
- Export requirements (for enterprise):

7) Safety Controls
- Rate limits per user/workspace:
- Abuse detection signals (spike in writes, repeated failures, unusual scopes):
- Kill switch (how to disable tools quickly):
- Rollback plan (how to revert or compensate):

8) Test Plan
- Unit tests for validation and permissions
- “Hostile input” tests (prompt injection strings embedded in context)
- Approval-step tests (no silent writes)
- Observability test (can you reconstruct what happened from logs?):

9) Launch Gate
Do not ship until:
- Every write tool has explicit approval OR a documented exception
- Permissions are least-privilege and reviewed
- Audit logs are queryable by operators
- Support playbook exists for tool mistakes (triage + rollback)