Server Quality Checklist

Tool Scores

• get-front-pageA
  4.3/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden and adds valuable behavioral context: it explains sorting by HackerNews algorithm, pagination support, default results per page, and tagging of posts. However, it doesn't cover aspects like rate limits, authentication needs, or error handling.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured and front-loaded with the core purpose, followed by supporting details and examples. Every sentence adds value without redundancy, making it efficient and easy to scan.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no annotations and no output schema, the description does a good job covering purpose, parameters, and behavior, including return structure. It could improve by explicitly mentioning error cases or rate limits, but it's largely complete for this tool's complexity.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description compensates fully by explaining both parameters: 'page' for pagination beyond the first page and 'hitsPerPage' for customizable results per page with a default of 30, including clear examples for usage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action ('Retrieve posts') and resource ('currently on the HackerNews front page'), distinguishing it from siblings like 'get-latest-posts' and 'search-posts' by focusing on front-page content with HackerNews ranking.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage for front-page posts but doesn't explicitly state when to use this tool versus alternatives like 'get-latest-posts' or 'search-posts'. It provides context about what the front page contains but lacks explicit guidance on exclusions or comparisons.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• get-itemA
  4.4/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden and does so effectively by disclosing key behavioral traits: it returns a full nested comment tree, includes metadata details, works for various item types, notes performance implications for large threads (2-3 seconds load time), and specifies error conditions (item doesn't exist or deleted). This covers most critical aspects beyond basic functionality.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-structured and front-loaded with the core purpose, followed by usage guidelines, features, examples, and notes. Every sentence adds value (e.g., performance warning, error handling), with no redundant information, making it efficient and easy to parse.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given 1 parameter with 0% schema coverage, no annotations, and no output schema, the description does an excellent job covering functionality, usage, and behavior. It explains what the tool returns (nested comment tree, metadata) and includes performance and error details. A minor deduction because it doesn't explicitly describe the output structure (e.g., JSON fields), but this is mitigated by the detailed features list.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema has 0% description coverage, so the description must compensate. It adds significant meaning by explaining that 'itemId' corresponds to HackerNews item IDs, provides examples (e.g., '38456789' for a story), and implicitly clarifies it's a string identifier. However, it doesn't detail format constraints (e.g., numeric strings only), leaving minor gaps.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose as 'Retrieve detailed information about a specific HackerNews item by ID' with specific verb ('Retrieve') and resource ('HackerNews item'), and distinguishes it from siblings like get-front-page (list) or get-user (user-focused). The description explicitly mentions it works for stories, comments, polls, and poll options, making the scope precise.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear usage contexts with bullet points (e.g., 'View a story with all comments', 'Read a specific comment with its replies'), which implicitly guides when to use this tool. However, it lacks explicit alternatives or exclusions compared to siblings like search-posts, missing a perfect score for not naming specific alternatives or when-not-to-use scenarios.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• get-userA
  4.6/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it specifies that the username is case-sensitive, returns error conditions (user doesn't exist or invalid format), and describes the return format (karma, bio, creation date). However, it doesn't mention rate limits, authentication needs, or pagination, leaving some gaps for a tool with no annotation coverage.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is appropriately sized and front-loaded with the core purpose, followed by organized sections (Returns, Use this to, Features, Examples, Username validation, Returns error). Some redundancy exists (e.g., 'Username' mentioned in multiple sections), but overall it's efficient with zero wasted sentences.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the complexity (simple read operation), no annotations, no output schema, and 0% schema coverage, the description is quite complete: it covers purpose, usage, parameters, behavior, and error conditions. However, it lacks details on output structure (e.g., exact JSON format) and potential side effects like rate limits, which would be helpful for full completeness.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema has 0% description coverage for the single parameter 'username', but the description compensates fully by detailing username validation rules (alphanumeric/underscores, case-sensitive, must exist), providing examples of usage, and explaining its semantics in the 'Features' and 'Username validation' sections. This adds significant meaning beyond the bare schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action ('Retrieve public profile information') and resource ('for a HackerNews user'), distinguishing it from sibling tools like get-item or search-posts that handle posts rather than user profiles. The verb 'retrieve' is precise and the scope 'public profile information' is well-defined.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit usage scenarios in a bulleted list (e.g., 'Check user reputation', 'Verify user existence before searching their content'), which clearly indicates when to use this tool. It also implicitly distinguishes it from siblings by focusing on user profiles rather than posts, though it doesn't explicitly name alternatives.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• search-postsA
  4.6/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations provided, the description carries full burden and does well: it discloses the tool returns paginated results with hits, total count, and page info, and details advanced filtering capabilities like OR logic. However, it doesn't mention rate limits, authentication needs, or error behaviors, leaving some gaps for a search tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is appropriately sized and front-loaded with the core purpose, followed by organized sections (Supports, Basic Examples, Advanced Filtering Examples, syntax details). While comprehensive, some redundancy in examples could be trimmed for tighter structure, but overall it's efficient and well-organized.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given 5 parameters with 0% schema coverage and no output schema, the description is largely complete: it explains parameters thoroughly, provides return format (paginated results with hits, total count, page info), and includes examples. Minor gaps include lack of error handling or rate limit info, but it's sufficient for effective use.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description must fully compensate, which it does excellently. It explains all 5 parameters: query (keyword search), tags (with syntax examples), numericFilters (with operators and fields), page (pagination), and hitsPerPage (customizable results). Examples and detailed syntax rules provide comprehensive parameter meaning beyond the bare schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool searches HackerNews for stories, comments, and other content by keyword, specifying the resource (HackerNews content) and action (search). It distinguishes from siblings like get-front-page (front page only), get-item (single item), get-latest-posts (latest posts without search), and get-user (user info).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly provides when to use this tool through examples and capabilities: keyword search across titles/text/authors, tag filtering, numeric filtering, pagination, and advanced filtering. It implicitly distinguishes from siblings by offering comprehensive search vs. their specific retrieval functions, though no explicit 'when-not' statements are given.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• get-latest-postsA
  4.7/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With no annotations, the description carries full burden and does well: it discloses sorting behavior ('chronological order, newest first'), content scope ('all types unless filtered'), pagination support, default values ('default: 20'), and that empty query returns all recent posts. It doesn't mention rate limits or authentication needs, but covers key operational traits adequately for a read-only tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Well-structured and front-loaded: purpose statement first, then bulleted features, examples, and usage guidance. Every sentence adds value—no fluff. The bullet points efficiently organize key capabilities, and examples are directly actionable.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 3-parameter tool with no annotations and no output schema, the description is highly complete: it covers purpose, usage, parameters, and behavior. It doesn't detail the exact output structure (e.g., post fields), but given the tool's straightforward nature and lack of output schema, this is a minor gap. Overall, it provides sufficient context for effective use.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description must compensate fully. It explains all 3 parameters: 'tags' for filtering by content type with examples, 'page' for pagination, and 'hitsPerPage' for customizable results with default. The examples provide concrete usage patterns, adding significant meaning beyond the bare schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action ('retrieve'), resource ('most recent HackerNews posts'), and scope ('sorted by date, newest first'). It distinguishes from siblings like 'get-front-page' (which likely shows curated content) and 'search-posts' (which likely searches by keyword rather than recency).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicit guidance is provided: 'Use this to monitor real-time HackerNews activity or find the newest content.' It distinguishes from alternatives by focusing on recency and filtering by tags, unlike 'get-item' (single item) or 'search-posts' (keyword search). The examples further clarify when to use specific parameter combinations.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.