Server Quality Checklist

Tool Scores

• search_postsA
  3.9/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context such as pagination, default sort behavior, and the ability to sort chronologically, but it lacks details on rate limits, authentication needs, error handling, or what metadata is included in results. This leaves gaps for a tool with 13 parameters.

  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 appropriately sized and front-loaded, starting with the core purpose and then detailing features in a logical flow. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

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

  Completeness3/5

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

  Given the complexity (13 parameters, no annotations, no output schema), the description is moderately complete. It covers the tool's purpose, key parameters, and basic behaviors like pagination and sorting, but lacks details on output format, error cases, or full parameter explanations, which could hinder agent effectiveness.

  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 schema description coverage is 0%, so the description must compensate. It effectively adds meaning by listing key parameters (e.g., content type, author, date ranges, points thresholds, comment counts) and explaining sortByDate and pagination defaults. However, it does not cover all 13 parameters (e.g., storyId is not mentioned), slightly reducing completeness.

  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 with specific verb ('Search') and resource ('HackerNews posts'), distinguishing it from sibling tools like get_front_page (which fetches a specific page) and get_post (which retrieves a single post). It explicitly mentions searching by keywords with advanced filtering, establishing a clear scope.

  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 context by mentioning 'advanced filtering options' and default behaviors like sorting by relevance, but it does not explicitly state when to use this tool versus alternatives like get_front_page or get_user. No exclusions or specific scenarios are provided, leaving some ambiguity for the agent.

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

• get_userA
  4.2/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 of behavioral disclosure. It effectively describes what the tool returns (user metadata, karma score, creation date, bio text, computed fields) and the purpose of those fields ('to provide context about user activity and reputation'). However, it doesn't mention error conditions, rate limits, or authentication requirements.

  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 efficiently structured in two sentences: the first states the core purpose and parameter, the second details the return data and its value. Every element adds useful information without redundancy or unnecessary elaboration.

  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 single-parameter read operation with no annotations or output schema, the description provides strong context about what data is returned and why. It covers the tool's purpose, parameter semantics, and return value meaning. The main gap is lack of explicit error handling or rate limit information.

  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 schema has 0% description coverage, so the description must compensate. It clearly explains the 'username' parameter's purpose ('by username') and implies constraints through context (HackerNews usernames). While it doesn't specify format details beyond the schema's min/max length, it provides meaningful semantic context for the single parameter.

  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 ('HackerNews user profile information'), and scope ('by username'). It distinguishes this tool from sibling tools like get_front_page, get_post, and search_posts by focusing on user profiles rather than posts or content.

  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 context by specifying 'by username' and listing the returned data fields, but it doesn't explicitly state when to use this tool versus alternatives. No guidance is provided about prerequisites, limitations, or comparisons with sibling tools.

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

• get_front_pageA
  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 full burden and does well by disclosing key behavioral traits: it's a read operation (implied by 'Retrieve'), supports pagination, specifies the typical page size ('30 posts per page'), and mentions ordering ('ordered by rank'). It doesn't cover rate limits, authentication needs, or error conditions, but provides substantial operational context.

  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 perfectly front-loaded with the core purpose in the first sentence, followed by supporting details about ordering, pagination, and page size. Every sentence adds value with zero wasted words, making it highly 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 the tool's moderate complexity (2 parameters, no output schema, no annotations), the description provides good coverage of what the tool does, how it behaves, and parameter context. The main gap is the lack of output format details (what fields posts contain, structure of return data), which would be needed for full completeness since there's no output schema.

  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?

  With 0% schema description coverage for the 2 parameters, the description must compensate. It explains the pagination concept ('Supports pagination to browse through all front page items') and mentions the default page size ('Front page typically contains 30 posts per page'), which helps interpret the 'page' and 'hitsPerPage' parameters. However, it doesn't explicitly map these terms to the parameter names or explain the 'page' numbering starting at 0.

  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 current HackerNews front page posts'), resource ('HN front page posts'), and distinguishes it from siblings by focusing on the front page rather than individual posts, users, or search results. It provides concrete details about what gets returned ('posts currently featured on the HN front page, ordered by rank').

  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 context for when to use this tool ('to browse through all front page items') and implies usage through the mention of pagination. However, it doesn't explicitly state when NOT to use it or name alternatives like 'get_post' for individual posts or 'search_posts' for filtered searches, which would be needed for a perfect score.

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

• get_postA
  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 well by disclosing key behavioral traits: it's a read operation (implied by 'Retrieve'), returns hierarchical comment trees with nested replies, and includes metadata like comment count and nesting depth. It doesn't mention rate limits, authentication needs, or error handling, but covers core functionality adequately.

  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 appropriately sized and front-loaded, starting with the core purpose and progressively adding details about returned data and structure. Every sentence earns its place by providing essential information without redundancy, 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 the tool's moderate complexity (1 parameter, no output schema, no annotations), the description is mostly complete. It explains what the tool does, what it returns, and the data structure. However, it lacks details on error cases (e.g., invalid post ID) and doesn't fully compensate for the missing output schema by not specifying exact return fields beyond examples.

  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 schema has 0% description coverage, so the description must compensate. It adds meaning by specifying that the parameter is a 'post ID' for HackerNews, implying it's a numeric identifier (though not explicitly stated). This clarifies the parameter's purpose beyond the schema's pattern constraint, but doesn't detail format examples or validation rules.

  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 full details'), resource ('HackerNews post by its ID'), and scope ('complete post data including title, URL, author, points, and the entire comment tree'). It distinguishes from siblings like get_front_page (list), get_user (user data), and search_posts (search).

  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 implies usage context by specifying 'by its ID' and listing returned data, suggesting it's for detailed post inspection rather than browsing or searching. However, it doesn't explicitly state when to use this tool versus alternatives like get_front_page for overview or search_posts for discovery, nor does it mention prerequisites like needing a post ID.

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