MCPChain presents a blockchain-based MCP server registry with 3 tools. However, critical definition gaps significantly impact quality. Tool descriptions are present but lack LLM-optimization guidance on when/why to use them. Input schemas are partially visible with type information, but lack depth in parameter descriptions. No output schemas are documented. The tools themselves are specialized blockchain operations (server registration, removal, attestation logging) that appear valid in isolation, but lack contextual guidance for LLM agent planning. Tool naming follows action-verb conventions (RegisterServer, RemoveServer, LogAttestation) which is positive, but parameter descriptions are minimal. Parameter validation constraints are inferred from code context but not explicitly stated in descriptions. No evidence of error handling patterns, recovery guidance, or actionable failure messages. The schema provided shows basic types (string, uint64) but descriptions like 'Bech32-encoded owner address' and 'Amount to stake in coin format' are functional but spare. Critical issue: no output schema documentation means LLMs cannot plan downstream tool chains. RegisterServer and RemoveServer are purely state-modifying operations but lack confirmation/dry-run patterns for safety.
Tools (3)
LogAttestationwrite40/100
Log an attestation record for agent-tool interactions. Validates required fields (agentId, toolName, requestHash, responseHash), creates an AttestationRecord with interaction ID, agent ID, tool ID, tool name, request and response hashes, and timestamp. Appends the record and emits a logging event.
RegisterServerwrite50/100
Register an MCP server with staking. Validates sender address, parses staked amount, transfers tokens from owner to module account, creates a RegisteredServer object with owner address, description, endpoint URL, MCP schema hash, staked amount, and registration timestamp. Stores a stake record and emits a registration event.
RemoveServerwrite50/100
Remove a registered MCP server. Validates that the server exists and that the caller is the owner. Deletes the server from state and emits a removal event.
No output schemas documented for any tool. LLMs cannot infer what fields are returned or plan downstream tool chains. RegisterServer likely returns a server ID or registration confirmation; RemoveServer likely returns a success status; LogAttestation likely returns an attestation ID. These must be explicitly documented.
Parameter descriptions are minimal and lack actionable constraints. 'Bech32-encoded owner address' is functional but does not guide LLM error recovery. 'Amount to stake in coin format (e.g., '100umcp')' includes an example value that LLMs may reuse literally instead of adapting to context. Replace with formal constraints: enum for coin format, pattern/validation for Bech32 format, and error recovery guidance.
RegisterServer and RemoveServer are destructive operations (write state) but lack confirmation/dry-run patterns. An LLM could accidentally register an invalid server or remove a live endpoint. Add a confirmation request pattern or dry-run mode to prevent catastrophic mistakes.
Recommendations
Document output schema for RegisterServer: Return object with fields {server_id: uint64, owner_address: string, registration_timestamp: string (ISO 8601), staked_amount: string}. Include chaining IDs so downstream tools can reference the new server.
Document output schema for RemoveServer: Return object with fields {success: boolean, removed_server_id: uint64, message: string}. Clarify what happens to staked tokens (refunded?).
Document output schema for LogAttestation: Return object with fields {attestation_id: uint64, interaction_id: string, timestamp: string (ISO 8601)}. Include references for downstream audit queries.
Enrich RegisterServer description: 'Register a new MCP server endpoint with staking to establish trust. Call this after you have deployed the server at a unique endpoint URL and prepared tokens for staking. Requires a valid Bech32 owner address and the MCP schema hash of the server. Returns server_id for use in future operations. Staked tokens are locked and may be forfeited if server validation fails.'
Enrich RemoveServer description: 'Remove a registered MCP server endpoint from the registry. Only the original owner can remove their server. Staked tokens are returned to the owner upon removal. This action is irreversible, removed servers cannot be re-registered under the same endpoint URL. Pass the server_id returned by RegisterServer or obtained from list_servers.'
Enrich LogAttestation description: 'Record an attestation record documenting an agent-tool interaction for audit and verification purposes. Call this after a tool execution completes to create an immutable audit trail. Requires agentId, toolName, request hash (SHA256), and response hash (SHA256). Returns attestation_id that can be used to retrieve the full record later.'
No error handling guidance provided. What happens if owner address is invalid? If endpoint URL is not unique? If stake amount is too low? If server does not exist? Tools must return actionable error messages: 'Invalid Bech32 address format, must start with bech32 prefix. Did you mean: cosmos1...?'
Tool descriptions are generic and lack context for LLM selection. 'Register an MCP server with staking' does not explain when to call this vs. other registration methods, what prerequisites exist (do you need a wallet first?), or what happens next. Add WHAT, WHEN, and WHY guidance per pattern:tool-description.
LogAttestation tool name is vague. 'LogAttestation' does not convey action at a glance, 'create_attestation' or 'record_tool_interaction' would be clearer. Per pattern:tool, verb-noun naming (action_resource) improves LLM comprehension.
Parameter 'creator' in RemoveServer is ambiguous. The description says 'Address of the requester (must be server owner)' but does not explain how LLM determines the current requester's address or how to obtain it. Either provide context about identity resolution or remove this parameter if it should be inferred server-side.
RemoveServer
Add parameter constraints: RegisterServer.stakedAmount must validate format (e.g., /^\d+u[a-z]+$/) and suggest valid denominations in error messages. Document minimum stake amount.
Add parameter constraints: RegisterServer.endpointUrl must be a valid HTTPS URL. Add format validation and error guidance: 'Invalid endpoint URL format. Must be HTTPS (e.g., https://mcp.example.com). HTTP endpoints are not allowed.'
Add parameter constraints: RegisterServer.mcpSchemaHash should validate format (hex string, expected length). Document as 'SHA256 hash of the MCP tool schema in hex format (64 characters, lowercase).'
Add parameter constraints: LogAttestation.requestHash and responseHash should validate format: 'SHA256 hash in hex format (64 characters, lowercase).' Provide error recovery if format is wrong.
Implement confirmation pattern for RegisterServer: Add optional dry_run parameter (boolean, default false). When true, validate all inputs and return estimated stake cost without committing. This prevents accidental registrations.
Implement confirmation pattern for RemoveServer: Require explicit confirmation parameter or add a two-step pattern (initiate removal → confirm with transaction hash).
Add error classification to all tools: Document which errors are retryable (network timeout, temporary service unavailable) vs. user-fixable (invalid address format, missing required field) vs. fatal (server already exists, insufficient stake balance).
Add actionable error messages: Instead of 'Validation failed', return 'Endpoint URL must be unique. Conflict with existing server_id=42 (endpoint: https://existing.example.com). Choose a different subdomain.'
Add permission gate documentation: Clarify that RegisterServer requires the caller to have tokens available and the authority to register servers in this registry. Document which on-chain roles/permissions are required.
Add audit trail documentation: All three tools should log caller address, timestamp, and parameters for regulatory compliance. Document that these logs are immutable and accessible via query tools.
Consider adding list_servers tool to help LLMs discover registered endpoints, staking amounts, and availability before attempting to register or interact. This supports the discovery pattern.
Rename LogAttestation to create_attestation for consistency with verb_noun naming convention. Or use record_interaction or log_tool_interaction.
Add dependency hints to descriptions: 'To remove a server, you must first know its server_id. Call list_servers() to find it, then pass the ID to this tool.'
Strip blockchain-specific jargon from descriptions and make them accessible to LLM agents unfamiliar with Cosmos/DeFi terminology. E.g., replace 'Bech32-encoded' with 'Cosmos address format (starts with cosmos1...)' and 'coin format' with 'token amount (e.g., 100token_name)'.
Document what 'unique' means for endpointUrl: Is it per-owner or global? Can multiple owners register the same endpoint (unlikely)? Clarify in error messages.