Server Quality Checklist

Tool Scores

• get-front-pageA
  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 and does well by disclosing key behavioral traits: it describes the sorting algorithm (HackerNews ranking), typical content (most popular/trending stories), pagination support, default and customizable results per page, and return structure. It lacks details on rate limits or error handling, but covers essential operational aspects.

  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, followed by supporting details, examples, and return information. Every sentence adds value without redundancy, making it efficient and easy to scan for key information.

  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, no annotations, no output schema, and rich schema coverage, the description is largely complete. It covers purpose, behavior, parameters, and return structure, but could benefit from more explicit guidance on when to use alternatives or error handling details to be fully comprehensive.

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

  Parameters3/5

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

  The schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema by mentioning pagination and customizable results per page in general terms, but does not provide additional syntax, format, or usage nuances for the parameters beyond what the schema already documents.

  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 specifying front-page content with HackerNews ranking algorithm sorting. It explicitly mentions that all posts are tagged with 'front_page', further differentiating its scope.

  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 get front-page posts sorted by popularity/trending), but it does not explicitly state when not to use it or name alternatives among sibling tools. It implies usage for paginated retrieval of front-page content without direct comparison to other tools.

  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.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. It discloses key behavioral traits: returns posts in chronological order (newest first), includes all content types unless filtered, supports pagination, has a default page size of 20, and allows an empty query. It doesn't mention rate limits, authentication needs, or error handling, but covers the core functionality well 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?

  The description is well-structured and appropriately sized. It starts with the core purpose, lists key features with bullet points, provides concrete examples, and ends with usage guidance. Every sentence adds value with no redundancy or fluff. The bullet points make it scannable 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?

  For a read-only tool with 3 parameters and 100% schema coverage but no output schema, the description is quite complete. It explains what the tool does, how to use it, and provides examples. The main gap is the lack of output format details (what fields posts include), which would be helpful since there's no output schema. Otherwise, it covers the essential context well.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some value by explaining that tags filter by content type (e.g., story, comment) and providing examples, but doesn't add significant semantic meaning beyond what the schema provides. The baseline of 3 is appropriate when the schema does the heavy lifting.

  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: 'Retrieve the most recent HackerNews posts sorted by date.' It specifies the resource (HackerNews posts), verb (retrieve), and sorting (newest first). It also distinguishes from siblings like 'get-front-page' (which likely shows curated content) and 'search-posts' (which likely searches by keyword).

  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: 'Use this to monitor real-time HackerNews activity or find the newest content.' It distinguishes from 'search-posts' by focusing on recency rather than search queries. However, it doesn't explicitly state when NOT to use it or compare all alternatives (e.g., 'get-front-page' for curated content).

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

• get-itemA
  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 of behavioral disclosure. It does well by specifying performance characteristics ('Large comment threads (>500 comments) may take 2-3 seconds to load due to nested fetching'), error conditions ('Returns error if item doesn't exist or has been deleted'), and what the tool returns ('complete item details including the full nested comment tree'). However, it doesn't mention rate limits or authentication requirements, which would be helpful for a public API 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 well-structured with clear sections (purpose, use cases, features, examples, notes) and front-loads the core purpose. While comprehensive, it could be slightly more concise by combining some bullet points or reducing redundancy between 'Features' and the opening description. Every sentence adds value, but there's minor room for tightening.

  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 output schema, the description provides excellent context about what information is returned (full nested comment tree, complete metadata), performance characteristics, error conditions, and supported item types. The main gap is the lack of output format details (structure of returned data), which would be helpful since there's no output schema. However, it covers most other aspects well.

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

  Parameters3/5

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

  The input schema has 100% description coverage, with the single parameter 'itemId' well-documented in the schema. The description adds minimal value beyond the schema by providing examples of item IDs in the 'Examples' section, but doesn't explain parameter semantics beyond what's already in the schema description. This meets the baseline of 3 for high schema coverage.

  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 detailed information') and resource ('specific HackerNews item by ID'), distinguishing it from sibling tools like get-front-page (list of stories), get-latest-posts (recent posts), get-user (user profiles), and search-posts (search functionality). It explicitly mentions what types of items it works for (stories, comments, polls, poll options).

  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 guidance on when to use this tool through bullet points: 'View a story with all comments', 'Read a specific comment with its replies', 'Explore discussion threads in depth', and 'Get complete metadata for any item'. It also implicitly distinguishes from siblings by focusing on single-item retrieval rather than lists or searches.

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

• get-userA
  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 full burden and does well by disclosing key behavioral traits: case-sensitivity, username validation rules (alphanumeric+underscores), existence requirement, and error conditions. It also mentions that bio may contain HTML. However, it doesn't cover rate limits or authentication needs.

  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 well-structured with clear sections (purpose, use cases, features, examples, validation, error handling) and every sentence adds value. It could be slightly more concise by combining some bullet points, but overall it's efficiently organized and front-loaded with the core purpose.

  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-only tool with no output schema, the description provides comprehensive context: purpose, usage guidelines, parameter details, examples, validation rules, and error conditions. The main gap is lack of output format details (structure of returned profile), but otherwise it's quite complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds some value by providing username validation details (alphanumeric+underscores, case-sensitive, must exist) and examples, but doesn't significantly enhance the parameter understanding beyond what the schema already documents.

  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 get-latest-posts which handle posts/items rather than user profiles. It provides concrete details about what information is retrieved (karma, bio, creation date).

  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 lists four specific use cases (check reputation, read bio, see creation date, verify existence before searching content), providing clear guidance on when to use this tool. It also distinguishes from siblings by focusing on user profiles rather than posts/items, 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.5/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 key behaviors: it's a read-only search operation (implied by 'search'), supports pagination with customizable results per page, returns paginated results with hits, total count, and page information, and explains advanced filtering logic (AND/OR). It doesn't mention rate limits or authentication needs, but covers most operational aspects well.

  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 well-structured with clear sections (Supports, Basic Examples, Advanced Filtering Examples, Numeric Filter Operators, Tag Syntax, Returns). While comprehensive, it could be slightly more concise by reducing some example repetition. Every sentence adds value, and key information is front-loaded.

  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 search tool with 5 parameters, 100% schema coverage, but no output schema or annotations, the description provides excellent context. It explains what the tool does, how to use parameters, provides multiple examples, describes return format (paginated results with hits, total count, page info), and covers filtering logic. The main gap is no explicit mention of error cases or rate limits.

  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?

  Schema description coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by providing detailed examples of parameter usage, explaining numeric filter operators and fields, detailing tag syntax with OR logic examples, and showing how parameters combine in practice. This goes well beyond the schema's basic descriptions.

  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. It specifies the verb 'search' and resource 'HackerNews content', distinguishing it from sibling tools like get-front-page (specific content), get-item (single item), get-latest-posts (recent posts), 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 usage guidance through examples and context. It shows when to use this tool (e.g., for keyword searches, tag filtering, numeric filtering) versus alternatives like get-front-page (front page only) or get-latest-posts (recent posts without search). The examples illustrate various use cases, making it clear when this tool is appropriate.

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