PayHere MCP has well-structured tool definitions with complete schemas and descriptions. All 5 tools have clear verb-noun naming (create_, get_, issue_, generate_, verify_) and descriptions ranging 80 - 250 chars. Input schemas are fully typed with Zod validation. However, output schemas are not documented in the tool definitions themselves, responses are inferred from code comments and API contracts rather than explicit schema declarations. Error handling is present but lacks recovery guidance (e.g., 'if refund fails, try X'). Tool composition is sound: create_checkout_payload and generate_signature work together; get_payment feeds into issue_refund. Security is strong: secrets injected via env vars, never exposed as parameters. Minor gaps: no pagination support (get_payment returns all records), no batch operations, and output field naming could be more consistent with input parameter naming conventions.

• Add explicit output schema declarations to each tool registration. Use JSON Schema to document return fields, types, and examples. E.g., create_checkout_payload should declare { action_url: string, form_fields: object, html_snippet: string }.
• Enhance error messages with recovery guidance. E.g., 'Refund failed: payment_id not found. Call get_payment(order_id) to retrieve valid payment IDs for this order.'
• Document generate_signature parameter dependencies more formally. Consider splitting into two separate tools (generate_checkout_signature, generate_notify_signature) to eliminate conditional logic and make each tool's contract explicit.
• Add pagination support to get_payment if PayHere API allows filtering by date or status in future versions. For now, document the result limit and advise agents to call get_payment once per order_id rather than in loops.
• Expand verify_credentials description to explain when to call it (first call during setup), what success means (credentials valid, OAuth token obtained), and what failure modes indicate (missing env vars, invalid credentials, network error).