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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, open-world write. The description adds value by noting the Markdown body format and that the comment is attributed to the connected user, but it does not warn about duplicate comments or what happens if the issue is closed or the user lacks permission.

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 tight sentence with no waste, and the key action and resource are front-loaded. It is perhaps slightly under-specified rather than verbose.

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 3-parameter write tool with no output schema, the description covers the core action but omits what the call returns (e.g., comment ID) and any failure conditions. Adequate but with clear gaps around return value and error behavior.

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 description coverage is 100%, so issueKey, body, and site are already fully documented in the schema. The description only reinforces that body is Markdown, adding no new semantic detail. Baseline 3 applies.

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?

States a specific verb and resource ('Adds a comment ... to an issue') plus the body format (Markdown) and acting identity (connected user). It is clearly distinguishable from the sibling jira_get_comments, though it doesn't explicitly contrast with it.

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 when-to-use guidance, no prerequisites (e.g., must be connected / have comment permission), and does not point to any alternative such as viewing existing comments first. The agent must infer context from the name alone.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the mutation profile is known. The description adds useful behavioral facts – a hard 50-issue cap and the conditional resolution rules – but says nothing about what happens to issues already in another sprint, closed sprints, or partial-failure behavior on a batch.

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?

Two tight sentences with zero filler; the core action and the 50-item limit come first, then the parameter disambiguation. Every clause earns its place.

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 trickiest conditional logic (sprint resolution, board/project fallback) is well covered, but with no output schema the definition still leaves the return shape and error/partial-success behavior unexplained, which matters for a 50-item batch mutation.

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 only 20% (only `site` is documented), so the description carries most of the burden, and it does well: it explains that `sprint` accepts an id, name, 'active' or 'next', and that `boardId`/`projectKey` are conditionally required with a stated default. It does not show the expected `issueKeys` format (e.g. 'PROJ-123'), leaving one param partly implicit.

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 states a specific verb ('Moves') and resource ('up to 50 issues into a sprint'), which is unambiguous against siblings like jira_get_sprint_issues or jira_get_sprints. It never names an alternative, but no confusion is possible given the distinct operation.

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 conditional prerequisites ('name/active/next need boardId or projectKey') and a default ('projectKey defaults to the first issue's project'), which helps an agent decide how to call it. However, it never states when to use this tool versus jira_get_sprints or another sprint operation, and offers no 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?

Annotations already declare non-read-only, idempotent, non-destructive, open-world behavior, and the description is consistent with them. The description's extra content (unassign path) is already stated in the assignee parameter schema, so it adds little context on permissions, lookup failures, or what is returned.

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?

Two short sentences, zero filler, with the primary action stated first and the unassign variant second. Every clause carries information.

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 3-parameter mutation with no output schema, the description covers the action and both termination states, and annotations carry the safety profile. Minor gaps: user-resolution failure behavior and required permissions are not mentioned.

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 description coverage is 100%, so all three parameters are fully documented in the structured field, including 'site' and the exact-match-one-user constraint. The description only restates the assignee forms already in the schema, so baseline 3 applies.

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?

Specific verb+resource ("Assigns an issue to a user") with accepted identifier forms, and the inverse operation (unassign) stated. It does not acknowledge that jira_update_issue can also change an assignee, so sibling differentiation is incomplete, keeping it off a 5.

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?

Both modes of use are spelled out: supply an assignee string, or omit/null/'unassigned' to clear. There is no explicit statement of when to prefer this over jira_update_issue or a transition, and no prerequisites (resolve user first) are surfaced.

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?

Annotations already establish that this is a read-only, non-destructive, open-world operation, so the safety profile is covered. The description adds useful behavioral context by listing what the response reveals (connection state, account, sites) and by telling the agent to call it first when another tool reports NOT_CONNECTED. It does not discuss auth prerequisites or rate limits, but those are not essential for a zero-parameter status check.

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 purpose and followed by a directly actionable routing instruction. Every sentence earns its place and there is no redundant or filler 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?

There is no output schema, so the description carries the burden of explaining what the tool returns. It does so by naming the connection state, Atlassian account, accessible sites, and selected site. That is sufficient for an agent to understand the tool's result shape, though it does not specify exact field names or response formatting.

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 takes zero parameters, so there is no parameter syntax to explain. The baseline for zero-parameter tools is 4, and the description appropriately focuses on the status information returned rather than inventing parameter guidance.

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-resource pairing: it shows Jira connection status and enumerates the exact status fields returned (connected state, Atlassian account, accessible sites, selected site). This distinguishes it from sibling tools like jira_connect, jira_list_sites, and jira_select_site, which perform actions rather than report status.

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 an explicit triggering condition: 'Call this first if any other tool reports NOT_CONNECTED.' That is clear usage guidance for the primary diagnostic scenario. It does not explicitly mention alternatives such as jira_connect or jira_list_sites, but the error-routing instruction provides actionable context without ambiguity.

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?

Annotations only tell the agent this is a non-read-only, open-world, non-destructive call. The description adds the behavior that actually matters: it opens the system browser, returns a URL the agent must surface, blocks for up to waitSeconds, and keeps waiting in the background for 5 minutes total — all invisible in the annotations.

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?

Three sentences, front-loaded with the action, then the timing behavior, then the user-facing instruction. No sentence is redundant with the schema or annotations.

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?

There is no output schema, and the description still says what comes back (the authorization URL) and how to handle the case where consent is pending. For a two-optional-parameter auth tool, nothing an agent needs is missing.

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, but the description adds real meaning: waitSeconds bounds only the blocking wait while the login continues in the background, which reconciles the schema's 240-second maximum with the stated 5-minute total. The force parameter is left entirely to the schema, so not a full 5.

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?

States a specific verb and resource: 'Starts the Atlassian OAuth 2.0 login.' It also names the concrete mechanics (system browser consent, returns authorization URL), which separates it cleanly from jira_auth_status, the sibling that only checks state.

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?

Gives explicit when-to-use (start login), what to do on the non-approved path ('you can call this tool again or jira_auth_status to check'), and a user-facing fallback instruction ('Show the user the URL if the browser did not open'). The alternative and the retry condition are both spelled out rather than inferred.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safe-read profile is covered. The description adds valuable behavioral context beyond that: the count is 'approximate' (a real accuracy caveat for JQL) and no issue payloads are fetched, which signals cost/weight.

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 efficient sentence that front-loads the core behavior and packs the key differentiator ('without fetching them') into the trailing clause. No 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 simple two-parameter read tool with annotations covering safety, this is nearly complete. The one gap is the return shape (is it a bare number or a wrapped object?), which matters since there is no output schema, but otherwise nothing an agent needs to call it is missing.

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 50%: the 'site' parameter is fully documented in-schema, but 'jql' has no description and the definition adds nothing about JQL syntax or validity. The description restates that a JQL query is the input but does not compensate for the undocumented required parameter.

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?

States a specific verb+resource ('Approximate count of issues matching a JQL query') and implicitly distinguishes itself from the search/fetch siblings via 'without fetching them'. It doesn't name jira_search_issues directly, but the read-only counting scope is unmistakable.

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 phrase 'without fetching them' implies you should use this when you only need a number rather than the issues themselves, which hints at the alternative. However, it never names jira_search_issues or states an explicit when-to-use/when-not rule, leaving the routing inference to the agent.

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?

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), so the description's job is to add context — and it does, by disclosing that the project is inherited from the parent and that valid issuetypes are project-dependent. It says nothing about permissions, failure modes, or what happens if the parent is not an Epic, which keeps it out of the top tier.

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?

