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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that this is a POST (write) operation via the endpoint, but does not mention authentication requirements, rate limits, side effects, or return values. This is a minimal addition beyond the fact that it adds a comment.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single concise sentence that includes the relevant endpoint. It is front-loaded with the action and resource, contains no unnecessary words, and is easy to parse at a glance.

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

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

Given the low complexity (2 simple params, no output schema), the description covers the core purpose but lacks any contextual details such as expected response format, error conditions, or confirmation of success. This makes it minimally viable but not fully complete for an agent that might need to handle invocation outcomes.

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

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

The schema description coverage is 100%, with both 'issueKey' and 'comment' clearly documented. The description adds no additional meaning beyond the schema, so it does not improve parameter understanding beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Adds') and resource ('a comment to an issue'), and includes the REST endpoint for clarity. This clearly distinguishes it from sibling tools like get_issue_comments, which retrieves comments, and create_issue, which creates issues.

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

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

The description implies usage through the verb 'Adds' but does not explicitly state when to use this tool versus alternatives. It lacks any mention of exclusions, prerequisites, or when to prefer get_issue_comments for reading comments, so guidance is only implicit.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It mentions the POST endpoint and the returned key, but does not disclose any permission requirements, side effects, failure behavior, or irreversibility of the creation, which is a significant gap 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.

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

The description is a single, well-formed sentence that includes the core action, the endpoint, and the return value. It contains no unnecessary words or repetition, making it maximally concise and front-loaded.

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

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

The tool is relatively simple with documented parameters and a clear return value, but the description omits contextual guidance such as when to prefer this tool over the specialized create_jira_story_from_requirements. It also lacks any mention of potential validation rules or error conditions, leaving the description only minimally complete for the tool's simplicity.

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

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

The input schema provides descriptions for all four parameters, covering 100% of parameter semantics. The description adds no additional parameter-level meaning beyond the schema, so it meets the baseline of 3 but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a new Jira issue via a specific endpoint and returns the issue key. However, it does not differentiate from the sibling tool create_jira_story_from_requirements, which also creates Jira issues, so it lacks explicit sibling differentiation.

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

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. It does not mention the existence of create_jira_story_from_requirements or any conditions that would favor one over the other, leaving the agent to infer usage.

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

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

With no annotations, the description carries the full burden and does well by disclosing the creation behavior, heuristic parsing rules (tagged lines, 'As a...' phrasing, bullets), and dryRun safety. It does not explicitly mention permissions or reversibility, but the mutation and preview behavior are well explained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is appropriately sized at about three sentences, front-loaded with the primary purpose, and every sentence earns its place by explaining modes, parsing rules, and dryRun. It is concise yet thorough.

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

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

Given the tool's complexity and lack of output schema, the description covers the main workflow, parsing heuristics, and preview capability. It does not explicitly state the return value (e.g., created issues vs. parsed items), but the overall operation is well enough specified for an agent to use it effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the relationship between `items` and `notes` (items override parsing and are recommended for pre-analyzed content) and clarifies that `dryRun` previews without creating. This adds semantic meaning beyond the schema's individual field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Turns... into... and creates' with a clear resource (Jira Stories, Tasks, Bugs) and target project. It clearly distinguishes itself from sibling tools like create_issue by focusing on parsing requirements text into structured backlog items.

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

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

The description gives clear usage context: use `items` when pre-structured, use `notes` for automatic parsing, and use `dryRun` to preview. While it does not explicitly contrast with alternatives like `create_issue`, the mode-selection guidance is strong and practical.

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

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

With no annotations provided, the description discloses the HTTP method (GET) and the raw-data output, which conveys read-only behavior. It does not mention pagination or rate limits, but the schema documents maxResults and the description's emphasis on arbitrary JQL hints at potential complexity. Overall, it adds useful behavioral context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is only two sentences, with no filler. The first sentence states the action and output; the second provides usage context. All words contribute to understanding.

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

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 read-only query tool: it specifies the purpose, the alternative, and the output type ('raw issue data'). The absence of an output schema is mitigated by this output description. It does not detail error scenarios or pagination, but these are minor for a well-scoped tool with a fully described schema.

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

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

