Server Quality Checklist

Tool Scores

• create_projectA
  3.5/5.0
  Behavior1/5

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

  The description calls creation 'irreversible/high-impact' yet annotations have destructiveHint=false, creating a direct contradiction. This undermines the agent's ability to trust the metadata.

  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, front-loaded sentences cover the essential purpose and key behavioral caveats without fluff.

  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?

  Adequate for a creation tool with schema coverage, but missing return value details and incomplete behavioral disclosure due to the contradiction. No output schema, so description should ideally give more context.

  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 covers all parameters (100%). Description adds value with 'admin only' and the confirm requirement, but does not significantly elaborate beyond the 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 explicitly states 'Creates a new Jira project' (verb + resource) and includes 'admin only', clearly distinguishing it from sibling tools like create_board or create_issue_type.

  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?

  Provides useful guidance: requires confirm:true and retry with template_key if creation fails. Does not explicitly contrast with alternatives, but the sibling tools are for different entities so no strong need.

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

• get_storyA
  3.8/5.0
  Behavior3/5

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

  Annotations (readOnlyHint, openWorldHint) already indicate safe read behavior. The description adds that it returns specific fields, which is useful but does not disclose additional traits like 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.

  Conciseness5/5

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

  Two sentences with no wasted words. The purpose is front-loaded and the description is efficiently structured.

  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 tool is simple (one parameter, read-only, no output schema). The description covers the return fields adequately for an AI agent, though a bit more detail on output structure would be beneficial.

  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 parameter 'issue_key' is already described in the schema. The description reinforces the expected format (e.g., 'PRD-42') but adds no new semantic meaning.

  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 specifies the verb 'Retrieves', the resource 'Story', and the input (issue key). It also lists the returned fields, clearly distinguishing it from siblings like 'search_stories' that perform broader searches.

  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 retrieving a single story by key but does not explicitly state when to use this tool over alternatives (e.g., 'search_stories' for queries). No guidance on prerequisites or exclusions.

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

• create_sprintA
  4/5.0
  Behavior4/5

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

  Discloses guarded nature requiring confirmation, which is not fully covered by annotations (idempotentHint false, destructiveHint false). Also notes prerequisite 'Requires Jira Software'. Adds relevant context beyond structured metadata.

  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?

  Extremely concise: two sentences with no filler. Front-loaded with purpose, then key behavior (guarded) and prerequisite. 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 6 parameters (2 required) and no output schema, the description covers purpose, guarding, and dependency. Lacks return value description, but schema descriptions for parameters are good. Reasonably complete for a simple creation 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 covers 100% of parameters with descriptions. The tool description adds no additional parameter-specific meaning beyond what's already in the schema, so 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?

  Clearly states 'Creates a sprint on a scrum board' with specific verb and resource. Distinguishes from siblings like create_board, create_story by specifying sprint creation.

  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?

  Mentions 'requires confirm:true' which guides usage, but lacks explicit when-not-to-use or comparison with alternative tools. Could be improved with scenarios where other creation tools are preferred.

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

