HarvestAPI MCP has 25 tools with consistent naming (verb_noun pattern: get_*, search_*) and basic descriptions. However, critical gaps undermine quality: most tools lack input schemas in the source code (only 6 of 25 have visible schema definitions), parameter descriptions are sparse or missing, and output schemas are entirely undocumented. Error handling exists but is generic. The custom zod-to-json-schema converter in index.ts is fragile and incomplete, relying on heuristics that fail for complex types. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite all tools being READ_ONLY. Descriptions are adequate (50-100 chars) but lack dependency hints and recovery guidance.

• Add explicit input schemas to all 14 search and profile tools. Use zod-to-json-schema library (npm install zod-to-json-schema) instead of the fragile custom converter in index.ts. Example: harvest_search_ads should expose query, limit (1-100), offset, and filters parameters with full type definitions.
• Document output schemas for all 25 tools. Add a TypeScript interface or JSDoc comment above each handler showing the response structure. Example: 'Returns { id: string, name: string, url: string, followerCount: number }'. This enables LLMs to plan chained calls.
• Add pagination to all search tools. Expose limit (default 20, max 100), offset/page, and return total_count and has_more in responses. Example: harvest_search_posts(query, limit=20, offset=0) → { posts: [...], total_count: 1234, has_more: true }.
• Add readOnlyHint: true to all 25 tool definitions in the ListToolsRequestSchema response. Modify index.ts to include 'readOnlyHint': true in the tool object returned by ListToolsRequestSchema handler. This signals to agents that these tools are safe to call without confirmation.
• Enhance error messages with recovery guidance. When a tool fails, return actionable next steps. Example: 'Profile not found. Try harvest_search_profiles(name="John") to find the correct profile ID.' Implement in error handlers in index.ts and individual tool files.