Two short sentences, front-loaded with the core action and constrained scope, then the conditional hint. No filler and no restatement of the title.

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 12-parameter mutation tool with a nested customFields object and no output schema, the description leaves meaningful gaps: it never mentions that required fields vary per project or points at jira_get_create_fields, and it does not say what is returned (presumably the new issue key). Adequate but not 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 58%, and the description only adds semantics for issueType and parentKey, both of which the schema already documents reasonably. Labels, priority, components, storyPoints and summary carry no explanation in either place, so the description does not compensate for the documented-parameter gap.

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 names a specific verb (creates), an enumerated set of issuetypes (Feature, Story, Task, Bug) and a fixed placement (under a parent Epic keyed by parentKey). The statement that 'the project is taken from the parent' implicitly separates it from jira_create_issue and jira_create_subtask, though neither sibling is named.

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 a concrete conditional rule ('Use issueType="Feature" where the project has that type') plus a fallback path ('call jira_get_issue_types if unsure'), which is exactly the kind of routing hint an agent needs. It stops short of an explicit exclusion (e.g. 'for a subtask of a Story use jira_create_subtask instead'), so it does not reach a 5.

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?

Annotations already declare the safety profile (readOnly=false, destructive=false, non-idempotent, openWorld). The description adds one genuine behavioral fact — automatic detection of the epic issue type — which is useful. It says nothing about required permissions, whether duplicate epics are rejected, or what happens if no epic issue type exists in the project.

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?

Two short sentences, front-loaded with the core action and immediately followed by the workflow hint. No filler; it is arguably under-specified rather than verbose.

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 an 11-parameter mutation tool with no output schema, the description only tells the agent what gets created and what to do next. It omits what the call returns (issue key/id?), how required fields interact with customFields, and any failure modes, leaving the agent to infer from the 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 only 55% and the description compensates for none of it: labels, summary, priority, components and storyPoints are undocumented in either place, and the description never mentions a single parameter. The auto-detection note is about issue type, not about inputs, so it does not fill the gap.

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?

States a specific verb and resource ('Creates an Epic') and adds a distinguishing behavioral detail — the epic-level issue type is auto-detected per project. It does not, however, differentiate itself from jira_create_epic_with_children or jira_create_issue, which live in the same sibling set and overlap heavily.

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 a follow-up path ('use jira_create_child_issue to add features/stories under it'), which implies this is the bare-epic tool. But there is no explicit when-to-use / when-not guidance versus jira_create_epic_with_children, which presumably does this plus children in one call.

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?

Annotations already cover safety (non-read-only, non-destructive, non-idempotent, open-world), so the bar is lower; the description still adds real value by disclosing that it 'fails fast on the first error' and 'reports what was created,' which tells the agent this is a non-atomic batch that may leave partial state and returns a creation manifest. The main omission is whether partial creations are rolled back or persist after failure.

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?

Two sentences with zero filler, front-loaded with the create action and hierarchy, then the failure semantics. Every clause carries information an agent needs.

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?

This tool has no documented parameters, no output schema, and no annotations, so the description fully carries the burden. It states a specific verb and resource, describes the three-level hierarchy, and names the safety profile it inherits. Nothing an agent needs in order to call it correctly is missing.

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 50% (only projectKey and site are described), and both the 'epic' and 'children' parameters are undocumented nested objects. The description loosely maps the schema shape by naming epic, child issues with types (features/stories/tasks), and optional sub-tasks, but adds no ordering, cardinality, or field-level detail beyond what the schema shows. Baseline 3 for a half-documented schema with a small clarification.

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?

States a specific verb and resource (creates an Epic plus child issues, with optional sub-tasks) and captures the full three-level hierarchy in one sentence. It implicitly separates itself from the granular path with 'in one call,' but never names jira_create_epic / jira_create_child_issue / jira_create_subtask, so the differentiation is inferred rather than stated.

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?

Usage is only implied: 'in one call' hints that this is the batch alternative to repeated single-issue calls, but there is no explicit when-to-use or when-not-to-use guidance, no mention of the sibling create tools, and no guidance on batch size limits or when to prefer the granular tools instead.

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?

Annotations already declare the write/open-world/non-idempotent/non-destructive profile, so the bar is lower. The description still adds value by disclosing the return payload ('the new key and URL') and the Markdown-to-Jira-rich-text conversion behavior, which annotations do not cover.

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?

Four short sentences, zero filler, with the core action front-loaded and hierarchy/format/return details following in priority order. Every sentence carries distinct information.

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?

