Four tools with clear verb-noun naming and complete Zod schemas. All tools have descriptions (avg 110 chars) and parameters are typed with descriptions. However, output schemas are undocumented, responses are JSON-stringified without field-level documentation. Error handling converts exceptions to text but lacks recovery guidance. No tool annotations (readOnlyHint/destructiveHint). Missing pagination for search_companies despite potentially large result sets. Parameter descriptions are adequate but lack format/constraint details (e.g., no guidance on email format beyond Zod validation, no limit on activity body length).

• Document output schemas for all tools. For hubspot_get_contact, explicitly list returned fields: {found: boolean, contact: {id, email, firstName, lastName, lifecycleStage, companyName}}. For search_companies, document {count: number, companies: [{id, name, domain}]}.
• Add pagination to search_companies: introduce 'limit' (1-100, default 20) and 'offset' (default 0) parameters. Return total_count in response so LLM knows if more results exist.
• Add tool annotations via MCP SDK. Mark hubspot_get_contact and hubspot_search_companies with readOnlyHint=true. Mark hubspot_create_contact and hubspot_log_activity with destructiveHint=true.
• Enhance error messages with recovery guidance. E.g., if getContactByEmail returns null, return 'Contact not found. Try hubspot_search_companies() to find the contact by name or domain first.'
• Clarify parameter constraints in descriptions. For 'body' in log_activity, add '(max 5000 chars)'. For 'query' in search_companies, add 'e.g., company name or domain (case-insensitive)'.