HubSpot MCP server has clear tool naming (verb_noun pattern: list_, get_, search_) and complete input schemas with type definitions. However, descriptions are minimal (10-20 chars baseline), parameter descriptions lack depth, and output schemas are entirely undocumented. No error handling guidance, no pagination metadata in responses, and no tool annotations. All 7 tools follow the same pattern but lack the richness needed for production LLM agents.

• Document output schemas for all tools. E.g., hs_list_contacts should declare: returns {contacts: [{id, email, firstname, lastname, ...}], paging: {next: string}}. Include all fields agents need to chain to downstream tools.
• Expand tool descriptions to 80-150 characters. Example: 'List HubSpot contacts with pagination. Returns contact objects with id, email, name, and custom properties. Use limit (1-100, default 10) and after cursor for pagination. Call this first to discover available contacts.'
• Add parameter descriptions for pagination cursors. E.g., 'after: Opaque pagination cursor from a previous response. Pass the paging.next value to fetch the next page. Omit to start from the beginning.'
• Implement error handling with recovery hints. Catch 401 (auth failure) and return 'HubSpot authentication failed. Verify your OAuth token is valid and has contacts:read scope.' Catch 429 (rate limit) and return 'Rate limited. Retry after 60 seconds.'
• Add tool annotations to schema. Mark all tools with readOnlyHint: true in inputSchema metadata so agents know these are safe to call without confirmation.