Covers the essentials for a 14-parameter create tool with 86% schema coverage: hierarchy handling, description format, and return values. Missing only permission/prerequisite notes and guidance on customFields or site selection, which the schema mostly handles.

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 86%, so the schema already documents nearly all 14 parameters. The description's parentKey guidance and Markdown note largely restate what the schema's own field descriptions state, adding little new semantic information; baseline 3 applies.

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?

Opens with a concrete verb+resource ('Creates an issue of any type') and describes scope (any type, hierarchy via parentKey). It partially distinguishes itself from siblings by naming jira_create_subtask, but does not clarify its relationship to jira_create_epic, jira_create_child_issue, or jira_create_ticket_from_context.

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?

Gives actionable routing guidance: use parentKey for stories/features/tasks under an Epic, or for sub-tasks under a standard issue, and points to jira_create_subtask when you want the sub-task type auto-picked. It stops short of saying when NOT to use this tool versus jira_create_epic/jira_create_child_issue.

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?

Annotations already declare the write/open-world/non-idempotent profile, so the bar is lower. The description does contribute real behavioral context — the sub-task issue type is auto-detected, so the caller need not resolve it — but says nothing about required screen-field availability, permission needs, or what is returned on success.

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?

Two front-loaded sentences with no filler; the parent constraint comes first. It is efficient but also lean to a fault, given the 11-parameter surface it is fronting.

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 an 11-parameter mutation with a nested customFields object and no output schema, the description covers the parent-key rule and auto issue-type detection but omits the practical Jira caveat that fields must exist on the sub-task create screen (discoverable via jira_get_create_fields) and gives no success/failure behavior. Adequate but with a clear gap.

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 55%, with the discriminating parameters (site, parentKey, assignee, description, dueDate, customFields) already well documented in-schema. The description adds only the implicit 'no issueType parameter needed' insight; it says nothing about labels, priority, components, storyPoints, or how customFields keys behave on sub-tasks.

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?

Specific verb+resource ('Creates a sub-task') plus an explicit constraint on the parent ('under a standard issue (Feature, Story, Task, Bug)'), which separates it from jira_create_issue and jira_create_child_issue. It stops short of naming those siblings, so the differentiation requires the agent to infer from the parent-type clause.

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?

Usage is implied by the parent-type restriction — the agent can deduce 'standard issue, not Epic' — but the description never states when to prefer this over jira_create_issue, jira_create_child_issue, or jira_create_epic_with_children, nor does it mention prerequisites.

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?

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=true, so the write/safety profile is covered. The description adds that it 'builds a consistently formatted description', which explains a real behavioral trait beyond the annotations, but says nothing about required permissions, what the resulting description looks like, or what identifying data comes back.

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?

Three short sentences: action first, then the formatting behavior, then the duplicate-check pointer. No filler and no restatement of the tool name.

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 21 parameters, no output schema and only 62% schema coverage, the description should carry more weight than it does. It omits what the tool returns (e.g. the created issue key), how the sections are ordered or rendered, and how the many optional attributes interact with the generated description.

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 62%, so roughly a third of the 21 parameters are undocumented anywhere. The description's field list (problem, context, reproduction steps, expected/actual, acceptance criteria, technical notes, links) does convey that these inputs are composed into a formatted description rather than passed raw, which is value beyond the schema, but it ignores site, assignee, priority, parentKey, labels, dueDate, storyPoints and customFields entirely.

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?

States a specific verb and resource ('Creates a well-structured ticket') and enumerates the structured content it accepts, which is more than the title restates. However, it never distinguishes itself from the closely-named sibling jira_create_issue, so an agent cannot tell from the description alone which creator to choose.

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 points at one sibling, jira_find_duplicate_ticket, but only with the hedged 'when appropriate', giving no concrete condition. There is no guidance at all versus jira_create_issue, jira_create_epic, jira_create_child_issue or jira_create_subtask, all of which are viable alternatives in this family.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, so 'Permanently' and 'Irreversible' largely restate structured data. The one piece of added value is the user-confirmation requirement, which is a workflow constraint the annotations cannot express. No detail on collateral effects (comments, links, attachments) or what happens when subtasks exist.

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?

Two short sentences with the destructive nature front-loaded and the safety instruction immediately after. No filler, no 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 destructive one-required-param tool with full annotation and schema coverage and no output schema, this covers the essentials. The only gap is scope of destruction — whether comments, links, and attachments go with the issue — which an agent might reasonably want before confirming with a user.

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 description coverage is 100%, including the non-obvious 'required if it has any' rule for deleteSubtasks, so the schema carries parameter semantics fully. The description adds nothing about issueKey format, site selection, or the subtask flag, which is acceptable given the coverage baseline of 3.

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?

States a specific verb ('Permanently deletes') and resource ('an issue'), which is unambiguous and easily distinguished from siblings like jira_update_issue or jira_transition_issue. It stops short of naming those alternatives, so it is clear but not maximally differentiated.

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?

'Confirm with the user first' is a genuine precondition, which is more than most definitions offer. However, there is no guidance on when deletion is preferable to alternatives (e.g., closing via jira_transition_issue or jira_update_issue), and no mention of the subtask prerequisite that the schema imposes.

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?

Annotations already declare destructiveHint=true and openWorldHint=true, so the description's job is to say what exactly is destroyed and what remains. It does both: stored tokens on this machine are removed, while the remote app grant persists until manually revoked. It does not mention irreversibility of the deletion or what the caller must do afterwards (re-run jira_connect), which keeps it off a 5.

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

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

Two sentences, front-loaded with the action and its effect, then the remediation caveat. Every clause carries information an agent needs; nothing is padded or restated from the annotations.

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 parameters, the description only needs to convey the state change and the residual remote grant, which it does. A note on what happens to existing in-flight sessions or whether reconnection is needed would make it fully self-contained.

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 there is nothing for the description to disambiguate. A 4 is the baseline for a no-arg tool; no parameter-related gaps exist.

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?

