An MCP tool specification should document one user job, when the model should and should not call it, permissions, bounded inputs, a compact output, failure behavior, risk and confirmation requirements, and a held-out evaluation set. Copy the worksheet below into design review.
Purpose and selection
Tool name: [namespace].[verb]_[object]
User job: The user is trying to…
Use when: Call this tool when…
Do not use when: Do not call it for…
Nearest competing tool: … The distinction is…
Write in task language. A model choosing among tools needs sharper boundaries than a developer browsing API docs.
Inputs and policy
Required inputs: type, range, example
Optional inputs: default and effect
Caller identity: user and workspace resolution
Permissions: exact scopes and object checks
Validation: size, format, allowlist, injection controls
Output and errors
Result: smallest fields needed next
Provenance: source ID, title, location, time
Budget: default/max result count and tokens
Pagination: cursor behavior
Empty result: explicit response and refinement
Safe errors: actionable without secrets
Use progressive disclosure. See the token guide.
Risk and evaluation
Read/write and side effect: …
Confirmation: required before…
Idempotency/rollback: …
Audit: actor, tool, target, outcome
Evaluation: 10 normal, 5 ambiguous, 5 adversarial prompts
Pass: selection, arguments, policy, usefulness
Annotations are hints, not enforcement. Read the full tool design guide for rationale.
Built for the next step
Compare the worksheet with a live surface
SPYN3’s endpoint starts agents on a few navigation tools and reveals each source’s tools on demand.
Review SPYN3 toolsSPYN3 is a consolidated MCP layer: one hosted endpoint in front of every system you connect — MCP servers, Postgres, REST APIs, Google Drive — with tools foldered by source and read/write permissions per key. Switching agents means moving one URL. Free plan available; current capabilities are documented on the product facts page.
Sources
- Anthropic: writing effective tools for agents — namespacing, response design and tool evaluations. Verified 13 Sep 2026
- MCP specification: tools — tool discovery, invocation and security considerations. Verified 13 Sep 2026
- MCP project: tool annotations — risk hints and their enforcement limits. Verified 13 Sep 2026