Server Quality Checklist

Tool Scores

• get_usersA
  3.8/5.0
  Behavior3/5

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

  With no annotations provided, the description must carry the transparency burden. It discloses the two retrieval modes (all users vs. by ID) but does not mention error handling, return format, or any limitations. For a simple read operation this is acceptable but incomplete.

  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 only two sentences, front-loaded with the verb and resource, and the second sentence adds useful mode detail. Every word earns its place with no fluff.

  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 tool with one optional parameter and no output schema, the description covers the essential functionality (all or by ID). It does not describe the return structure, but that is implicit for a 'get users' operation, making it fairly complete for the simplicity level.

  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 already fully describes the sole parameter (id) with 100% coverage. The tool description repeats the conditional behavior but adds no new semantic details beyond what the schema provides, warranting the baseline score.

  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 action (get) and resource (users), with explicit modes for retrieving all or a single user by ID. It distinguishes well from sibling tools that target different resources (posts, comments, todos).

  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 makes the primary use case obvious (retrieving users) but does not explicitly discuss when to use this tool versus alternatives. No exclusions or comparisons to sibling tools are provided, so guidance is implied rather than stated.

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

• create_postA
  3.9/5.0
  Behavior4/5

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

  The description discloses the key behavioral trait: the post won't be saved but is simulated. This is critical context beyond what annotations provide (none exist). However, it does not mention the return format or other side effects, so it is not a 5.

  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?

  Two concise sentences with no wasted words. The purpose is front-loaded, and the simulation note adds essential behavioral context without bloating the description.

  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?

  For a simple 3-parameter tool with no output schema, the description covers the purpose and the key caveat but omits the expected return value and any authentication or rate-limit considerations. The tool is understandable but not fully specified.

  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 three parameters. The description adds no additional semantic meaning or examples, making the baseline score of 3 appropriate.

  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 'Create a new post on JSONPlaceholder' with a specific verb and resource, distinguishing it from sibling tools like update_post and delete_post. The simulation note adds context without confusing the primary purpose.

  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 creating posts but does not explicitly state when to use this tool versus alternatives or provide exclusions. The simulation note hints at a testing use case, but there is no direct guidance on when to invoke it.

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

• update_postA
  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 disclosure burden. It explicitly reveals the critical quirk — 'This won't actually update the server, but will simulate the update' — which is essential for an agent to calibrate expectations. It does not detail the exact return value or error behavior, but the core non-obvious behavior is honestly surfaced.

  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 two sentences: the first states the primary purpose and the second adds a crucial behavioral caveat. It is front-loaded, concise, and every sentence earns its place with zero filler.

  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 simple mock tool with fully documented parameters and no output schema, the description covers the essential purpose and the simulation caveat well. The main gap is that it does not describe what the tool returns (e.g., a fake updated post object), which would help the agent interpret the result, but the provided information is otherwise adequate.

  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 of 3 applies per the rubric. The description text adds no additional parameter meaning beyond what the input schema already provides for id, body, title, and userId.

  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 pairs a specific verb ('Update') with a distinct resource ('existing post on JSONPlaceholder'), clearly distinguishing it from sibling tools like get_posts, create_post, and delete_post. The platform context further anchors its role in the API.

  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?

  No explicit when-to-use or when-not-to-use guidance is provided, and alternatives are not named. Usage is implied by the 'update' verb in the description and the sibling tool set, while the simulation note hints that real persistence is not achievable, but no direct comparison to create_post or delete_post is made.

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