• create_storyA
  4/5.0
  Behavior4/5

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

  Annotations already indicate mutability (readOnlyHint=false). Description adds value by detailing formatting of description with acceptance criteria, setting labels/priority, and attaching remote link. No contradictions.

  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, efficient and front-loaded with primary action. Every sentence adds information. No wasted words.

  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 8 parameters (5 required) and no output schema, description covers creation process and return values. Could add more about error behavior if Outline link fails, but overall sufficient.

  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 baseline is 3. Description adds minimal extra meaning beyond schema (e.g., 'formats the description with acceptance criteria' hints at combined 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 it creates a new Jira Story from a PRD, with specific formatting and optional linking. It distinguishes from sibling tools like update_story and delete_story.

  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 use when you have a PRD, but does not explicitly state when to use this tool versus alternatives like update_story or search_stories. No when-not-to-use guidance.

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

• list_sprintsA
  4/5.0
  Behavior3/5

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

  Annotations already indicate readOnlyHint=true, so description adds return field details but no extra behavioral traits like pagination or rate limits. Consistent with annotations.

  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 front-loading purpose and returns, then usage tip and requirement. No unnecessary words, perfectly concise.

  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 list tool with 2 well-documented params and annotations, description is fairly complete. Could explicitly tie board_id to the board that must be a scrum board, but overall good.

  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 descriptions cover both parameters (board_id and state) with source and enum, so baseline of 3 is appropriate. Description does not add further parameter guidance.

  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 states it lists sprints for a given Agile board and specifies returned fields (id, name, state, dates). Distinguishes from sibling tools like get_sprint_burndown and list_boards.

  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?

  Provides context: use sprint id with get_sprint_burndown and requires a scrum board. Does not explicitly state when not to use or list alternatives, but gives clear usage direction.

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

• create_issue_typeA
  4.1/5.0
  Behavior4/5

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

  Beyond annotations, the description adds 'Guarded: requires confirm:true' and 'Issue types are global across the instance.' It also implies high-impact action via the schema, which annotations (destructiveHint: false) do not fully capture. The 'admin only' requirement is extra 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 extremely concise at two sentences, with no fluff. It front-loads the core purpose and critical constraints, making it easily scannable.

  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?

  While the description covers guard, admin requirement, and global scope, it does not describe the return value or error cases. For a creation tool with no output schema, mentioning what the tool returns (e.g., the created issue type details) would improve completeness. Current description is adequate but not fully 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 baseline is 3. The description adds context about the guard (confirm parameter) but does not substantially improve understanding beyond what the parameter descriptions already provide. It mentions 'admin only' which is not in schema, adding some value.

  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 verb 'creates', resource 'new issue type', and scope 'global across the instance'. It effectively distinguishes from sibling tools like create_story and create_project, as no other sibling creates issue types.

  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 mentions 'admin only' and 'requires confirm:true', providing clear context on when to use. However, it does not explicitly state when not to use or suggest alternatives, but given the unique resource, the guidance is adequate.

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

• list_boardsA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the description does not need to restate. The description adds the critical prerequisite ('Requires Jira Software'), which is beyond what annotations cover. No contradictions.

  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?

  Three sentences cover purpose, output, and usage context without redundancy. Front-loaded with the main action. One more sentence could be trimmed but overall efficient.

  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 absence of an output schema, the description adequately describes return values (id, name, type). It also links to downstream tools (list_sprints, burndown). With readOnlyHint annotation covering safety, the tool is well contextualized.

  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 both parameters have detailed descriptions including default behavior. The description does not add new information beyond what the schema already provides, so 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?

  Clearly states it lists Jira Agile boards (scrum/kanban) and specifies returned fields (id, name, type). Distinct from sibling tools like create_board or list_sprints, establishing its role as a prerequisite for other operations.

  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?

  Mentions that Jira Software (Agile) is required and that the board id is needed for listing sprints and fetching burndown data, implicitly guiding when to use this tool first. Could explicitly exclude scenarios, but context is sufficient.

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

• add_commentA
  4.2/5.0
  Behavior4/5

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

  Annotations indicate a write operation (readOnlyHint=false) but non-destructive. The description adds the return shape { success, comment_id } and mentions plain-text limitation. This adds context beyond annotations, though permissions or side effects aren't detailed.

  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, front-loads the core action, and provides an example and return info without extraneous words.

  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 two parameters and no output schema, the description covers the action, return value, and a typical use case. It is adequate but could mention who can use it or any constraints.

  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 both parameters have descriptions. The description echoes 'plain text' and the issue key example, but adds minimal new meaning beyond the schema's 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 'Adds a plain-text comment to a Story,' providing a specific verb and resource. It distinguishes from sibling tools like create_story or update_story by focusing solely on adding 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 provides a concrete usage example ('to log when the PRD doc is updated in Outline'), implying appropriate contexts. However, it does not explicitly state when not to use or mention alternatives for similar actions.

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

• create_boardA
  4.2/5.0
  Behavior4/5

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

  Description adds behavioral context beyond annotations: it flags the confirm guard and permission requirements. Annotations already indicate non-readOnly, non-destructive, but description clarifies the irreversible nature and authorization needs, adding value without contradiction.

  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, zero wasted words, front-loaded with the core action. Efficient and to the point.

  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 low complexity (4 parameters, no output schema), the description covers the key functional aspects: action, prerequisites, guard. It could mention what happens on success/failure, but the high parameter description coverage compensates.

  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% with clear descriptions for each parameter. The description reinforces the filter_id parameter by mentioning 'from an existing saved filter' but does not add substantial new meaning beyond the 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?

  Description states 'Creates a Jira Software Agile board (scrum/kanban) from an existing saved filter.' This clearly identifies the verb (creates), resource (board), and scope (from filter), distinguishing it from sibling tools like create_project or create_sprint.

  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?

  Explicitly states the guard 'requires confirm:true' and prerequisite 'Requires Jira Software and permission to manage boards.' This provides clear context on when to use, though it does not explicitly compare with alternatives.

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

• delete_storyA
  4.2/5.0
  Behavior4/5

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

  Description discloses permanence, irreversibility, guarded behavior (confirm flag), and intended use case. Annotations already indicate destructiveHint true, but description adds the critical detail about warning vs deletion, which is beyond annotations.

  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?

  Three concise sentences, each adding value. Front-loaded with the core action and irreversibility. No unnecessary words.

  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 destructive tool with no output schema, the description adequately covers behavior, parameter effects, and return conditions (warning vs deletion). It is complete enough for correct invocation.

  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%, so parameter descriptions in schema are sufficient. The description reinforces the confirm parameter's guarded behavior but does not add new meaning beyond the schema's description.

  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 (delete), resource (Story), and input (issue key). It distinguishes from sibling tools like create_story, update_story, and get_story by specifying a destructive operation.

  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: irreversible, requires confirmation, intended for human-approved cleanup. It implicitly warns against casual or automated use but does not explicitly name alternatives like transition_story or update_story for deactivation.

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

• search_storiesA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe, non-destructive read operation. The description adds that the query is 'wrapped in JQL' and returns a specific set of fields, providing useful behavioral context beyond the annotations. It does not contradict annotations.

  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: first defines the core action, second gives a use case and return format. It is front-loaded, no redundant words, and every sentence adds value. Perfectly concise for the tool's complexity.

  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 has 3 parameters, no output schema (but description specifies return format), and annotations cover safety/open world, the description is fairly complete. It includes purpose, usage hint, and return structure. Missing details like pagination or error behavior, but acceptable for a simple search 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 coverage is 100% with descriptions for all three parameters (query, max_results, project_key). The description mentions the query as 'plain-text query' but does not add meaningful extra semantics beyond the schema. The return format hint helps slightly, but overall parameter info is adequately covered by 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 action ('Searches for Stories'), the resource ('Stories in the configured project'), and the input ('plain-text query wrapped in JQL'). It distinguishes from siblings like 'get_story' (single retrieval) and 'list_*' tools by specifying a text-based 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 explicitly states a use case: 'Useful for checking duplicates before creating a new Story.' This provides clear context for when to use the tool. However, it does not explicitly mention when not to use it or compare to alternatives among siblings like 'get_story' for single retrieval.

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

• update_storyA
  4.2/5.0
  Behavior4/5

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

  Annotations declare destructiveHint=true and readOnlyHint=false, consistent with 'Updates'. Description adds key behavioral detail: only supplied fields are changed (partial update). No contradictions.

  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, front-loaded with core action and behavior. Every word adds value. 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?

  For a tool with 6 parameters and no output schema, description covers return value, partial update behavior, and usage context. Missing details on idempotency (annotations hint) or error handling, but adequate for selection.

  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 covers 100% of parameters with descriptions. Description adds no new parameter info but reinforces partial update behavior. Baseline 3 due to full 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?

  Clearly states verb 'updates' and resource 'Story'. Includes a usage hint ('after human approval edits') and distinguishes from create/delete by implying modification of existing entity. Returns format is specified.

  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?

  Implies typical use case (after human approval), but does not explicitly state when not to use or compare to sibling tools like transition_story. Provides context but lacks explicit exclusion criteria.

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

• get_sprint_burndownA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds value by describing the returned data (summary and best-effort raw time-series), partially addressing behavioral traits like reliability ('best-effort').

  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, front-loaded with purpose, no wasted words, and clearly structured to present key information first.

  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?

  Despite having no output schema, the description adequately explains the return data (computed summary and raw time-series) and includes a prerequisite. Parameter coverage is complete via schema.

  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% with clear parameter descriptions. The tool description does not add any additional detail beyond the schema, so it meets the baseline without extra value.

  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 verb 'returns', the resource 'burndown data for a sprint', and distinguishes itself from a chart image, which differentiates it from sibling tools like get_story or list_sprints.

  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 for analyzing/summarizing progress and notes a prerequisite ('Requires Jira Software'), but does not explicitly exclude alternative tools or provide when-not-to-use guidance.

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

• transition_storyA
  4.4/5.0
  Behavior4/5

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

  The description adds behavioral context beyond annotations: it reveals that transitions into terminal statuses are guarded and require confirmation, and that omitting the transition parameter lists available transitions. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

  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, extremely concise and front-loaded with the core action. Every sentence provides essential information without 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?

  The tool is simple and the description covers the key behaviors. However, since there is no output schema, mentioning what the listing of transitions returns would improve completeness slightly.

  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?

  Although schema coverage is 100%, the description adds meaning beyond the schema: it explains the effect of omitting `transition` (lists available transitions) and the special role of `confirm` for irreversible actions. This enhances parameter understanding.

  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: moving a Story through its workflow, with concrete examples (To Do -> In Progress -> Done). It distinguishes from sibling tools like update_story or create_story by focusing specifically on workflow transitions.

  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 to call without `transition` to list available transitions and notes that terminal statuses require `confirm:true`. It provides clear context for usage but does not explicitly compare to alternative sibling tools.

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

• list_projectsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds context by specifying that it returns only visible projects and lists the exact fields returned. No contradictions.

  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, extremely concise, front-loaded with key information (lists all projects), no unnecessary words.

  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 parameters, no output schema, and annotations present, the description is complete enough. It states what is returned and how to use it. Minor omission: no mention of pagination or limits, but acceptable for a list-all tool.

  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?

  There are no parameters, and schema coverage is 100% (empty). The description adds full meaning by explaining that the tool lists all projects without any filtering needed.

  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 lists all Jira projects visible to the account, and specifies the returned fields (key, name, id, project type). This distinguishes it from siblings like get_project_info (single project) and create_project (write operation).

  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 advises using this tool to discover which project_key to pass to other tools when working across multiple projects, providing clear context. It does not explicitly state when not to use it, but the guidance is strong.

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

• get_project_infoA
  4.7/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true; description adds specifics about returned data and default project, complementing the annotations well.

  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?

  Three sentences, front-loaded with purpose, then default behavior, then use case. No redundant information.

  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?

  Given single optional param and no output schema, description fully covers purpose, parameters, return details, and use case.

  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 covers 100%, so baseline 3. Description adds that project_key defaults to configured value if omitted, adding meaning beyond the 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 it returns project metadata (key/name, priorities, story issue type id) and distinguishes from sibling tools like list_projects by targeting a specific project.

  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?

  Explicitly says to use for input validation before creating issues, and explains the default project behavior, guiding when to pass project_key.

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