zen-mcp demonstrates solid fundamentals: all 14 tools have clear verb-noun names (create_payment_link, refund_transaction, etc.) and descriptions (avg ~100 chars). Input schemas are present with type constraints (minLength, maxLength, format, optional flags). Risk annotations (WRITE, DESTRUCTIVE, READ_ONLY) are well-applied. However, parameter descriptions are sparse, most params lack inline guidance on format, constraints, or dependencies. Output schemas are not documented. Error handling is basic (no recovery guidance visible). Idempotency keys are offered on write operations, which is good practice.

• Add inline parameter descriptions for all params. For 'status' in list_payment_links, document: 'Filter by payment link status (e.g., pending, completed, expired). Omit to list all.'
• Document output schemas for each tool. E.g., create_payment_link returns {id, url, qr_code_url, expires_at, status}. This enables LLMs to chain calls and extract required fields.
• For mutually exclusive params (zenId vs merchantTransactionId in get_transaction), add: 'Provide exactly one of zenId or merchantTransactionId; both cannot be specified.'
• Implement error recovery guidance. Catch API errors and return actionable messages: 'Transaction not found. Verify the transaction ID and try again, or call list_payment_links() to discover valid IDs.'
• Add a confirm_refund or dry_run parameter to destructive tools. E.g., refund_transaction(transactionId, amount, dry_run=true) returns the refund that would be issued without executing it.