Server Quality Checklist

Tool Scores

• add_commentB
  3.3/5.0
  Behavior2/5

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

  With no annotations provided, the description itself carries the full behavioral disclosure burden. It only states the basic mutation and does not mention whether the comment replaces or appends, permission requirements, or whether the operation is irreversible. There is no information about side effects, rate limits, or response structure.

  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, front-loaded sentence that directly states the action and object. It contains no filler, repetition, or unnecessary wording, and is appropriately sized for a simple two-parameter tool.

  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?

  The description is complete enough for a simple tool given the thorough parameter schema, but it relies entirely on the schema and name for context. There is no mention of return values, required permissions, or behavioral side effects, which would matter to an agent deciding how to verify the result of the call.

  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%, with both parameters already documented including an example issue key and a note that comment text is plain text converted to ADF. The tool description itself adds no parameter semantics beyond the schema, 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 and resource: "Add a comment to a Jira issue." It clearly distinguishes itself from sibling tools like create_issue, update_issue, or transition_issue, none of which add a comment specifically. The agent can immediately understand the tool's unique purpose.

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

  Usage Guidelines2/5

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

  The description gives no guidance on when to use this tool versus alternatives, and does not mention prerequisites, typical use cases, or when not to use it. The agent must infer usage solely from the tool name and one-line description.

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

• update_issueA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description carries the full behavioral burden. It does disclose an important trait: 'Only the provided fields will be changed; others remain untouched,' which prevents an agent from assuming full overwrite semantics. However, it does not mention permissions, reversibility, error cases, or what the response contains, leaving some behavioral aspects unexplained.

  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 short sentences with no filler. The first sentence front-loads the core purpose, and the second adds the critical partial-update behavior. Every word adds value.

  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 rich parameter schema and the tool's moderate complexity, the description plus schema covers what an agent needs: what is updated, which fields are affected, and that updates are partial. It lacks details about the response or prerequisites, but nothing essential is missing for a field-update tool.

  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 six parameters clearly (e.g., 'Replace labels with this array,' 'null to unassign'). The description adds no additional parameter-level meaning, 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 states a specific verb and resource: 'Update fields on an existing Jira issue.' The word 'existing' distinguishes it from create_issue, and the scope (fields) separates it from issue transitions or comments. This is unambiguous and actionable for tool selection.

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

  Usage Guidelines2/5

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

  There is no explicit guidance about when to use this tool versus alternatives such as assign_issue or transition_issue. The description does not provide exclusions, prerequisites, or routing hints; it only describes what the tool does without framing the selection context.

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

• create_issueA
  3.7/5.0
  Behavior2/5

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

  No annotations are provided, so the description must carry the responsibility of exposing behavior. It states the create action and lists required/optional parameters, but does not disclose permissions required, side effects, idempotency concerns, or what response is returned (e.g., created issue key).

  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 short, front-loaded with the primary action, and then succinctly separates required from optional fields. Every sentence earns its place.

  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 7-parameter mutation tool with no output schema and no annotations, the description is a little sparse. It states what is needed to start invocation, but it does not clarify the response shape or operational constraints such as permissions or error-relevant 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 schema already covers every parameter with descriptions, so the baseline is 3. The description adds a helpful required/optional grouping, but it says 'requires ... issue type' while the schema marks issueType as optional with a default of 'Task', creating a small inconsistency.

  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?

  Clearly identifies a specific action and resource: 'Create a new Jira issue.' The word 'new' distinguishes this from sibling tools like update_issue and transition_issue without ambiguity.

  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 phrase 'Create a new Jira issue' provides clear context for when to use the tool: when a new issue should be created. It does not explicitly name alternative tools or state when not to use it, but the 'new' framing is enough for most selection scenarios.

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

