MCP Tool Generator

Purpose

Design MCP tools: input/output schemas, handler logic outline, idempotency rules, and agent-facing descriptions for reliable tool invocation.

Input: Server scope, tool use cases, underlying API capabilities, safety constraints
Output: MCP Tool Design Document per tool with JSON Schema, description, examples, and edge case handling Examples: See examples.md for worked input/output.

Workflow

Step 1: Identify tool candidates

Map agent tasks to tool operations:

Prefer read-only tools first; defer destructive operations until security review.

Step 2: Define tool contract

Per tool document:

Step 3: Design input schema

{
  "type": "object",
  "properties": {
    "query": { "type": "string", "description": "Search query, max 500 chars" },
    "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }
  },
  "required": ["query"]
}

Rules:

• Constrain string lengths and array sizes
• Use enums for fixed option sets
• Mark destructive tools explicitly in description

Step 4: Design output format

Return structured JSON text content:

Keep responses token-efficient; paginate large results.

Step 5: Handle edge cases

Step 6: Validate

Run Validation checklist.

Decision Rules

Validation

• Each tool has snake_case name following verb_noun pattern
• Description states when to use and when not to use
• Input JSON Schema with required fields and constraints
• Output structure documented with success/error paths
• Edge cases: empty, rate limit, invalid args covered
• Destructive tools have confirmation mechanism
• ≥2 example invocations per tool (happy path + edge case)
• Token-efficient response design (pagination for lists)

Anti-patterns

• Vague description — "helps with data" without specifying inputs/outputs.
• God tool — single tool with 15 optional parameters covering unrelated actions.
• Raw API passthrough — exposing entire REST API without agent-friendly shaping.
• Unbounded results — returning thousands of records without pagination.
• Silent destructive ops — delete without confirmation arg or annotation.

Best Practices

• One tool = one clear action; compose complex flows in agent workflow.
• Description written for LLM tool selection (include negative cases).
• Validate inputs in handler before external API call.
• Return consistent error schema across all tools.
• Pair with mcp-security-review before enabling write tools.

Output Structure

# MCP Tool Design: [Server Name]

## Tool: `tool_name`

### Description
[Agent-facing description with use/when-not-use]

### Input Schema
```json
{ ... }

Output Schema

{ ... }

Examples

Happy path

Input: ... Output: ...

Edge case

Input: ... Output: ...

Edge Case Handling

Risk Level

[Low / Medium / High]

---

# Next Skills

| Outcome | Recommended Skill |
|---------|-------------------|
| Implement server scaffold | `mcp/mcp-server-generator` |
| Security review for write tools | `mcp/mcp-security-review` |
| Client invocation patterns | `mcp/mcp-client-generator` |
| Production hardening | `mcp/mcp-best-practices` |
| Workflow orchestration | `ai/ai-workflow-builder` |