States a specific verb and resource ('Deletes the stored tokens') and names the effect ('this machine is no longer authorized'). It is clearly the inverse of jira_connect, though it never names that sibling explicitly.

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 second sentence gives the critical usage context: local deletion leaves the app authorized remotely, so full revocation requires the Atlassian URL. It stops short of an explicit 'use this when you want to log out / do not use if you only need to switch sites' rule, but the conditional is clear enough to act on.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description still earns credit by disclosing which fields are searched (summary, description, AND comments — a non-obvious scope) and that output is candidate duplicates for the user to judge rather than an automatic decision. It omits ranking/recency behavior and the default result cap, which would be useful for a 6-param open-world search.

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?

Two sentences, zero waste, with the precondition ('Before creating a ticket') front-loaded ahead of the mechanics and the return semantics. Nothing repeats the title verbatim or pads with 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?

With no output schema, the description must carry the return shape, and 'returns likely duplicates' is thin — an agent doesn't know what fields come back or how many. It also leaves maxResults and issueType entirely undocumented across both schema and prose. Adequate for a pre-create sanity check, but there are clear gaps for a 6-parameter tool.

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 67%, and the description maps only two of six parameters — 'summary/keywords' to query and 'a project' to projectKey. The undocumented-in-schema parameters (issueType, maxResults) get no compensation from the description, nor does it clarify the includeDone default's effect on duplicate detection. Baseline 3 fits.

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?

States a specific verb and resource ('searches a project for existing issues matching a summary/keywords') and adds the text-search scope (summary, description, comments) plus the intent ('returns likely duplicates'). The purpose is unambiguous and clearly narrower than a generic search, though the sibling jira_search_issues is never named as the contrasting option.

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?

'Before creating a ticket' gives a concrete trigger condition, so an agent knows exactly when to reach for this tool rather than jira_create_issue. However, no exclusion is stated — nothing says 'do not use this for general issue lookup, use jira_search_issues instead' — so the alternative routing is left 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the useful chaining fact that returned board ids feed sprint lookups. It says nothing about result volume, pagination, or whether all boards across sites are returned.

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?

Two compact sentences with the resource and filters front-loaded, followed by the downstream-use note. Nothing is padded, though the second sentence is a fragment that could more explicitly name the sprint tools.

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 four-parameter, no-output-schema list tool, the description leaves the agent guessing at the returned shape (does it include board id, name, type, project?) and at site selection behavior. The chaining hint helps, but an agent still needs to open the schema to call this confidently.

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 description coverage is only 25% (only 'site' is documented), so the description must carry more weight. It does mention name and projectKey filtering, covering two of four params, but the 'type' enum (scrum/kanban/simple) is only obliquely hinted at by 'Scrum/Kanban boards' and 'site' is not explained at all. Partial compensation, not full.

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 names the resource (Scrum/Kanban boards) and the available filters (project key or name), and the tool name/title supply the 'list' verb. It distinguishes itself from sprint-related siblings by positioning itself as the board-id source. It stops short of a full verb+resource statement on its own.

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?

'Board ids are needed for sprint lookups' implies the ordering: call this before jira_get_sprints/jira_get_sprint_issues. But no sibling is named explicitly and there are no when-not conditions (e.g. when to use jira_list_projects instead). Usage is inferable rather than stated.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds the key trait that only direct children are returned (not the full descendant tree), which is genuinely useful behavioral context. It says nothing about ordering, pagination/caps on large epics, or the exact return shape.

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 well-formed sentence with zero filler, front-loading the verb and the resource and reserving the parenthetical for the disambiguation that matters. Nothing to trim.

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, the description carries responsibility for describing results, and it does name the two returned attributes (status, assignee) and the scope restriction (direct children only). For a small read-only tool with 100% schema coverage that is largely sufficient, though pagination behavior and the full result shape remain unstated.

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 description coverage is 100%, and each parameter (site, issueKey, includeDone) is documented in the schema including the default for includeDone. The description mentions no parameters at all, so it adds no meaning beyond the schema; baseline 3 applies.

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?

Specific verb (Lists) and resource (direct children of an Epic, or sub-tasks of a standard issue), plus a glimpse of what's returned (status and assignee). It disambiguates the overloaded word 'children' by naming both hierarchy levels. It stops short of naming a sibling it is not (e.g., jira_get_issue for the parent, jira_search_issues for cross-project queries), so it is clear but not fully differentiated.

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?

Usage is implied by the two scenarios it enumerates (Epic children vs sub-tasks of a standard issue), which tells the agent when the tool applies. However, there is no explicit when-not guidance and no pointer to alternatives such as jira_search_issues for broader hierarchy queries or jira_get_issue for the parent itself.

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?

Annotations already declare readOnly=true, destructive=false, and openWorld=true, so the safety profile is covered. The description adds useful behavior — newest-first ordering and Markdown formatting — but omits pagination/default count behavior even though a maxResults parameter exists, leaving 'Latest comments' ambiguous in size.

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?

One tight sentence with no filler, and the key attributes (newest first, Markdown) are front-loaded. It borders on under-specified rather than verbose, but by the sizing criterion it is efficient.

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?

No output schema exists, so the description's mention of Markdown format and ordering is valuable. However, it fails to clarify default/maximum result counts or whether paging is required to get all comments, which is a meaningful gap for a read tool with a maxResults cap.

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 67%: site and issueKey are well documented, but maxResults has no description in the schema and the description never explains its role in limiting the 'latest' comments. Baseline 3 for middling coverage where the schema does most of the work.

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?

States a specific verb+resource (get comments), plus ordering (newest first) and output format (Markdown), which clearly separates it from the sibling jira_add_comment. It does not name any sibling explicitly, so it stops short of the 5 bar.

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?

Usage is implied: fetch comments for an issue key. There is no explicit when-to-use, no mention of when not to use it, and no pointer to alternatives (e.g., jira_get_issue for full issue detail).

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the useful content detail that results include required vs optional status and allowed values. It does not discuss result shape or site-resolution behavior, but the schema handles the latter.

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?

