ERC-8004 MCP server provides 11 tools with consistent naming (verb-first), adequate parameter schemas, and moderate descriptions. All tools have input schemas visible in mcp.json. Descriptions average ~120 chars, which meets baseline but lacks the LLM-optimized depth of A-tier servers. Parameter descriptions are present and typed. Critical gaps: (1) No documented output schemas, tools return data but responses are not formally specified, forcing LLMs to guess at field names and types. (2) No error handling guidance, tools will fail but error messages are not designed for agent recovery. (3) No idempotency hints or destructive operation guidance. (4) Parameters lack constraint documentation (e.g., score range -128 to 127 mentioned in description but not in schema, limit defaults not enforced). (5) Batch tool (batch_get_metadata) is good composition, but single-key get_metadata duplicates it without clear differentiation.

• Document output schemas in mcp.json for each tool. For example, register_agent should specify: {type: 'object', properties: {tokenId: {type: 'string', description: '...'}, txHash: {type: 'string'}, owner: {type: 'string'}, ...}, required: ['tokenId', 'txHash']}
• Add JSON Schema constraints to parameters: submit_reputation.score should have minimum: -128, maximum: 127. list_agents.limit and search_agents.limit should have minimum: 1, maximum: 100.
• Add error schemas and recovery guidance. For each write tool, document common failure modes: 'If you receive 'permission denied', the caller is not the agent owner. Use get_agent() to verify ownership.' For get_agent, 'If tokenId not found, try search_agents() to confirm the agent exists.'
• Implement full pagination for list_agents, search_agents, and get_reputation: add 'offset' and 'total_count' to responses. Or use cursor-based pagination (next_cursor) for better performance.
• Consolidate get_metadata and batch_get_metadata: remove single-key version (or clearly document: 'For single keys use get_metadata; for 3+ keys use batch_get_metadata to reduce round-trips'). Batch is almost always better.
• Add tool annotation hints (via tool extensions if supported): register_agent, set_uri, set_metadata, submit_reputation should be marked as destructiveHint: true. Tools should hint whether they are idempotent.
• For set_metadata and set_uri, add a confirmation pattern or dry-run parameter: 'dry_run: boolean (optional, default false), if true, validate but do not submit on-chain.' This prevents irreversible mistakes.