The server defines 7 well-structured tools with consistent naming, reasonable descriptions, and explicit input schemas using Zod validation. All tools follow verb_noun naming conventions (hn_get_*) and are read-only, which is appropriate for a Hacker News client. However, descriptions are uniformly brief (34 - 76 chars), and parameter descriptions lack detail about constraints, ranges, and edge cases. The output schema is documented implicitly through JSON stringification but not explicitly declared in parameter descriptions. Error handling is minimal, tools return raw API responses without recovery guidance. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present. The schema quality is solid across all tools: all use Zod with explicit type declarations, min/max constraints, and defaults. Naming is clear and consistent. The main gaps are shallow descriptions and missing error guidance patterns.

• Expand descriptions to 100 - 200 chars. Example for hn_get_top_stories: 'Get the 30 currently highest-ranked stories on Hacker News. Returns story metadata including ID, title, URL, score, and comment count. Use this instead of hn_get_best_stories for real-time trending; use hn_get_new_stories for the latest submissions.' This teaches the LLM when to select each tool.
• Document the HNItem return schema explicitly in the tool metadata or in a description field. Include sample field names: 'id (number), title (string), url (string), score (number), descendants (number), type (story|comment|job|poll).' This lets LLMs extract and chain the data correctly.
• Add readOnlyHint: true to all tools in their registration. This signals to clients that these tools are safe to call without side effects and can be cached/replayed.
• Add idempotentHint: true to all tools. LLMs will retry on ambiguous failures without fear of duplicate side effects.
• Enhance error responses with recovery guidance. In the HackerNewsClient.makeRequest() method, catch network errors and return: 'Hacker News API unavailable. This is typically temporary. Retry in 30 seconds.' For null results in hn_get_item, return: 'Item not found. This may indicate the ID is invalid or the item has been deleted. Try hn_get_top_stories to fetch valid item IDs.'
• Document the limit parameter behavior more explicitly. Example: 'Maximum items to return (1 - 500, default 30). The API returns all available items up to this limit; fewer may be returned if fewer exist. Stories are returned in ranked order.'