Two tight sentences with the purpose front-loaded and the usage trigger immediately after; no filler and nothing repeated from the schema.

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 read-only discovery tool with no output schema, the description tells the agent what the payload contains (field list, required/optional, allowed values) and why to call it. Only the requiredOnly filter and pagination/size expectations are left unaddressed.

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 75% and the required params (projectKey, issueType) are well documented in the schema. The description's phrase 'required and optional' hints at the undocumented requiredOnly flag, but it never states what that parameter does, so it only partially compensates for the gap.

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?

States a specific verb and resource ('Lists the fields ... for creating an issue of a given type in a project') and scopes it to create-time fields, which implicitly separates it from the generic jira_get_fields sibling. It stops short of naming that sibling explicitly, so the differentiation requires a small inference.

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?

Gives two concrete invocation triggers: 'when a create fails because of a missing required field' and 'to find custom field ids.' That is clear context for when to reach for it, but there is no explicit statement of when NOT to use it or which sibling to prefer for a general field listing.

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?

Annotations already establish read-only, open-world, non-destructive behavior. The description adds useful context that system and custom fields are included and that Sprint/Story Points field ids are detected, but it omits permissions, response size, and any pagination or caching behavior.

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?

One tight sentence that front-loads the main payload (all fields with ids) before the special detection note and the query filter. No 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 two-parameter, read-only list tool with no output schema, the description sufficiently explains what is returned (fields, ids, detected Sprint/Story Points ids). It relies on the schema for the `site` parameter and does not explain pagination, but that is minor here.

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 both `site` and `query` are fully documented in the schema. The description only echoes the `query` filter at a high level and adds no syntax or behavior beyond the schema's 'case-insensitive substring' 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?

States a specific resource and scope: all system and custom fields with ids, plus special Sprint/Story Points detection. This clearly distinguishes it from field-related siblings like jira_get_create_fields, though it does not name any sibling explicitly.

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 only guidance is 'Filter with `query`,' which explains a parameter rather than when to choose this tool over alternatives. The use case (discovering field IDs, especially Sprint/Story Points) is implied but never stated as an explicit when-to-use rule.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the description field is rendered as Markdown, comments are fetched only on request (default off), and 'extra' fields hang off a separate block. Pagination/comment-limit behavior is still unstated.

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?

One front-loaded sentence that lists exactly what you get, with the conditional payload (comments) flagged as optional at the end. No 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?

No output schema exists, so the description carries the burden of describing the return shape, and it does so at a reasonable level of detail for a read tool. It could go further on comment count limits or behavior with unknown field ids, but nothing critical for correct invocation is missing.

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 description coverage is 100%, so the baseline is 3. The description only reinforces includeComments as optional; it adds nothing about 'site', 'fields' (that extras land under `extra`), or the issueKey format beyond what the schema already documents.

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?

States a specific verb+resource ('Full details of one issue') and enumerates the payload (fields, description, parent, sub-tasks, links, comments), which separates it from list-style siblings like jira_search_issues. It does not name any sibling explicitly, so differentiation is implied rather than stated.

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?

Usage is only implied: it is clear you call this when you want full detail on a single known issue, but there is no statement of when to prefer jira_search_issues, jira_get_comments, or jira_get_children instead. No prerequisites or exclusions are given.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, so safety is covered. The description adds value annotations cannot: it decodes the hierarchyLevel values (1 = epic level, 0 = standard, -1 = sub-task), which is the key to interpreting the response and correctly choosing a create tool afterwards.

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?

Two compact sentences, front-loaded with the resource, followed by the one piece of interpretive guidance an agent actually needs. No filler, no restatement of the tool name or annotations.

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 two-parameter read tool with no output schema, the description plus annotations cover nearly everything needed: what is returned (type names) and how to read hierarchyLevel. It stops short of stating the response shape (flat list vs. keyed object) or ordering.

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 description coverage is 100% and both parameters (site, projectKey) are documented in the schema, so the baseline 3 applies. The description adds nothing about parameter behavior and the hierarchyLevel note refers to output, not input, so it does not raise this dimension.

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?

States the resource and scope precisely: issue types available in a specific project, with concrete examples (Epic, Feature, Story, Task, Bug, Sub-task). The verb is implicit (list/retrieve) and there is no differentiation from adjacent lookups like jira_get_fields or jira_get_create_fields, but an agent can tell what it gets back.

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?

No explicit when-to-use statement, no prerequisites, and no named alternatives among siblings such as jira_get_create_fields or jira_get_fields. The only implicit signal is that a projectKey is required, so the agent must infer this is a pre-creation lookup.

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?

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, and idempotentHint=false. The description adds that the phrases feed jira_link_issues, but it does not explain the return shape or whether all link types are returned for the selected site. No contradiction is present.

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 short clauses, front-loaded with the resource and a concrete example, followed by actionable usage guidance. There is no 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 simple read-only lookup with one optional schema-documented parameter and full safety annotations, the example plus routing to jira_link_issues is largely sufficient. It could still clarify that it returns all available link type names and phrases, but that is a minor gap.

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?

There is one optional parameter, site, and schema description coverage is 100%, so the schema fully documents it. The description does not mention the site parameter, so the baseline of 3 applies.

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 identifies the resource as issue link types and gives a concrete example mapping 'Blocks' to 'blocks' / 'is blocked by'. The title supplies the list verb, and naming jira_link_issues distinguishes this lookup from the linking mutation sibling.

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 explicitly says to use the returned phrases with jira_link_issues, making clear this is a prerequisite lookup for linking issues. It does not describe when not to use it or mention alternatives, but the usage context is clear.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The phrase 'available on the site' adds a small amount of behavioral context by signaling results are site-scoped, but nothing about caching, stability, or result shape is disclosed.

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 short sentence with zero padding, and the site-scoping qualifier is included. It is arguably too terse for a fragment, but nothing wasted.

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-required-param read-only lookup with full schema documentation and annotations, this is close to sufficient. The only real gap is that the description does not state that the result is a flat list of name/id pairs, which would help since there is no output 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?

