clover-mcp has 5 tools with basic schemas and descriptions, but significant gaps limit production readiness. All tools have descriptions (10-50 chars, mostly short) and input schemas with type definitions. However, parameter descriptions are sparse or missing context. list_inventory and list_orders lack 'required' field declarations. get_merchant_info and get_oauth_status have empty schemas with no parameters documented. Error handling is minimal, no recovery guidance or actionable error messages. No output schemas documented. Tool names follow verb_noun convention (good), but descriptions lack WHEN/WHY context. OAuth flow tool exposes port as a parameter (should be server-side config). No tool annotations (readOnlyHint, destructiveHint). Composition is reasonable, tools are single-purpose, but missing chaining IDs in responses (inferred from code structure, not visible in schema).

• Add output schemas to all tools. Document return fields (e.g., list_inventory returns array of {id, name, price, quantity}). Include pagination metadata (total_count, next_cursor) for list tools.
• Expand parameter descriptions with format, constraints, and examples. E.g., 'query: Free-text search (e.g., "red shirt"). Searches name and description fields.' Add 'required' array to schemas.
• Add tool annotations: readOnlyHint=true for list_* and get_* tools; destructiveHint=true for initiate_oauth_flow (state change).
• Move OAuth port to server-side config (environment variable CLOVER_OAUTH_PORT, default 4000). Remove from tool parameters. Agents should not manage infrastructure.
• Add error recovery guidance. E.g., 'If query returns no results, try search_inventory with partial terms.' Document which errors are retryable (network timeout) vs user-fixable (invalid date format).