Centrapay-mcp has well-structured tool definitions with clear naming (verb_noun pattern) and complete input schemas. All 9 tools have descriptions and typed parameters. However, descriptions are brief (avg ~80 chars, below the 194-char baseline), lack actionable context for LLM selection, and omit critical details like prerequisites, return value structure, and error recovery guidance. Parameter descriptions are minimal. Output schemas are not documented. Error handling returns raw API errors without recovery hints. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications. Missing idempotency guidance for irreversible operations (pay_payment_request, create_refund).

• Expand tool descriptions to 150 - 250 chars. Include WHEN to use (vs similar tools), prerequisites (e.g., 'Requires a valid configId from list_merchants()'), and what the response contains. Example: 'Create a payment request under a merchant config. Returns a payment URL and request ID. Call this first to initiate a payment flow; use get_payment_status() to poll for completion.'
• Add tool annotations: mark pay_payment_request and create_refund with destructiveHint=true; mark get_payment_status, list_payment_requests, list_merchants, get_merchant with readOnlyHint=true; mark create_payment_request with idempotentHint=true (if idempotencyKey is provided).
• Document output schemas in tool descriptions or as a separate schema field. E.g., 'Returns: {id: string, status: string, paymentUrl: string, value: {amount: string, currency: string}}'.
• Wrap error responses with recovery guidance. Catch API errors and return: 'Error: [error message]. [Recovery hint: e.g., "Call list_merchants() to find valid merchant IDs."]' Categorize as retryable (network timeout) vs user-fixable (invalid configId) vs fatal (auth failure).
• Add idempotency guidance to create_refund and pay_payment_request descriptions: 'Idempotency key must be unique per logical operation. Reuse the same key if retrying the same refund to prevent double-refunds. Generate keys as UUID or hash(operation_id + timestamp).' Provide a helper tool or example.