• get_commentsA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description needs to carry behavioral disclosure. It says 'retrieve', which implies read-only, but does not explicitly state side effects, return format, or behavior when parameters are combined. The addition of 'from JSONPlaceholder' provides source context, but it's minimal.

  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 a single, focused sentence that front-loads the purpose and then lists the retrieval variants. Every word earns its place with no redundancy.

  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 simplicity (no required params, no output schema, no annotations), the description covers the core functionality and parameter combinations. It misses ambiguity about providing both id and postId, but that's a minor gap for a simple GET tool.

  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 only says parameters are optional, but the description explains the meaning: no params returns all, id returns a specific comment, postId returns comments for a post. This adds semantic value beyond the schema, which has 100% coverage but lacks the combination logic.

  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 gets comments from JSONPlaceholder, with a specific verb and resource. It also distinguishes between retrieving all comments, by ID, or by post ID, which separates it from sibling tools that retrieve other resources.

  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?

  While it doesn't explicitly say 'use this instead of get_posts', the resource is clearly distinct from siblings, and the description outlines the three usage modes (all, by ID, by post ID). It implies the appropriate context for using this tool.

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

• get_postsA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the burden. It states this is a retrieval operation with no side effects, and outlines the available query variants. It does not mention response format or potential limitations, but for a simple read-only tool the description is reasonably transparent.

  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 a single, well-structured sentence that front-loads the primary purpose ('Get posts') and efficiently covers all three modes. There is no filler or redundant 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?

  This is a simple read-only tool with two optional parameters, no output schema, and no nested objects. The description is sufficient for an agent to understand the tool's capabilities and primary use cases, though it omits details like response format or pagination, which are not critical for a basic JSONPlaceholder endpoint.

  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 already describes both parameters (id and userId) with 100% coverage. The description essentially paraphrases the schema's semantics by mentioning retrieval by ID and filtering by user ID. It adds no new or deeper meaning beyond what the schema provides.

  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 retrieves posts from JSONPlaceholder and explicitly lists the three retrieval modes: all posts, by ID, or by user ID. The verb 'get' plus resource 'posts' distinguishes it from sibling tools like get_users and get_comments.

  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 gives clear context on when to use the tool: whenever posts are needed, with optional filtering by ID or user. It does not explicitly mention alternatives (e.g., 'for comments use get_comments'), but the sibling names make the appropriate use obvious.

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

• get_todosA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. The verb 'Get' suggests a read-only operation, and the description details retrieval modes, but it does not explicitly state read-only semantics, error behavior, or response format. This is partial transparency.

  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 a single, efficient sentence that front-loads the resource and immediately explains the parameter usage. There is no wasted wording, and the structure is clear and scannable.

  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 simple read tool with two optional parameters and no output schema, the description covers the core functionality and parameter interactions. It does not mention return format or explicitly confirm read-only behavior, but given the low complexity, it is adequately complete.

  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 coverage is 100%, but the description adds meaning by mapping parameters to specific retrieval modes. It clarifies that omitting both parameters returns all todos, while providing 'id' or 'userId' filters accordingly. This goes beyond the schema's per-field 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 it retrieves todos from JSONPlaceholder, using the specific verb 'Get' and resource 'todos'. It further distinguishes from sibling tools (posts, users, comments) by the resource type and explicitly lists three retrieval modes (all, by ID, by user ID).

  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 explains the three invocation scenarios (all todos, by ID, or by user ID), giving clear context for when to use the tool and which parameters to provide. It does not explicitly mention alternatives or exclusions, but the resource difference from siblings makes the usage straightforward.

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

• delete_postA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the full disclosure burden. It explicitly reveals that the deletion is simulated and will not actually modify the server, which is a critical behavioral trait. However, it omits any details about permissions, errors, or response format.

  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?

  Two short sentences: the first states the core purpose, the second provides a crucial caveat. No unnecessary words or repetition.

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

  Completeness5/5

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

  For a one-parameter simulation tool with no output schema, this description plus the schema fully covers what the agent needs to know: what it does, the id to specify, and the simulating behavior.

  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 already documents the single 'id' parameter with a clear description. The tool description does not add any further parameter detail, but the schema coverage is 100%, so the baseline of 3 is appropriate.

  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 uses a specific verb ('Delete') and names the resource ('a post') plus the platform ('JSONPlaceholder'). It clearly distinguishes itself from sibling tools like create_post, update_post, and get_posts.

  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?

  While the description does not explicitly mention when not to use it or name an alternative, the purpose is so unambiguous that a user would know this is for deleting posts. The simulation caveat provides important context but does not direct to alternatives.

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