There is a single optional parameter and schema description coverage is 100%, with detailed guidance on cloud id vs. site name vs. URL and the omit-to-use-default behavior. The description adds nothing beyond that, so baseline 3 applies.

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 names the resource returned (priority names) and scopes it to a site, which is enough to know the general purpose. However, it uses a sentence fragment with no verb and never differentiates from sibling reference-data lookups such as jira_get_issue_types, jira_get_fields, or jira_get_link_types.

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 call this versus the other enum-lookup siblings, no stated prerequisite (e.g. selecting a site first), and no mention of what to do with the result. The agent must infer the use case from the name alone.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds useful context about what the response contains (issue type hierarchy, sub-task classification), but says nothing about errors for unknown project keys, or which site is used when 'site' is omitted. That's a modest value-add on top of the annotations rather than rich disclosure.

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?

Two short sentences with zero filler, and the payload description comes first. Slight weakness: the opening is a verbless fragment ('Project details including...'), making the primary action slightly less front-loaded than a clear 'Get a project's details...'.

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?

No output schema exists, so the description carries the return-value burden, and it does identify the key returned data (issue types with hierarchy and sub-task flags). For a two-parameter read tool that is largely sufficient; only secondary project fields and failure behavior are unstated.

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 description coverage is 100%, with both projectKey and site documented in-schema including examples and the default-site fallback. The description adds no parameter semantics beyond that, so the baseline 3 applies.

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?

Names a specific resource (project) and enumerates the most useful payload fields (issue types, hierarchy level, sub-task flag), which tells an agent what it gets back rather than just 'get project'. It doesn't distinguish itself from the sibling jira_get_issue_types or jira_list_projects, so an agent comparing them still has ambiguity.

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?

'Call before creating issues in an unfamiliar project' gives a concrete triggering situation, which is real routing value. It stops short of stating when not to use it (e.g. when the project is already known or when jira_get_create_fields is the better call).

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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description contributes the cross-field precondition for 'active'/'next', which is real behavioral context, but says nothing about pagination, default maxResults, or what happens on an invalid sprint name.

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?

Two sentences, front-loaded with the resource and followed immediately by the parameter rule that governs correct invocation. Slightly lean to the point of being a fragment ('Issues in a sprint.') with no verb, but nothing is wasted.

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 6-parameter read tool with no output schema, the description covers the risky parameter but omits return shape, default paging, and the meaning of jql/site in this context. Adequate to call correctly, thin for choosing 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?

Schema coverage is only 33%, and the description compensates for the most important gap by enumerating accepted values for `sprint` (id, name, 'active', 'next') and the dependency that the last two impose on boardId/projectKey – a cross-parameter rule the schema cannot express. It still leaves maxResults, boardId, and projectKey semantics to the schema.

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?

"Issues in a sprint" names the resource and the scoping dimension, and the sprint-argument sentence makes the retrieval intent concrete. It lacks an explicit verb and never distinguishes itself from the sibling jira_search_issues, which also returns issues, so the boundary has to be inferred.

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 does give one actionable rule: 'active'/'next' require boardId or projectKey. It never says when to prefer this over jira_search_issues or when a sprint lookup should be replaced by a JQL search, so the usage guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — the default state filter is active+future — which is not in the schema, but says nothing about pagination, result caps, or ordering.

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?

Two short sentences, zero filler, with the two addressing modes front-loaded and the default filter appended as a separate clause.

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 four-parameter, no-output-schema listing tool, essentials like how results are shaped, whether pagination applies, and what happens when neither boardId nor projectKey is passed are absent. Adequate but with clear gaps.

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 only 25% (just 'site'), so the description must carry the load and largely does: it defines boardId as a board identifier, projectKey as a project's scrum boards, and specifies the default for the undocumented 'state' parameter. It stops short of clarifying mutual exclusivity or the 'all' vs 'active,future' enum distinction.

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?