Schema coverage is 100%, so the description only needs to add minimal context. It aligns 'requested fields' with the fields parameter and 'arbitrary JQL' with the jql parameter, but does not explain default behavior or parameter interactions. The schema itself already provides parameter-level descriptions, so the description adds no critical new semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs arbitrary JQL queries via the Jira REST API and returns raw issue data. It explicitly contrasts with the sibling search_issues by mentioning its fixed field set, making the scope and resource unambiguous.

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

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

It gives explicit guidance: 'Use this for ad-hoc reporting when search_issues' fixed field set isn't enough.' This names the alternative and specifies the condition for choosing this tool, which is clear and actionable.

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

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

No annotations are provided, so the description carries full behavioral burden. It reveals read-only intent via the GET endpoint and links to configured credentials, but does not explicitly state auth requirements, possible errors (e.g., invalid credentials), or output structure. It provides some context but omits failure modes and side-effect absence.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single sentence that immediately states the tool's purpose, followed by the endpoint in parentheses. It is front-loaded, concise, and contains no unnecessary words.

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

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

For a zero-parameter, read-only identity tool, the description gives enough context for an agent to know when and why to call it. Although there is no output schema or annotation, the description's clarity mitigates the need for extensive detail. However, it could specify the returned fields or error scenarios for full completeness.

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

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

The tool has zero parameters, so the baseline is 4. The empty schema provides complete coverage, and the description need not explain any parameter semantics. Nothing more is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's function: returning the Jira user identity associated with the configured credentials. It uses a specific verb ('Returns') and resource ('user identity'), and includes the REST endpoint for precision. This distinguishes it from sibling tools, which focus on issues, projects, or comments.

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

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

The intended usage is clear: call this tool to retrieve the current user's identity. While it does not explicitly contrast with alternatives, no sibling tool serves this purpose, so the context is sufficient without exclusions or when-not guidance.

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

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

With no annotations provided, the description carries full responsibility. It discloses a non-obvious limitation: linked Confluence pages are never included, and in Jira Data Center they appear as remote links. It also notes the dependency on CONFLUENCE_BASE_URL for certain tools. However, it does not specify response format or error behavior, which are minor gaps for a single-issue fetch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is longer than average, but every sentence serves a purpose: stating the action, listing return fields, and giving a detailed cross-tool workflow for Confluence. It is well-structured with a clear 'Confluence access' section. Slightly verbose but justified.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is exceptionally complete. It explains the tool's scope, its relationship to other tools, and provides an end-to-end alternative workflow. It fully covers the context an agent needs to use it correctly.

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

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

The schema already fully covers the single parameter (issueKey) with an example. The description adds usage context by referring to the issueKey in the workflow, but no extra parameter semantics beyond what the schema provides. Baseline 3 for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the verb ('fetches'), the resource ('full details for a single issue'), and the API endpoint. It lists specific fields returned, distinguishing it from sibling tools like get_issue_comments or search_issues.

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

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

Provides explicit guidance on when NOT to use this tool (Confluence content), and exactly when to use alternative tools (get_issue_remote_links, confluence_get_page, and confluence_search). The 'Confluence access' section offers a step-by-step workflow, covering both reading remote links and alternative search.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It simply states 'Lists all comments' and the endpoint, without explaining pagination behavior, whether the result is a complete list or as-yet-unloaded pages, or any authentication/permission requirements. The GET endpoint implies read-only, but key behavioral traits are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single sentence that immediately states the action and resource, with the REST endpoint in parentheses for precision. There is no redundant text or padding; every element earns its place, making it highly concise and well-structured.

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

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

