Five tools with clear verb-noun naming (get_*) and consistent parameter schemas. All tools have descriptions (10 - 100 chars) and input schemas with type constraints. Strengths: consistent naming convention, proper use of Zod for validation, count parameter bounded 1 - 30, comments tool accepts both ID and URL formats. Weaknesses: descriptions are terse (avg 65 chars, below 194-char baseline); no output schema documentation; no error handling guidance; no parameter descriptions beyond count/id; missing idempotency/destructiveness hints.

• Document output schema for each tool. Add a 'returns' section to tool descriptions: 'Returns array of Story objects with fields: rank (int), title (string), url (string), domain (string), points (int), author (string), age (string), ageIso (ISO 8601 timestamp), comments (int), discussionUrl (string), type ("story"|"job").'
• Expand tool descriptions to 100 - 150 chars. Example: 'Get the top 10 - 30 stories currently on the Hacker News front page, ranked by points. Returns story metadata including title, URL, author, points, and comment count. Use this for trending tech news; use get_new for latest submissions, get_ask for community questions.'
• Add per-parameter descriptions in tool registration. Ensure 'count' description appears in the MCP tool definition: 'Number of stories to return (1 - 30, default 10). Higher counts increase response time.'
• Add error handling and recovery hints. Wrap scrapeStories() in try-catch; return structured errors like '{"error": "Timeout fetching HN", "retry": true, "hint": "HN may be slow; try again in 10 seconds."}' instead of raw exceptions.
• Add tool annotations. Mark all five tools with readOnlyHint=true and idempotentHint=true so LLMs know these are safe to retry and do not modify state.