States the resource (sprints) and the two distinct lookup modes (boardId for a single board, projectKey for a project's scrum boards). That distinguishes it from jira_get_boards and jira_get_sprint_issues, though it never names those siblings explicitly.

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 parenthetical '(by boardId) or (by projectKey)' implies the two entry paths, but it never states that at least one of them must be supplied nor what happens if both or neither are given. No exclusions or comparisons with sibling tools are offered.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the bar is lower. The description still adds real value by disclosing the response shape (names, target statuses, required fields) and the fact that results are scoped to 'currently available' transitions, though it says nothing about error behavior for invalid issue keys or cross-site lookup.

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?

Two sentences, zero filler: the first defines the result set, the second routes to the consuming sibling tool. Front-loaded with the primary noun phrase so the agent can stop reading early if the purpose is all it needs.

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, the description correctly compensates by naming the returned fields, and the prerequisite for jira_transition_issue is stated. Minor residual gap: multi-site ambiguity is left entirely to the schema's 'site' parameter documentation rather than being flagged in the description for a tool that is inherently site-scoped.

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 description coverage is 100%, including a clear explanation of the optional 'site' parameter (cloud id, site name, or URL) and the issueKey format, so the baseline is 3. The description contributes nothing about either parameter and adds no syntax or defaults beyond what the schema already 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?

Names a specific resource (workflow transitions) with the scope qualifier 'currently available for an issue', and enumerates what comes back (name, target status, required fields). It is immediately distinguishable from the sibling jira_transition_issue, which performs the transition rather than listing it.

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?

Explicitly states the sequencing rule — call this before jira_transition_issue — and the condition that triggers it ('if unsure of the names'). The alternative tool is named directly, so the agent needs no inference to choose.

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?

Annotations already declare this as a non-readonly, non-idempotent, non-destructive, open-world mutation, so safety is covered. The description adds genuinely new behavioral meaning: argument order is semantically significant, and link phrases are site-specific vocabulary rather than free text. It omits what happens on a duplicate link or what permissions are required.

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?

Two tight sentences, front-loaded with the core action and the reading convention, followed by the routing hint. No filler and nothing redundant with the schema.

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 five-parameter mutation with no output schema, the description covers the essential decision points: direction, phrase vocabulary, and the discovery tool. It doesn't state the return value or failure modes (duplicate link, invalid phrase), which an agent may still need to infer.

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 80%; the one undescribed parameter, linkType, is precisely the one the description compensates for by giving example phrases and pointing to jira_get_link_types. It also fixes the positional meaning of fromKey vs toKey beyond the generic 'Issue key' schema text. The optional comment/site parameters are left to the schema.

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?

States a specific verb and resource ('Creates a link between two issues') and immediately disambiguates the directional semantics with the '<fromKey> <linkType> <toKey>' reading order. An agent can distinguish it from jira_get_link_types (discovery) and jira_get_issue (read) without opening any schema.

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?

Explicitly routes the agent to jira_get_link_types to obtain the site's valid phrases, which is the main prerequisite for calling this tool. It gives worked examples of link types but never states when not to use it (e.g., existing link, cross-project restrictions).

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing further — no pagination behavior, no default for maxResults, no sense of result volume on a large site — so it earns only baseline credit.

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 tight sentence that front-loads the resource and appends the optional filter without waste.

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 three-parameter list tool this is adequate, but with no output schema the agent gets no indication of what a project record contains or whether results are truncated by maxResults. A short note on default page size would have closed the gap.

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 67%: `site` and `query` are documented in the schema, and the description's filtering clause merely restates `query`. The undocumented parameter `maxResults` is not addressed at all, so the description does not compensate for the coverage gap.

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?

States a specific verb (Lists) and resource (Jira projects) plus the optional filter scope, which clearly separates it from jira_get_project (singular lookup). It does not explicitly name that sibling, so it falls short of a 5.

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 phrase "optionally filtered by a name/key substring" implies the enumeration use case, but there is no explicit statement of when to call this versus jira_get_project (single project) or jira_list_sites (site enumeration). Usage is implied rather than guided.

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?

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so safety is covered. The description still contributes a real behavioral fact beyond them: 'Re-fetches from Atlassian' tells the agent results are live/uncached and therefore incur a network round-trip to the provider, which is not derivable from annotations. It stops short of stating auth requirements or failure behavior, so not a 5.

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

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

Two short sentences, zero filler, with the scope constraint stated before the caching note. Every clause carries information an agent would otherwise have to guess.

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 parameters, no output schema, and annotations covering the safety profile, the remaining burden is small: say what is listed and where it comes from, which it does. Nothing an agent needs in order to invoke this correctly is missing.

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 takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly makes no attempt at parameter talk, which is the right call.

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?

A specific verb ('Lists') plus resource ('Jira Cloud sites') scoped to 'this account ... through this integration'. An agent knows exactly what it returns, but the description never contrasts it with the nearby jira_select_site sibling, so the boundary is left to inference.

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 closest thing to guidance is 'through this integration', implying an account must already be connected, plus the re-fetch note implying you get fresh data. There is no explicit when-to-use, no mention of jira_select_site as the follow-up, and no stated precondition that auth must be established first.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the concrete return payload (accountId, name, email), which matters because no output schema exists; it does not, however, mention behavior when not connected or multi-site resolution.

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 sentence with no filler, front-loading the resource and immediately enumerating the returned fields. Nothing is wasted.

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 trivial, read-only identity lookup with fully documented schema and no output schema, listing the returned fields is largely sufficient. A brief note on failure when unauthenticated (vs jira_connect/jira_auth_status) would make it 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?

With one optional parameter at 100% schema description coverage, the schema already fully documents the 'site' parameter including the cloud id/site name/URL forms and the omit-for-default behavior. The description adds nothing beyond it, so baseline 3 applies.

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?

Specific verb and resource: 'Returns the Atlassian account the integration acts as', plus the exact identity fields (accountId, name, email). It is clear what it does, though it never distinguishes itself from the adjacent jira_auth_status or jira_search_users siblings an agent might confuse it with.

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?

Usage is only implied by the title/semantics ('who am I'). There is no explicit statement of when to call this versus jira_auth_status (connectivity/auth check) or jira_search_users (looking up another user), which are plausible confusions in this sibling set.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the return shape ('compact list') and the pagination continuation mechanism, which annotations cannot express. It omits the 100-result cap and default page size, though those live in 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?

Three sentences, front-loaded with the action, then examples, then paging. The examples are the longest element but each demonstrates a distinct pattern (filter+sort, current-user scoping, full-text). Minor waste in the quotation style, but nothing extraneous.

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 six-parameter read-only search with no output schema, the description covers the query language, the return compactness and the paging loop. It stops short of explaining how `format: json` and `fields`/`extra` affect the response shape, which is the main remaining gap for an agent building a call.

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 67%, and the two undocumented parameters are exactly the ones the description covers: `jql` (which has only a type and minLength in the schema) is illustrated with three concrete query examples, and `nextPageToken` (no schema description) is explained as the continuation token. `site`, `fields`, `format` and `maxResults` are left entirely to the schema, which is acceptable since they are documented there.

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?

States a specific verb and resource ('Runs a JQL query and returns a compact list'), which is enough to distinguish it from mutation siblings and from fixed-scope readers like jira_get_sprint_issues. It does not explicitly contrast with jira_count_issues or jira_search_my_tickets, which are the nearest neighbours.

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 three JQL examples imply when the tool is appropriate (arbitrary filtering, sorting, text search) and 'Use nextPageToken to continue' gives a paging cue. However, there is no explicit guidance on when to prefer this over jira_count_issues (counts only) or jira_search_my_tickets (pre-scoped), so routing between them is left to inference.

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?

Annotations already cover the safety profile (readOnly, non-destructive), and the description adds genuinely useful behavior: implicit sort order ('newest activity first') and the default scope ('open issues only'). What it omits is volume behavior — whether maxResults caps silently and whether there is pagination — which matters for a 100-row-limit search.

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?

Three short sentences, front-loaded with ownership and ordering, then defaults, then filters. No filler and nothing buried.

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 6-parameter, no-output-schema read tool, the description covers the core promise but leaves two substantive gaps: reportedByMe silently changes what 'my tickets' means, and there is no routing guidance against the very similar jira_search_issues. An agent could infer these from the schema, but not from the prose.

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?

Coverage is 67%, so the schema already documents site, status, and updatedWithin in detail. The description loosely maps to status categories, project, and recent updates but adds no format guidance, and it never mentions reportedByMe — which inverts the whole premise from 'assigned to' to 'reported by' — nor maxResults.

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?

States a concrete resource and scope: issues assigned to the connected user, ordered by newest activity. An agent knows exactly what it returns. However, it never names jira_search_issues, the general sibling that overlaps heavily, so the boundary between 'my tickets' and a general search must be inferred.

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?

'Defaults to open issues only. Filter by project, status category, or recent updates' implies the natural use case (personal triage queue), but there is no explicit when-to-use versus jira_search_issues or jira_count_issues, and no statement of when this shortcut is insufficient.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by disclosing the return payload (accountIds) and the scoping behavior of projectKey (only assignable users), though it omits pagination limits and whether results are visibility-restricted.

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?

Three short sentences, front-loaded with what the tool does, then the optional scope, then the return value. Every sentence carries distinct information with no repetition of the schema.

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 4 parameters, the description does the important work: it names the identifier returned and the intended downstream use. Minor gaps remain around result volume (maxResults default/cap) and the other fields in each user record, which an agent may need for disambiguation.

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 only 25% (site alone is documented), so the description must compensate. It explains query (name or email matching) and projectKey (restrict to assignable users), but maxResults is undocumented in both schema and description, leaving the agent without page-size guidance for a capped search.

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?

States a specific verb and resource (find Jira users by name or email), plus the output it produces (accountIds) and its downstream use (assignee). No sibling tool performs user lookup, so the tool is unambiguous without opening either schema.

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 'Returns accountIds for use as assignee' clause implies it should be run before jira_assign_issue, but that sequencing is never stated. The projectKey guidance covers one conditional case, yet there is no when-to-use/when-not rule relative to jira_myself or jira_get_project.

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?

Annotations declare a non-read-only, non-destructive, open-world operation, and the description adds genuinely new behavioral context: the setting is global ('for all tools') and durable ('persists across restarts'). It does not say what happens on an unrecognized site value or whether the current selection is validated first, which keeps it short of a 5.

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

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

Two short sentences, no waste, with the core action and the accepted input forms front-loaded and the persistence note second. Every clause carries information.

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 one-parameter configuration setter with annotations present and no output schema, the description covers what it does, its scope, and its persistence. Only error/failure behavior for an invalid site string and any auth prerequisite are unstated.

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 single parameter is already documented with examples ('acme.atlassian.net'). The description's 'by cloud id, name, or URL' restates the schema rather than adding resolution rules or precedence when the three forms conflict, so baseline 3 applies.

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?

States a specific verb and resource ('chooses the default Jira site') plus the accepted identifier forms, and the phrase 'for all tools' clarifies the global scope of the effect. It is clearly distinct from jira_list_sites or jira_connect, though it never names those siblings to make the contrast explicit.

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?

Usage is implied by 'for all tools' — an agent can infer this should be called when it needs to pin a default site before other Jira calls. But there is no guidance on prerequisites (must jira_connect run first?), whether jira_list_sites should be used to discover valid values, or how this interacts with jira_auth_status.

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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description's main added value is disclosing the optional side effects: a comment is attached and a resolution is set as part of the transition. It does not disclose failure behavior for an invalid transition name or whether the response includes the updated issue.

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?

Two sentences, zero waste, and the core action is front-loaded before the parameter detail. Nothing is repeated from the schema unnecessarily.

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 6-parameter mutation tool with a nested `fields` object and no output schema, the description covers the transition argument and optional side effects but leaves gaps: it never explains that `fields` is needed when the transition has a screen, and never points to jira_get_transitions for discovering valid values. Adequate but not 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 83% (baseline 3), but the description uniquely documents the `transition` parameter, which has no schema description at all, by explaining it accepts a transition name, a target status name, or a transition id. That is exactly the ambiguity an agent would otherwise stumble on. It adds little for comment/resolution, which the schema already describes well.

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?

States a concrete verb and resource: moving an issue through its workflow (status change). An agent can distinguish it from jira_update_issue or jira_add_comment. However, it never names jira_get_transitions, the closest sibling and the natural prerequisite, so the differentiation is implicit rather than stated.

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?

Usage is only implied by the verb 'moves an issue through its workflow'. There is no explicit direction to call jira_get_transitions first to discover valid transition names, no when-not guidance (e.g. use jira_update_issue for field edits), and no note that transitions requiring a screen need the `fields` object.

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?

Annotations already declare readOnly=false, destructive=false, idempotent=true; the description usefully corroborates the partial-update/idempotent behavior and, importantly, discloses that `labels` wholesale replaces the existing set — a destructive nuance the annotations mask with destructiveHint=false. It omits permissions requirements, error behavior for bad issue keys, and what the call returns.

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?

Three short sentences, each carrying distinct information: mutation semantics first, then the dangerous field, then the structural move case. No filler, no restatement of the title, correctly 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?

For a 16-parameter mutation with no output schema and a nested customFields object, the description covers the key traps but says nothing about the response, about how customFields interacts with typed fields like storyPoints, or about when a sibling (assign/transition) is the better route.

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 only 50% across 16 parameters. The description compensates for the highest-risk cases (labels replacement, parentKey move vs null detach), but leaves summary, priority, components, fixVersions, storyPoints, addLabels, and removeLabels undocumented in either place. That is real added value without fully closing the coverage gap.

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?

States a specific verb and resource ("Updates fields on an issue") and immediately narrows the scope with partial-update semantics. It is distinguishable from jira_create_issue and jira_transition_issue, though it never addresses the overlap with jira_assign_issue, which also appears in the sibling list despite assignee being a parameter here.

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?

"Only provided fields change" plus the explicit labels-vs-addLabels/removeLabels routing and the parentKey move/detach instruction give an agent actionable guidance on how to shape a call. It falls short of a 5 because it never states when to prefer this tool over siblings such as jira_transition_issue or jira_assign_issue, and gives no prerequisites or failure conditions.

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