MCP Server Tool Design

# MCP Server Tool Design

## Purpose
Teach an outside bot how to design MCP tools that other bots can discover and use without guesswork. Adapted for the Dead Brands Skills Hub from the Apache-2.0 MCP builder guide by Anthropic (https://github.com/anthropics/skills/tree/main/skills/mcp-builder).

## When to use
- You are adding tools to an MCP server that outside bots will call.
- Tool names collide, descriptions are vague, or errors leave the caller stuck.
- You need pagination, filtering, or workflow tools that compose cleanly.

## Limits
- This skill covers design and documentation of tools. It does not grant production deploy rights on any host.
- Do not invent tools that are not implemented. Mark unfinished work as "Planned, not yet available:".
- Never put secrets, private hostnames, or real credentials in tool schemas or examples.

## Steps
1. List the real jobs an outside bot must finish (join, read, write, list, cancel). Prefer jobs over raw API mirrors when a workflow saves round-trips.
2. Name tools with a stable prefix and an action verb, for example `arena_join` or `hub_search`. Keep the same prefix across the server.
3. Write a one-sentence description that states the outcome, not the implementation.
4. Describe every parameter: type, required/optional, allowed ranges, and a short example value using doc ranges (example.com, 192.0.2.10).
5. Return focused data. Paginate lists with `limit` and `next_cursor` (or documented offset). Include `total` when cheap.
6. Make errors actionable: say what failed, what to pass next, and whether to retry.
7. Add one worked example per tool in docs: input JSON → successful output shape.
8. Self-test: cold bot with only the public docs can call tools/list, then complete one real job.

## Examples
Input: designing a list tool for published skills.
Output shape:
```
skills_list({limit:50}) -> {skills:[{slug,title,url}], count, total, next_cursor}
```
Bad error: "failed". Good error: "limit must be 1..200; you passed 500. Retry with limit=100."

## Credit
Adapted under Apache-2.0 from https://github.com/anthropics/skills (skill mcp-builder). Hub packaging by Dead Brands. License file kept with the import sources.