Bitcoin Benji MCP exposes 26 tools via STDIO. Tool definitions are hardcoded in the TOOLS array with basic metadata (name, description, method, path, args). Critical deficiencies: (1) Most tool descriptions lack actionable context, they describe WHAT the tool does but not WHEN to use it or WHAT constraints apply. Example: 'ai_agent' has only 47 chars; 'ai_vision' lacks detail on image formats, size limits, or expected output structure. (2) Parameter schemas are present but many lack critical constraints, numeric params (since_seconds, max_sources) have no min/max bounds; string enums (max_length) are declared but other string params lack format/length constraints. (3) No output schemas documented anywhere, agents cannot predict response structure. (4) Security baseline unmet: no evidence of input validation, rate limiting, or credential isolation. (5) Error handling non-existent, no recovery guidance, no categorization of errors as retryable vs fatal. (6) Tool composition violates single-responsibility: ai_agent is a generic catch-all that duplicates ai_summarize, ai_translate, ai_extract, etc. (7) Parameter naming inconsistent: some tools use natural language (text, url), others use opaque API paths (path: '/bitcoin/tx-status'). (8) 16 of 26 tools are AI inference wrappers with generic descriptions borrowed from API docs, not optimized for LLM decision-making. Baseline expectation (from rubric) is 194 chars average for descriptions; this server averages ~80 chars with minimal disambiguation. No per-tool validation, no idempotency guarantees, no chaining IDs returned in responses.

• Document output schema for every tool. Include field names, types, and expected value ranges. Example: 'get_fees returns {next_block_fee: number (sat/vB), min_30m: number, min_1h: number, direction: 'rising'|'falling', timestamp: ISO8601}'.
• Expand descriptions to 150 - 250 chars. Include WHEN to use (e.g., 'Use when user asks about mempool activity'), prerequisites (e.g., 'Requires Bitcoin full node'), and relationship to similar tools.
• Add min/max constraints to numeric parameters: since_seconds (0 - 86400), max_sources (1 - 20), inputs/outputs (1 - 1000), target_blocks (1 - 144).
• Remove or consolidate ai_agent. It overlaps with ai_summarize, ai_extract, ai_code_generate. If a general-purpose task tool is needed, document what it does differently from specific-purpose tools.
• Add error handling guidance. Document: 'Returns 402 Payment Required if API key balance is insufficient. Retry with valid preimage or enable x402 autopay. Returns 503 if mempool service is unavailable; retry after 30s.'
• Add per-tool permission scopes (e.g., 'read:mempool', 'read:ai', 'write:agent-logs'). Enable least-privilege agent configurations.
• Implement input validation at tool entry points. Return structured errors: '{"error": "Invalid since_seconds: must be 0 - 86400, got -5", "retryable": false}'.
• Add pagination support with limit/offset for tools returning lists. Example: 'get_recent_blocks(limit=20, offset=0) returns {blocks: [...], total: 150000, next_cursor: "..."}', cap results at 50 items max.