| name | tool-spec |
| description | Draft an MCP tool specification for an mangrove-agent extension. Use when the user asks to "draft an MCP tool", "spec out a new tool", "add a tool for X", or "/tool-spec <purpose>". Produces a JSON-schema-shaped spec that matches the mangrove-agent service-layer pattern and auth-tier conventions, ready to paste into `server/src/mcp/tools.py`. Adapted from the Mangrove workspace `tool-spec` skill with mangrove-agent conventions. |
| user_invocable | true |
| argument-hint | <tool name and purpose> |
Draft MCP Tool Specification
Parse $ARGUMENTS as a natural-language description of the tool you want to add (no project prefix — this skill is scoped to mangrove-agent).
Produce a complete MCP tool specification following the conventions already in server/src/mcp/tools.py and the service-layer pattern documented in docs/contributing.md and CLAUDE.md.
Output sections
1. Tool name
Lowercase snake_case. No prefix (the MCP server is single-tenant; all tools live under mcp__mangrove-agent__*). Match existing patterns: get_balances, create_strategy_autonomous, list_trades, evaluate_strategy.
2. Access tier
Pick one:
- free — no API key required. Reserve for
status, list_tools, read-only discovery endpoints that can't leak wallet/strategy data.
- auth — requires
api_key param matching API_KEYS in config. Default tier for everything else.
- x402 — payment-gated via the x402 protocol. Currently demo-only (
hello_mangrove). Add this tier only on explicit product decision.
3. Description
One sentence. Match the tone of existing tool descriptions — direct, imperative, and it should state any guard or precondition ("Requires backup-confirmed wallet", "Paper mode only", etc.).
4. Parameters
For each parameter give: name, type, required, description. Standard patterns:
api_key: str = "" is always last in the param list and required when access != free.- Addresses use
str with the natural 0x-prefixed hex convention; chain_id uses int.
- Slippage / fee params are
float in decimal form (0.002 = 0.2%), with the cap in the description.
- Token params accept either symbol or contract address (document which is preferred for the route).
5. Service-layer function
Every MCP tool calls into a function in server/src/services/<resource>.py. Give the function signature the tool will call — the service layer owns the business logic, the tool layer only authenticates + marshals.
6. Response shape
JSON dict with explicit keys. Never return raw model objects without .model_dump(mode="json"). Never return encrypted secrets, Fernet ciphertext, or plaintext key material (the signing guard blocks that at the wallet layer, but your tool should not be a bypass).
7. Error shape
Match the existing error envelope:
{"error": true, "code": "ERROR_CODE", "message": "human-readable", "suggestion": "what to try", "correlation_id": "<uuid>"}
Standard codes: AUTH_INVALID_API_KEY, CHAIN_NOT_SUPPORTED_IN_V1, WALLET_NOT_FOUND, SDK_ERROR, VALIDATION_ERROR.
8. Example invocation + response
One positive example with realistic values (e.g. a real Base contract address, a non-zero amount). Helps the implementer quickly validate shape.
Safety-layer reminders
When drafting tools that touch signing, wallets, or execution, state explicitly in the spec's description / preconditions:
- Signing flows MUST route through
wallet_manager.sign() — the hard guard there refuses non-1inch payloads (see .claude/rules/wallet-presentation.md).
- New tools that take a wallet address MUST check
backup_confirmed_at before executing anything that moves real funds.
- New tools that take a chain_id MUST default to Base Sepolia (84532); mainnet (8453) requires an explicit user signal.
Output
Do NOT create any files. Output the spec as markdown with a JSON schema block for parameter + response + error, ready for review or paste into server/src/mcp/tools.py. End with a checklist:
[ ] Service-layer function exists in server/src/services/<resource>.py
[ ] Pydantic models for request + response defined
[ ] Route added to server/src/api/routes/<resource>.py (auth dependency wired)
[ ] Route registered in server/src/api/router.py
[ ] MCP tool registered in server/src/mcp/tools.py via register_tool()
[ ] Tests added in server/tests/unit/ and/or server/tests/integration/
[ ] Documentation updated (CLAUDE.md if user-facing, docs/contributing.md if dev-facing)
