Loading ToolBench
The server implements a single tool (get_stories) with a clear action verb and reasonable schema structure. However, the tool description is quite short (28 chars), lacking the context and selection guidance expected for production tools. The input schema is properly defined with enums and constraints, but lacks depth in parameter descriptions. Error handling exists but provides minimal recovery guidance. The tool definition is explicitly visible in src/index.ts and properly registered with the Server.
Get stories from Hacker News
Tool description is too short (28 chars). Provides no context about WHEN to use this tool, WHAT it returns, or why an agent should call it. LLMs need 50-200 char descriptions that explain use cases and output structure.
Output schema is not documented. The tool returns a Story array with fields (title, url, points, author, time, commentCount, rank), but LLMs cannot see this structure. Must document the expected output fields so agents can plan downstream reasoning.
Parameter descriptions lack specifics about what the returned data represents. The 'limit' parameter says 'Number of stories to return (max 30)' but does not explain that stories are ranked Hacker News items with engagement metrics (points, comments). Without knowing the domain, an LLM cannot reason about when to fetch more stories.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 52 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 45 | - | v1 |
Error handling exists (McpError with ErrorCode.InternalError) but provides no recovery guidance. When fetching fails, the LLM receives 'Failed to fetch stories: <error message>' with no hint about retry strategy, whether the issue is transient, or what to do next.
No pagination or result limiting hints in the tool description. The schema enforces a max limit of 30, but the description does not explain that HN pages contain ~30 stories and larger limits may cause long fetch times or timeout. Agents need to know the practical constraints.