• transition_issueA
  3.7/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full behavioral burden. It communicates that the tool changes workflow status, but it does not mention permissions, side effects such as notifications or post-functions, reversibility, or what happens on invalid transition attempts. The list_transitions tip is useful but not sufficient disclosure for a mutating operation.

  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 short sentences with no filler. The primary action is front-loaded, and the prerequisite is immediately stated. Every sentence earns its place.

  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 two-parameter tool with full schema coverage and a documented prerequisite, the description is reasonably complete for invoking it correctly. However, since there is no output schema and no annotations, the description does not convey the op's side effects or expected return behavior, leaving some context gaps.

  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 both issueKey and transitionId are already documented. The description reinforces that transitionId must come from list_transitions, which adds operational context, but it does not need to add much because the schema already covers the parameter meanings.

  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 states a specific verb and object: transition a Jira issue to a new status. This clearly differentiates it from siblings like update_issue, add_comment, and assign_issue. It also points toward list_transitions, reinforcing the tool's distinct role in the Jira workflow.

  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 explicitly instructs the agent to use list_transitions first to obtain valid transition IDs, which establishes a clear prerequisite and workflow. It does not explicitly name cases where update_issue should be used instead, but the core usage guidance is present.

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

• get_issueA
  4/5.0
  Behavior4/5

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

  With no annotations and no output schema, the description carries the burden of explaining behavior. It explicitly lists the return contents ('summary, status, description, comments, and metadata') and the verb makes the read-only nature clear, though it does not discuss not-found cases or authentication.

  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?

  A single, targeted sentence delivers the purpose and return content without any filler. The most important information is front-loaded 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?

  The description is sufficient for a single-parameter get operation: it names the input and lists key output fields. It is not exhaustive for edge cases or metadata semantics, but is reasonably complete given the simple tool shape.

  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 coverage is 100% and the description repeats the issue key format straightforwardly. It does not add extra meaning beyond the schema, so a baseline score 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 ('Get') with a clear resource ('full details of a single Jira issue') identified by key. It also provides the input format example, distinguishing it from issue creation, updates, and search.

  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 clearly indicates a single-issue fetch but does not explicitly explain when to choose this over search_issues, or provide exclusions and alternatives. Its usage context is implied rather than spelled out.

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

• list_transitionsA
  4/5.0
  Behavior3/5

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

  There are no annotations, so the description must carry full behavioral weight. It strongly implies a read-only, non-mutating operation with 'List' and 'discover,' which is important. However, it does not disclose dependency on current issue status, permission requirements, or the boundary of what 'available' means, so the agent lacks some behavioral 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?

  Two sentences, no filler. The main action and resource are in the first sentence, and the second sentence adds the crucial workflow context. Every word earns its place.

  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 tool with one fully documented parameter and no output schema. The description tells the agent what the tool lists, why it exists, and how it relates to transition_issue. It does not detail the output shape of the returned transitions, but for a discovery helper this gap is minor.

  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 single required parameter issueKey is already fully documented in the schema with a description and an example ('Issue key, e.g. PROJ-123'). The description adds no additional parameter-level meaning, so the baseline 3 applies given the schema's 100% 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 leads with a specific verb ('List') and a specific resource ('available status transitions for a Jira issue'), and explicitly positions the tool as the discovery step before calling transition_issue. This makes the tool's purpose immediately distinguishable from every sibling, especially transition_issue.

  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 usage context: use it to discover valid transition IDs before calling transition_issue. It does not explicitly state when not to use it or list all alternatives, but the intended workflow is unambiguous and directly steers the agent toward the correct next step.

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

• search_issuesA
  4/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 full burden. It does disclose a meaningful behavioral trait ('Returns a summary table of matching issues') and a concrete JQL example, but it does not mention behavior on invalid JQL, empty results, read-only guarantees, or pagination details. That is acceptable for a search tool but not especially 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 compact and front-loaded, containing purpose, return type, and a useful syntax example in just two sentences with no wasted words. Every sentence contributes to understanding how and why to invoke the tool.

  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 only two parameters and no annotations or output schema, the description is reasonably complete: it states the query language, gives an example, and describes the high-level result. The main gap is the ambiguity around 'summary table' — an agent might not know exactly which fields are returned — but that does not prevent correct invocation.

  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 already 100%, so the baseline is 3. The description adds value with a JQL example ('project = PROJ AND status = "In Progress" ORDER BY updated DESC'), which gives the agent concrete syntax guidance beyond the schema's minimal 'JQL query string'. No additional meaning is needed for maxResults since the schema fully defines its range and default.

  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 states a specific verb and resource ('Search Jira issues using JQL') and further clarifies the outcome ('Returns a summary table of matching issues'). This makes the tool's behavior clear and distinct from siblings like get_issue and search_users, which operate on different resources or use a different method.

  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 purpose is clear enough that an agent can infer when to use it — when needing to query Jira issues using JQL — but there is no explicit guidance about alternatives such as get_issue for fetching a single issue by key. The usage is implied rather than stated, leaving some ambiguity around tool selection.

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

