Server exposes 7 read-only HubSpot tools with consistent naming (verb_noun pattern: list_, search_, get_, describe_, find_). All tools have descriptions (avg ~120 chars, within baseline 34-392). Input schemas are present and typed (Zod). However, output schemas are NOT documented, responses are returned as unstructured text via `text()` helper, making it impossible for LLMs to parse results reliably. Parameter descriptions are adequate but lack examples of valid values or constraints. Error handling is minimal, no recovery guidance or categorization. No tool annotations (readOnlyHint present in descriptions but not in schema metadata). Composition is sound: tools chain logically (list_instances → list_objects → describe_object → search). Single-portal default is smart UX.

• Document output schemas for each tool. Define the structure of results (e.g., hubspot_search returns {results: [{id, properties: {name, email, ...}}], total: number}). Return structured objects, not text blobs.
• Add error recovery guidance. Catch common failures (invalid portal, API rate limit, network timeout) and return actionable messages: 'Portal "X" not found. Available: [Y, Z]. Did you mean one of these?'
• Add readOnlyHint annotation to all tool schemas. Use server.tool(..., {...}, {readOnlyHint: true}) to signal safety to clients.
• Formalize 'object' parameter as enum when possible. For standard objects (contacts, companies, deals, tickets), use z.enum([...]). For custom objects, document the fallback behavior clearly.
• Implement pagination for search and find_across. Add offset/limit or cursor-based pagination. Return total count and next_cursor in response so agents can fetch large result sets incrementally.