This MCP News Server has 2 well-defined tools with solid input validation via Zod schemas and clear descriptions. However, the implementation has several gaps: parameter descriptions lack depth and implementation guidance, output schema documentation is incomplete in the tool registration layer, error handling is generic without recovery guidance, and the server lacks modern patterns like idempotency hints and per-request metadata handling. The tools themselves are structurally sound (names are clear verbs, schemas are typed), but fall short of production-grade quality seen in A-tier tools. Average tool score: 62 (63 for listTopStories, 61 for getStory).
Returns full details for a specific story by ID
Returns a list of top story IDs from Hacker News
Parameter descriptions lack implementation context. 'Story ID' for getStory.id does not explain format, range, or how to discover valid IDs. Production tool descriptions should include: 'Numeric Hacker News story ID (e.g., obtained from listTopStories). Must be a positive integer.'
Output schema documentation is incomplete. While Zod contracts define getStoryOutput and listTopStoriesOutput with typed fields, these schemas are not explicitly registered or exposed in the MCP tool definition layer. Tools are defined via HTTP routes in handlers/index.ts with no schema export visible to the MCP client. The OpenAPI doc shows schemas internally but MCP protocol compliance requires explicit tool registration with input/output schemas.
Error handling provides no recovery guidance. Both handlers return generic 'Failed to fetch story' and 'Failed to fetch top stories' with HTTP 500. Per the recovery-guide pattern, errors should suggest next steps: e.g., 'Story ID not found. Call listTopStories to see available story IDs.' Current implementation gives agents no actionable path forward.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 49 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
No tool annotations (readOnlyHint, idempotentHint, destructiveHint). Both tools are read-only and fully idempotent, but this is not declared in the tool metadata. Modern MCP clients use these hints to optimize caching and retry behavior. Adding readOnlyHint=true and idempotentHint=true would improve agent performance.
listTopStories has no input documentation. While the input is empty ({}), the tool definition does not describe when to call it, what it returns, or dependencies. A proper description should explain: 'Fetches the 20 current top stories from Hacker News. Call this first to discover story IDs, then use getStory to retrieve full details.'
getStory ID validation error messages are not actionable. Zod regex /^\d+$/ will reject non-numeric input, but the error returned to the agent ('Failed to fetch story') does not explain the constraint. Should return: 'Invalid story ID: must be numeric (e.g., 12345).'