• search_usersA
  4/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 behavioral disclosure burden. It discloses the return value ('account IDs') and intended downstream use ('assignment'), but does not mention pagination, result limits, or access constraints. This is acceptable for a simple search but not exhaustive.

  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?

  One compact sentence with no filler. The action, resource, target fields, and output are all included, and it is front-loaded with the concrete search action.

  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 tool with one required parameter and no output schema, the description is largely complete: it states the input, the expected return type, and a primary downstream use (assignment). It could mention pagination or result limits, but those are not implied by the tool's apparent simplicity.

  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%; the query parameter is already clearly described in the schema. The tool description reinforces that the query can be a name or email, but it doesn't add additional parsing, formatting, or matching details 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?

  Description uses a specific verb and resource: 'Search for Jira users by name or email.' It explicitly states what search targets are accepted and connects output to assignment, making it easy to differentiate from sibling issue management tools.

  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?

  Clear context: it says the tool searches by name or email and returns account IDs for assignment, which aligns with siblings like assign_issue. It does not explicitly list exclusions or alternatives, but no other sibling tool performs user search, so the intended use is clear.

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

• assign_issueA
  4.2/5.0
  Behavior3/5

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

  The description mentions the key behavioral detail of 'empty accountId to unassign' and indicates that lookup of the account ID via search_users is necessary. However, no annotations are present, so the description carries the full burden; it provides no hints about required permissions, error conditions, or the effect of a successful assignment.

  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 and each part has a clear purpose: core action, prerequisite lookup, and unassign behavior. It is front-loaded, minimal, and avoids unnecessary 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 2-parameter, no-output-schema tool, the description covers the main workflow and the special unassign case. It does not mention permission requirements or what a successful response returns, but those are minor gaps given the tool's straightforward nature.

  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 already documents both parameters with usable descriptions (100% coverage), so the baseline is 3. The description adds meaningful extra value by directing the agent to use search_users to obtain the accountId, which goes slightly beyond the schema without adding redundant detail.

  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 first sentence is a precise, verb-resource statement: 'Assign a Jira issue to a user by their account ID.' It clearly identifies the operation, the target resource, and the mechanism, and the tool's purpose is easily distinguishable from siblings like create_issue, update_issue, and search_users.

  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?

  It explicitly directs users to search_users as the prerequisite for finding account IDs and states how to unassign via an empty accountId. It stops just short of a 5 because it does not explicitly define when this tool should be used instead of siblings like transition_issue or update_issue.

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

• list_projectsA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries full burden. It conveys that the tool is read-only and scoped to accessible projects, but it does not mention pagination, response shape, or any limits. For a simple list operation this is acceptable but not deeply 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?

  A single, concise sentence with no wasted words. The operation, resource, and scope are all front-loaded and the description earns its place.

  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 zero-parameter list tool, the description is complete enough: it states the resource, the breadth, and the access scope. There is no output schema, but the core intent is unambiguously conveyed.

  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 tool has no parameters, so the baseline is 4. Since the description names the resource being listed, nothing further is required beyond what the empty input schema shows.

  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?

  States a specific verb (List), resource (Jira projects), and clear scope (accessible to the authenticated user). It is immediately distinguishable from sibling tools, which handle issues, comments, transitions, and user 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 clearly communicates when to use this tool: whenever an agent needs to enumerate Jira projects for the authenticated user. While it does not explicitly name alternatives, no sibling tool overlaps with this listing purpose, so the context is clear and exclusions are unnecessary.

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