tool-spec
Skill8 starsChanged 14 days agoMITView on GitHub
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.
- Reads credentials
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- audit-securitySkill
- check-alignmentSkill
- connect-krakenSkill
- setup-krakenSkill
- setup-robinhoodSkill
- trading-botSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
free: - no API key required. Reserve for status, list_tools, read-only discovery endpoints that can't leak wallet/strategy data.
- Very specific: line 36
Every MCP tool calls into a function in server/src/services/<resource>.py.
- Distinctive: line 53
When drafting tools that touch signing, wallets, or execution, state explicitly in the spec's description / preconditions:
- Very specific: line 61
Do NOT create any files. Output the spec as markdown with a JSON schema block for parameter + response + error, ready for review or paste …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 SAGE.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: list_wallets, agent_list_venue_orders, agent_start_paper_schedule.
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_keyparam matchingAPI_KEYSin 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
strwith the natural 0x-prefixed hex convention; chain_id usesint. - Slippage / fee params are
floatin 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 (custody owns wallet secrets outside ordinary agent authority; no tool may add an export capability).
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:
- Transaction signing MUST carry immutable decoded intent through
wallet_manager.sign()into the separate-UID custody broker. Independent human policy bounds wallet, chain, assets, recipients, amounts and fees. Narrow x402/SIWX/marketplace proofs retain their own guarded interfaces; never add generic signing or agent backup/import/export authority (see.claude/rules/wallet-presentation.md). - New tools that take a wallet address MUST check
backup_confirmed_atbefore 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 (SAGE.md if user-facing, docs/contributing.md if dev-facing)Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

