Tool SDK Designer
Design tool specifications that AI agents can use reliably and safely.
Workflow
Tool Design Workflow
- Define the tool's purpose and scope (single responsibility)
- Select a specification format (XML, JSON Schema, or markdown)
- Define parameters with types, descriptions, constraints, and defaults
- Add safety classification (safe, moderate, dangerous)
- Implement error handling and recovery patterns
- Document examples with expected inputs and outputs
Tool Audit Workflow
- Extract all tool definitions from a system prompt
- Score each tool against the 6 quality indicators
- Flag tools without descriptions, types, or error handling
- Check MCP compatibility if cross-system use is planned
- Generate improvement recommendations
Specification Formats
Three formats for defining tools. Read references for templates.
| Format |
Best For |
Reference |
| XML |
Agents using XML response protocol (Replit, Devin) |
references/01-xml-format.md |
| JSON Schema |
OpenAI-style function calling, MCP tools |
references/02-json-schema-format.md |
| Markdown |
Documentation-first agents (Cursor, Windsurf) |
references/03-markdown-format.md |
Quality Indicators
Six indicators for a well-specified tool:
| # |
Indicator |
Description |
Weight |
| 1 |
Description |
Clear purpose statement |
20% |
| 2 |
Typed Parameters |
Each parameter has a type |
20% |
| 3 |
Required Fields |
Required vs optional is explicit |
15% |
| 4 |
Examples |
At least one input/output example |
15% |
| 5 |
Error Handling |
Failure modes documented |
15% |
| 6 |
Safety Flags |
Risk level and side effects noted |
15% |
Quality score = sum of weighted indicators (0-100%).
Tool Design Principles
- Single Responsibility — one tool, one action, no multi-purpose tools
- Descriptive Names —
search_codebase not search, write_file not write
- Typed Everything — every parameter has a type, every return has a schema
- Fail Loudly — errors include actionable messages, not silent nulls
- Idempotent When Possible — safe to retry without side effects
- Document Side Effects — if a tool modifies state, say so explicitly
Tool Composition
Read the reference for composition patterns.
| Pattern |
Description |
Reference |
| Sequential |
Output of tool A feeds input of tool B |
references/04-composition.md |
| Conditional |
Tool selection based on runtime conditions |
references/04-composition.md |
| Parallel |
Multiple tools invoked simultaneously |
references/04-composition.md |
| Fallback |
Alternative tool when primary fails |
references/04-composition.md |
MCP Compatibility
Read the reference for MCP interop requirements.
| Requirement |
Description |
Reference |
| Schema Format |
JSON Schema for parameters |
references/05-mcp-interop.md |
| Transport |
stdio, SSE, or HTTP |
references/05-mcp-interop.md |
| Discovery |
List tools endpoint |
references/05-mcp-interop.md |
Anti-Patterns
- God Tool — one tool that does everything via a "command" parameter
- Missing Types — parameters described in prose without formal types
- Silent Side Effects — tool modifies state but doesn't declare it
- No Error Contract — caller has no way to know what went wrong
- Prompt-Coupled — tool only works with one specific system prompt
Validation Scripts
Validate tool specifications with automated scoring (0-10):
python3 scripts/validate_toolspec.py <spec_file> [--strict]
Detects format (XML/JSON Schema/Markdown), extracts tool definitions, checks 6 quality indicators (description, parameters, examples, error handling, return types, safety flags), and flags anti-patterns (empty descriptions, any types, incomplete specs).
1---2name: tool-sdk-designer3description: Design production-grade tool specifications for AI agents. Use when defining tool interfaces, parameter schemas, safety flags, error handling, MCP compatibility, or tool composition rules. Covers three specification formats (XML, JSON Schema, markdown), 6 quality indicators, safety classification, error recovery patterns, and MCP interoperability. Based on analysis of 40+ tool specs from Cursor, Replit, Devin, Kimi, Windsurf, and the Model Context Protocol standard.4---56# Tool SDK Designer78Design tool specifications that AI agents can use reliably and safely.910## Workflow1112### Tool Design Workflow13141. Define the tool's purpose and scope (single responsibility)152. Select a specification format (XML, JSON Schema, or markdown)163. Define parameters with types, descriptions, constraints, and defaults174. Add safety classification (safe, moderate, dangerous)185. Implement error handling and recovery patterns196. Document examples with expected inputs and outputs2021### Tool Audit Workflow22231. Extract all tool definitions from a system prompt242. Score each tool against the 6 quality indicators253. Flag tools without descriptions, types, or error handling264. Check MCP compatibility if cross-system use is planned275. Generate improvement recommendations2829## Specification Formats3031Three formats for defining tools. Read references for templates.3233| Format | Best For | Reference |34|--------|---------|-----------|35| XML | Agents using XML response protocol (Replit, Devin) | `references/01-xml-format.md` |36| JSON Schema | OpenAI-style function calling, MCP tools | `references/02-json-schema-format.md` |37| Markdown | Documentation-first agents (Cursor, Windsurf) | `references/03-markdown-format.md` |3839## Quality Indicators4041Six indicators for a well-specified tool:4243| # | Indicator | Description | Weight |44|---|-----------|-------------|--------|45| 1 | Description | Clear purpose statement | 20% |46| 2 | Typed Parameters | Each parameter has a type | 20% |47| 3 | Required Fields | Required vs optional is explicit | 15% |48| 4 | Examples | At least one input/output example | 15% |49| 5 | Error Handling | Failure modes documented | 15% |50| 6 | Safety Flags | Risk level and side effects noted | 15% |5152Quality score = sum of weighted indicators (0-100%).5354## Tool Design Principles55561. **Single Responsibility** — one tool, one action, no multi-purpose tools572. **Descriptive Names** — `search_codebase` not `search`, `write_file` not `write`583. **Typed Everything** — every parameter has a type, every return has a schema594. **Fail Loudly** — errors include actionable messages, not silent nulls605. **Idempotent When Possible** — safe to retry without side effects616. **Document Side Effects** — if a tool modifies state, say so explicitly6263## Tool Composition6465Read the reference for composition patterns.6667| Pattern | Description | Reference |68|---------|------------|-----------|69| Sequential | Output of tool A feeds input of tool B | `references/04-composition.md` |70| Conditional | Tool selection based on runtime conditions | `references/04-composition.md` |71| Parallel | Multiple tools invoked simultaneously | `references/04-composition.md` |72| Fallback | Alternative tool when primary fails | `references/04-composition.md` |7374## MCP Compatibility7576Read the reference for MCP interop requirements.7778| Requirement | Description | Reference |79|-------------|------------|-----------|80| Schema Format | JSON Schema for parameters | `references/05-mcp-interop.md` |81| Transport | stdio, SSE, or HTTP | `references/05-mcp-interop.md` |82| Discovery | List tools endpoint | `references/05-mcp-interop.md` |8384## Anti-Patterns8586- **God Tool** — one tool that does everything via a "command" parameter87- **Missing Types** — parameters described in prose without formal types88- **Silent Side Effects** — tool modifies state but doesn't declare it89- **No Error Contract** — caller has no way to know what went wrong90- **Prompt-Coupled** — tool only works with one specific system prompt9192## Validation Scripts9394Validate tool specifications with automated scoring (0-10):9596```bash97python3 scripts/validate_toolspec.py <spec_file> [--strict]98```99100Detects format (XML/JSON Schema/Markdown), extracts tool definitions, checks 6 quality indicators (description, parameters, examples, error handling, return types, safety flags), and flags anti-patterns (empty descriptions, `any` types, incomplete specs).
saifyxpro