Given the tool's simplicity (one parameter, no annotations, no output schema), the description provides a minimal but workable overview. It fails to mention the structure of the returned comments (e.g., comment bodies, authors, timestamps) or any pagination limits, which are gaps an agent might need. This is adequate for a basic tool but not fully complete.

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

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

Schema coverage is 100%, and the sole parameter issueKey is already clearly described in the schema with an example ('ABC-123'). The description's endpoint reference including {key} adds no additional semantic meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Lists all comments on an issue' uses a specific verb ('Lists') and resource ('comments on an issue'), making the tool's purpose immediately clear. The REST endpoint reference further reinforces the named resource and distinguishes it from siblings like add_comment (which creates) and get_issue (which retrieves issue details).

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

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

The description implies the tool is for retrieving comments when needed, but provides no explicit when-to-use guidance, exclusions, or comparisons to alternatives. The presence of sibling tools like add_comment and get_issue is not leveraged to clarify use cases, so it remains at the 'implied usage' level.

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

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

With no annotations provided, the description must fully convey behavioral traits. It states 'Lists', implying a read-only operation, and includes the endpoint and link types, which adds useful context. However, it does not mention permissions, pagination, error handling, or the exact return format, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, well-structured sentence that front-loads the core action ('Lists an issue's remote links'), then provides the endpoint and examples. Every word adds value with no fluff.

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

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

For a simple one-parameter list tool with no output schema or annotations, the description is largely complete. It states what the tool does, the exact endpoint, and the types of links included. It could mention the response format or potential error cases, but given the tool's simplicity, this is sufficient.

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

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

The schema already provides full coverage with a clear description of the only parameter, issueKey ('Issue key, e.g. 'ABC-123''). The description's mention of '{key}' in the endpoint reinforces this but adds no new information beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists an issue's remote links, using a specific verb ('Lists') and resource ('an issue's remote links'). It also provides the exact endpoint and examples of link types, which distinguishes it from siblings like get_issue_comments or get_transitions.

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

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

The description provides clear context on what the tool does and what content it covers (Confluence pages and generic web links), which helps the agent decide when to use it. It does not explicitly mention when not to use alternatives, but the context is sufficient for a straightforward list operation.

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

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

No annotations are provided, so the description carries the burden. It discloses that the operation is a GET (read-only) and that it is scoped to visibility. However, it does not mention pagination, output format, or potential auth failures, which are minor gaps for a simple list operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, concise sentence that fronts the action and resource. No redundant wording; every element adds value.

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

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

For a simple parameterless tool with no output schema, the description provides enough context: it names the endpoint and the result set. It could elaborate on the return structure, but 'Lists all Jira projects' adequately implies a list of project objects.

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

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

The input schema has zero parameters, so the baseline of 4 applies. The description adds no parameter-specific information because none exist, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Lists'), the resource ('Jira projects'), and the scope ('visible to the authenticated user'). It is distinct from sibling tools which focus on issues, comments, and transitions.

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

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

The description conveys clear usage context: use it to get all projects the user can see. It does not explicitly mention when not to use it or name alternatives, but the specificity makes the appropriate scenario obvious.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It adds a small nuance with 'currently available,' indicating dynamic results based on issue status, but does not state read-only nature, permissions, or return format. Lacks the context needed for an agent to understand side effects or prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

A single, concise sentence that front-loads the purpose and includes the API endpoint. Every word earns its place, with no filler or redundancy.

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

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

For a low-complexity tool with one parameter and no output schema, the description is minimally adequate. However, it does not explain what the returned transitions contain or how to use them with the sibling tool 'transition_issue', which would improve completeness for an agent.

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

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

Schema coverage is 100% as the only parameter 'issueKey' has a clear description and example. The description adds no extra meaning beyond the schema, so baseline of 3 is appropriate per the rubric.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists workflow transitions for an issue, with a specific verb ('Lists') and resource ('workflow transitions... for an issue'). It distinguishes from the sibling tool 'transition_issue' by focusing on retrieving available transitions rather than performing one.

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

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

The description implies usage in a workflow context but does not explicitly state when to use this tool versus alternatives like 'transition_issue' or 'get_issue'. No exclusions or alternative scenarios are mentioned, leaving the agent to infer from the title and sibling tool names.

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

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

No annotations are provided, so the description must disclose behavioral traits. It mentions the GET endpoint and returned fields, but does not mention pagination, default result limits, or error behavior. The read-only nature is only implied by the HTTP method, not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, front-loaded sentence that immediately states the action, includes the endpoint, and lists return fields with no extraneous words.

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

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

With no output schema and no annotations, the description should more fully describe behavior. It lists returned fields but omits pagination details and the effect of maxResults, and it does not clarify how search_issues differs from execute_jql. This incompleteness could cause incorrect usage.

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

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

The input schema has 100% parameter description coverage for jql and maxResults, so the baseline is 3. The description adds no additional parameter meaning, only stating that it runs the query without elaborating on the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs a JQL query and returns matching issues, with the specific REST endpoint and a list of returned fields. This is a specific verb+resource, but it does not explicitly differentiate from the sibling tool execute_jql, which may also run JQL.

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

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

There is no guidance on when to use search_issues versus alternatives like execute_jql. The description only states what it does, not the context or exclusions.

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

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 discloses the HTTP method (GET), the endpoint, and that it returns data, implying a read-only operation. However, it does not mention authentication requirements, potential errors, or that the endpoint is specifically for Jira Data Center (as opposed to Cloud). These are useful behavioral nuances but the description partially covers them by naming 'Jira Data Center'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

A single, front-loaded sentence that provides the purpose, key return fields, and the endpoint. No wasted words, and the structure is immediately scannable. The API path is included as a useful reference without burdening the text.

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

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

For a zero-parameter, read-only tool with no output schema, the description is sufficiently complete. It lists exactly what data will be returned (version, deployment type, build number), which allows an agent to decide if this tool is relevant. No additional behavioral details are necessary given the tool's simplicity.

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

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

The tool has zero parameters, and the input schema is empty. The baseline for 0 params is 4, and there is nothing for the description to add beyond the schema. The description correctly does not invent parameters or add unnecessary detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns Jira Data Center deployment info (version, deployment type, build number) and specifies the exact GET endpoint. This verb+resource combination is specific and distinguishes it from sibling tools focused on issues, projects, or users.

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

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

Although there are no explicit 'when to use' instructions, the description provides clear context that this is the tool for retrieving server deployment information. Among the sibling tools, none serve the same purpose, so implicit usage is strong. Lacks explicit exclusions or alternative guidance, but this is a minor gap for such a simple read-only tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that this is a mutating POST operation ('Moves') and highlights the need for valid transition IDs, but it does not mention permissions, reversibility, side effects, or potential extra fields required by some transitions. This is a moderate level of transparency, missing some context that would be helpful for a write operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two sentences, front-loaded with the core action, includes the endpoint, and finishes with a valuable prerequisite. Every word earns its place with no redundancy or filler.

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

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

For a tool with only 2 parameters and no output schema, the description provides the essential usage steps: move the issue and consult get_transitions for the ID. It lacks details on potential error conditions or required transition fields, but given the simplicity and the schema coverage, it is largely complete.

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

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

The schema already provides descriptions for both parameters with 100% coverage, so the description adds limited new meaning. It reinforces the transitionId source by telling the agent to use get_transitions, which is helpful but not essential given the schema's 'see get_transitions' note. This meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Moves') and identifies a clear resource ('issue through its workflow'), making the tool's purpose unambiguous. It also distinguishes itself from sibling tools like get_transitions by explicitly referencing it for discovering transition IDs, and includes the API endpoint for additional clarity.

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

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

The description explicitly instructs to use get_transitions first to discover valid transitionId values, providing a clear prerequisite and guiding the agent on when to use this tool relative to a sibling. This effectively tells the agent the sequence of operations and implies the alternative for obtaining transition IDs.

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