CardOS MCP demonstrates solid definition quality with 27 well-named tools, comprehensive parameter schemas using Zod, and clear descriptions for most tools. Naming follows verb_noun convention consistently (list_products, issue_card, freeze_card). All tools have descriptions (avg ~120 chars, within 10-1024 baseline). Parameters are typed with Zod validators and include descriptions. However, output schemas are not explicitly documented, responses are inferred from API calls. Error handling is basic (CardOSError wrapper) without recovery guidance. Some parameter descriptions could be more explicit about constraints (e.g., 'idempotency_key' lacks format guidance). Tool composition is strong: issue_card → get_card → freeze_card chains work well. Security-sensitive tools (reveal_card, create_card_session) include warnings about sensitive links in descriptions.

• Document output schemas for all tools. For example, issue_card should specify: {card_id: string, status: string, last4: string, expiry: string, ...}. Use TypeScript interfaces or JSON Schema in tool descriptions or a separate schema document.
• Enhance error messages with recovery guidance. Instead of 'CardOS API error 400 (invalid_user)', return 'User not found. Try searching with a partial name or create a new user first.' Categorize errors as retryable (timeout, rate_limit) vs user-fixable (invalid_input, not_found) vs fatal.
• Specify idempotency_key format: 'A stable UUID or string (max 256 chars) that uniquely identifies this request. Reuse the same value if retrying after a timeout to prevent duplicate card issuance.'
• Add pagination metadata to list tools. Return {items: [...], total: number, limit: number, offset: number} or {items: [...], next_cursor: string | null}. Document in tool descriptions.
• Implement confirmation pattern for irreversible operations. Add optional 'confirm: true' parameter to close_card and delete_webhook, or create separate tools (confirm_close_card, confirm_delete_webhook) that require explicit confirmation.