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

Annotations already declare the mutation and open-world profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds real value beyond them by disclosing the return payload ({ok, commentId}) and the fact that the body renders as markdown, though it says nothing about duplicate-comment behavior or notification side effects.

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 with zero filler: action first, input format second, return shape last. Every clause carries information an agent needs before calling.

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 tool with no output schema, the description covers purpose, input format, and return shape, which is enough to invoke it correctly. Error behavior and permission requirements are the only notable omissions, and annotations partly cover the latter.

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 goes further than the schema by enumerating the supported markdown constructs (headings, tables, code fences, lists) that the body parameter accepts. issueKey semantics (the PROJ-123 pattern) are left entirely to the schema, which already handles them 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?

The first sentence gives a specific verb and resource ("Add a comment to a Jira issue"), which is unambiguous and cannot be confused with any sibling such as jcm_createIssue or jcm_editIssue. It does not explicitly name or contrast with siblings, so it lands just 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?

Usage is only implied by the purpose statement — there is no explicit when-to-use, when-not-to-use, or prerequisite guidance (e.g., required permissions or whether the issue must be open). Since no sibling tool offers a comparable commenting action, the lack of alternatives is low-risk, keeping this at a minimum-viable 3.

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 it is a non-read-only, non-idempotent, open-world mutation. The description adds useful behavioral context by explaining outward versus inward verb direction and the returned object shape, though it does not mention duplicate-link behavior or permission requirements.

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 core action and directional semantics front-loaded. The return-shape sentence is brief and informative without adding clutter.

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

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

The tool is a simple three-parameter mutation, and the description covers the action, parameter directionality, and return shape. With annotations and full schema coverage, it is nearly complete, though it omits edge cases such as duplicate links or invalid link types.

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 already well documented in the schema. The description reinforces the source/target directionality but adds little syntax or format detail beyond what the schema provides.

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

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

States a specific verb and resource: "Create a link between two Jira issues." It also clarifies the directionality of the link, which is the key semantic distinction for this 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?

The description implies usage through "Create a link," which distinguishes it from sibling tools like jcm_removeIssueLink and jcm_getIssueLinks. However, it does not explicitly state when to use this tool versus checking existing links or removing links.

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 idempotentHint=true, destructiveHint=false and openWorldHint=true; the description goes further by naming the concrete no-op triggers, enumerating failure reasons with candidate payloads, and describing both success and skipped return shapes despite there being no output schema. This is materially more than the annotations carry.

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 ordered as purpose, edge cases, error handling, return values — front-loaded and free of filler. The compact JSON-ish shape fragments convey return structure in far fewer tokens than prose would.

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 must describe return values, and it does for success, skip, and both error classes. Combined with a fully documented two-parameter schema and annotations, an agent has everything needed to call this correctly and interpret the result.

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 operational meaning the schema cannot: boardId is only needed as a retry after a multiple-scrum-boards failure, not something to supply upfront. issueKey semantics are left entirely to the schema, which is fine given its pattern example.

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 ('Add a Jira issue to its project's active scrum sprint') with the implicit scope resolution (its project's board) made explicit. Clearly distinct from siblings like jcm_editIssue or jcm_transitionIssue, which do not touch sprint membership.

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 no-op conditions (already in an active sprint, no scrum board) and a concrete recovery path tied to a specific failure reason: retry with boardId on multiple-scrum-boards, handle no-active-sprint and multiple-active-sprints manually in Jira. The agent knows both when to call it and what to do when it fails.

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 flag destructiveHint=true and idempotentHint=true, and the description adds real context on top: it uses Jira's bulk move, blocks up to 30s, and returns a taskId with status when the move fails or is still running. It stops short of saying what is lost in the conversion (field values, sub-task links, workflow state), which matters for a destructive operation.

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

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

Four tight sentences: purpose and constraint first, then the parentKey decision rule, then mechanism/timeout, then return shapes. Every sentence 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?

With no output schema, the description responsibly supplies both return shapes and the 30s blocking behavior, and notes the same-project restriction. One gap: it surfaces a taskId for still-running moves but no sibling tool in this set appears to poll that task, so recovery from that state is unclear.

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 all three parameters are already documented, including the parentKey omit/provide rule. The description largely restates that plus the same-project constraint, adding little new meaning; 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 ('Convert one or more Jira issues ... to another issue type') plus the distinguishing constraint that keys are preserved and all issues must share a project. This separates it from jcm_editIssue and jcm_transitionIssue without needing their schemas.

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 conditional guidance for the one ambiguous parameter: provide parentKey to create sub-tasks, omit it to make sub-tasks standalone. It does not name the sibling alternatives (editIssue/transitionIssue) or say when not to use this tool at all, so it stops short of 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the mutation/safety profile is covered structurally. The description adds one piece of genuinely new context – the return shape {id, title, url} – which matters because there is no output schema, but it says nothing about duplicate-creation risk on retry, required permissions, or space visibility.

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 filler, with the action stated first and the return value 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?

Adequate for a straightforward create tool whose schema is fully documented and whose annotations cover mutation semantics. However, with no output schema the return description is a terse inline list, and nothing explains what happens on a title collision or whether the created page is draft vs published – gaps an agent invoking a create operation would benefit from knowing.

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 the schema itself already explains the non-obvious bits (numeric spaceId, markdown in body, how to resolve a space key). The description adds no parameter information beyond this, 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?

States a specific verb and resource ('Create a new Confluence page'), which clearly separates it from jcm_getArticle and jcm_updateArticle among the siblings. It stops short of explicitly contrasting with those siblings, so it is clear but not fully differentiated by name.

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 when-to-use or when-not-to-use guidance is given, and no prerequisites or alternatives (e.g. jcm_updateArticle for existing pages) are named. The agent must infer the usage context entirely from the verb.

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 is a non-readonly, non-idempotent, non-destructive open-world write, so the safety profile is carried structurally. The description adds value annotations cannot: the return shape {key, url}, which matters because there is no output schema. It omits permission requirements and side effects such as notifications.

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 the action, followed by return value and then the one conditional hint. Nothing is redundant and every sentence 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?

Return value is stated despite having no output schema, and the sub-task case is covered, which an agent needs to invoke correctly given the three required parameters. Minor gaps remain around permissions and whether creating an issue triggers notifications or workflow validation.

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 five parameters are already documented in the schema, including the parentKey sub-task example. The description's parentKey note restates schema content rather than adding format or validation detail 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?

States a specific verb and resource ('Create a new Jira issue') that is immediately distinguishable from siblings like jcm_editIssue, jcm_getIssue, and jcm_createVersion. It doesn't explicitly contrast with the nearest alternative, but the verb makes the operation unambiguous.

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

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

The only usage guidance is 'For sub-tasks, pass parentKey,' which is conditional invocation advice for one parameter. There is no guidance on when to use this versus jcm_editIssue or jcm_convertIssueType, nor any note on prerequisites such as required project permissions.

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 disclose the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description needn't repeat that. It does add useful value by stating the return shape '{id, name}', which is the only source of return information given there is no output schema. However, it says nothing about permission requirements, duplicate-name behavior, or side effects.

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 core action front-loaded and the return value appended. Nothing is wasted or 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 four-parameter creation tool with full schema coverage and annotations covering the safety profile, the description supplies the missing return-shape information. It stops short of the creation-specific caveats (duplicates, required permissions, whether the version is created unreleased) that would make it fully complete.

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

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

Schema description coverage is 100%, so all four parameters are already documented with examples and a project-key pattern. The description adds no parameter-level meaning beyond the schema, which is the expected baseline-3 case when the schema does the heavy lifting.

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 and resource ('Create a new version (release) in a Jira project') and clarifies the domain term 'version' with 'release'. It is clearly distinguishable from siblings like jcm_listVersions and jcm_releaseVersion, though it never explicitly contrasts with them.

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

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

There is no guidance on when to use this versus alternatives such as jcm_releaseVersion (which presumably marks a version as released) or jcm_listVersions for checking existing ones. No prerequisites, permissions, or duplicate-name caveats are mentioned.

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?

It adds valuable operational context not in the schema or annotations, specifically noting that the 'Description' field supports markdown, which is a crucial execution detail.

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 definition is extremely concise, using two focused sentences to cover the purpose, key input format, and basic return structure.

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

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

The description is highly complete for execution, particularly since it defines the return structure ('Returns {ok, key}') which is not fully specified in 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?

Although the schema is 100% covered, the description adds semantic meaning by clarifying the expected structure ('Pass fields as {fieldName: value}') and detailing the markdown capability of the description field.

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 explicitly states the function ('Update fields on a Jira issue') and is clearly distinguishable from sibling tools like 'createIssue' or 'getIssue' by focusing on the 'update' action.

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 provides implied usage by contrasting it with creation/retrieval, but it offers no specific guidelines regarding constraints or when it should be chosen over related complex Jira API calls.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds useful return-shape context, including that body is markdown and parentId is optional, though it does not mention permissions or error 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?

Two short sentences, front-loaded with the core action and then the return fields. There is no redundant or wasted text.

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

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

For a simple one-parameter read tool with full schema coverage and complete safety annotations, the description is complete enough. Even without an output schema, it briefly documents the returned structure.

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 the only parameter pageId is already documented as a Confluence page ID. The description adds no syntax or format detail beyond the schema baseline.

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 and resource: 'Fetch a Confluence page by ID.' It is clearly distinct from siblings such as jcm_searchArticles, jcm_createArticle, and jcm_updateArticle.

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 'by ID' implies the tool is for cases where a page ID is already known, but the description does not explicitly say when to use this instead of jcm_searchArticles or other retrieval tools.

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 readOnly/idempotent/non-destructive and openWorld, so the bar is lower, and the description still adds real context: permission requirement, URL temporariness and expiry, that file bytes are not returned, and that Atlassian media redirects are handled. That is a lot of behavior an agent cannot infer from structured fields.

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?

Five tight clauses with zero filler, front-loaded on what the tool resolves and what it returns before the caveats. 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?

With no output schema, the description compensates by describing the returned object fields and the temporary flag, plus permission and expiry caveats. An agent has everything needed to call it and handle the result.

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

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

Schema coverage is 100%, so baseline is 3; the description adds provenance meaning by tying the ID to jcm_getIssue attachments, telling the agent where to obtain a valid value. It does not restate the numeric pattern, but that is already in 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 ('Resolve an attachment ID') and names the source tool (jcm_getIssue) and the return shape. No sibling tool does attachment-link resolution, so the agent can tell this apart from all 22 siblings instantly.

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 clear preconditions ('Requires the server's Jira account to have permission to view the attachment') and post-call guidance ('download the temporary URL without Jira credentials using a local download tool; request a fresh URL after expiry'). It does not name an alternative tool or state when not to use it, but the workflow 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description earns extra credit by enumerating the returned fields (accountId, displayName, email, active) in the absence of an output schema; it does not cover auth-failure behavior or whether email may be hidden by privacy settings.

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

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

A single front-loaded sentence with no filler; the resource and the return contract are delivered immediately with zero 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 zero-arg read with no output schema, listing the returned fields makes the tool callable without guesswork. The only shortfall is the unstated boundary versus jcm_lookupUser and the absence of any auth-prerequisite note.

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 the baseline is 4. The description correctly implies no input is needed by framing the call around the authenticated session.

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 ('Returns') plus a precisely scoped resource ('the authenticated Atlassian user's account info'), which implicitly separates it from jcm_lookupUser, the sibling that looks up arbitrary users. It stops short of naming that sibling explicitly, so the differentiation requires the agent to infer 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?

Usage is implied rather than stated: 'authenticated user' signals the self-lookup case. There is no explicit guidance on when to pick this over jcm_lookupUser, nor any note that it requires an active authenticated session.

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, idempotent, non-destructive, open world), yet the description adds substantive behavior the annotations cannot: the exact lean field set returned, the updatedJql minute-flooring and at-least-once/dedupe semantics for polling, and the requirement of Jira auth for attachment content URLs. These are precisely the non-obvious traits that prevent misuse in a polling loop.

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 action is front-loaded in the first clause, then the return shape is enumerated. The second half is a long run-on enumeration, but since no output schema exists each listed field earns its place; it could be tightened with a compact list rather than parenthetical nesting.

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 takes on the return-contract burden and discharges it fully, including nullability (assignee/reporter, updatedJql), date formats, and the auth caveat on attachment URLs. Nothing an agent needs to call this correctly or interpret the response 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% and the single issueKey parameter already carries its own description and regex pattern, so the schema does the work here. The description only restates "by key" and adds no format, casing, or failure-mode detail beyond the schema's pattern.

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?

"Fetch a Jira issue by key" gives a specific verb and resource with a clear scope qualifier (single issue, addressed by key), which implicitly separates it from jcm_searchIssues and jcm_getIssueChangelog. It stops short of naming any sibling explicitly, so the agent must infer the boundary rather than being told 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?

Usage is only implied: the phrase "by key" suggests this is for when you already know the issue identifier and search is for when you don't. There is no explicit statement of when to prefer jcm_searchIssues, no prerequisite for obtaining a key, and no note on whether this tool errors on missing keys.

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 read-only/idempotent/non-destructive, and the description goes well beyond them: it discloses result ordering, a hard cap of maxResults, the tie-breaking rule that entries sharing the last timestamp stay together, and the truncation flag. Without an output schema, that payload and paging disclosure is doing real work.

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 tight sentences, front-loaded with purpose, then return shape, then the paging rule. No filler; every clause carries either contract or recovery 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?

With no output schema, the description supplies the full return shape (entries, items, truncated) and the exact continuation procedure, so an agent can both interpret and page results without guessing. Nothing material is left out for a 3-parameter read 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 100%, so the baseline is 3, but the description adds semantic detail the schema lacks: `since` is strictly-after, and `maxResults` selects the oldest matches with same-timestamp grouping. The only gap is that it does not restate the issueKey key format, which the schema already covers.

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 ("Get a Jira issue's field-change history") plus an ordering guarantee ("oldest first") that immediately distinguishes it from sibling jcm_getIssue and jcm_editIssue. An agent can tell this is a read of audit-style change records rather than current field values.

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 operational guidance for the paging loop: "if truncated, call again with since = last returned created," which is the main decision an agent faces here. It stops short of naming when to prefer jcm_getIssue or which sibling answers 'current state' questions, so it is clear-context but not full when/when-not routing.

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, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds useful return structure, a flat array with optional inwardIssue/outwardIssue fields, which is valuable because there is no output schema.

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

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

The description is two short sentences, front-loaded with the core action and followed by the return shape. Every sentence carries useful information without redundant prose.

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 operation with one fully documented parameter and rich annotations, the definition is complete enough to select and invoke correctly. The missing output schema is compensated by the description's explicit return shape.

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 single required parameter, issueKey, is fully documented in the schema with a pattern and example. The description adds no parameter-specific detail beyond the schema, so the high-coverage 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 uses a specific verb and resource, 'Get all links for a Jira issue,' and states the return shape. This clearly distinguishes it from sibling mutation tools like jcm_addIssueLink and jcm_removeIssueLink, even without naming them.

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 explicit when-to-use, when-not-to-use, or alternative routing guidance. Usage is implied by the purpose: retrieve link data for a known issue key, while sibling add/remove tools handle mutations.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description contributes the return payload format ([{id, name}]), which is valuable since there is no output schema, but it omits that available transitions vary by workflow state and user permissions.

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, purpose front-loaded, return shape given immediately after. Zero 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 one-parameter read tool with no output schema, purpose plus return shape is nearly sufficient. The only missing element is a note that available transitions depend on the issue's current workflow status.

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 issueKey parameter is fully documented with an example and pattern in the schema. The description adds nothing about the parameter, 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 ('Get') and resource ('available workflow transitions for a Jira issue') and discloses the return shape. It is implicitly distinguishable from the sibling jcm_transitionIssue (which performs a transition), 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?

Usage is only implied: an agent can infer this is a prerequisite lookup before jcm_transitionIssue, but the description never states when to call it, when not to, or what to do with the returned ids. No alternatives are named.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value beyond that by disclosing the return shape [{id, name, released, releaseDate}], which annotations cannot convey; it omits any note on pagination or empty-project 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?

Two short sentences, front-loaded with the action and scope, then the return shape. Nothing is wasted and 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 one-parameter read tool with no output schema, the description supplies the return structure and scope, which is nearly everything an agent needs. A note on pagination or ordering would make it fully complete.

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

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

Schema coverage is 100% and the single projectKey parameter is documented with a pattern and example in the schema. The description adds no formatting or meaning beyond that, so the schema carries the semantic load and 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 (List) and resource (versions) scoped to a Jira project, and distinguishes itself by verb from siblings like jcm_createVersion and jcm_releaseVersion. It stops short of explicitly naming those siblings, but the read-vs-write verb makes the distinction obvious.

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: it is the read path for version metadata on a project, contrasted implicitly with createVersion/releaseVersion. There is no explicit when-to-use, prerequisites, or named alternative, so an agent must infer the routing.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new information by disclosing the return payload ("{id, key, name}"), which matters because no output schema exists; it omits error behavior for an invalid key.

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 purpose and followed by the return shape. Every clause carries information; nothing is redundant or padding.

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 single-parameter lookup with full annotation coverage, the description covers purpose, consumer, and return fields. The only meaningful gap is what happens when the space key does not exist (error vs. empty result), which an agent would otherwise have to discover by trial.

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 there is only one required parameter whose meaning ("Confluence space key") is already spelled out in the schema. The description restates the concept without adding format or validation semantics beyond what the schema provides, 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 ("Resolve") and resource ("a Confluence space key to its numeric ID"), which is a narrow, unambiguous operation that no sibling tool performs. It also names the downstream consumer (jcm_createArticle), so an agent immediately knows the result's role.

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?

"for use with jcm_createArticle" gives a clear positive trigger for calling this tool. There is no explicit when-not or note about what to do if the key is already known, but the usage context is concrete rather than implied.

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, idempotent, and openWorld, so safety is covered. The description adds genuine value by disclosing the return shape ([{accountId, displayName, email, active}]) despite there being no output schema. It does not say what happens when no user matches, which keeps it from 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 with zero filler; the lookup action is front-loaded and the return contract follows immediately.

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 lookup with no output schema, the description covers purpose and return fields, which is what an agent needs to call it. The only meaningful gap is the no-match/empty-result 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 coverage is 100% and the single email parameter is documented with format: email, so the schema does the heavy lifting. The description only restates 'by email address' without adding matching semantics (exact vs partial, case sensitivity).

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 (look up) and resource (Jira user) with the key selector (by email address), which implicitly separates it from jcm_getCurrentUser. It does not name any sibling explicitly, so it stops short of full differentiation.

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

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

Usage is implied by 'look up a user by email address' — an agent can infer this is the tool for resolving an email to an accountId. However, there is no explicit guidance on when to prefer this over jcm_getCurrentUser, and no mention of failure behavior or 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 destructive, idempotent, open-world, and non-read-only behavior. The description adds the return shape {ok, id, name}, but does not add further context on permissions or side effects beyond annotations; it is consistent with them.

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 action and followed by the return shape. No wasted words.

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

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

For a simple mutation with rich schema and annotations, the description supplies the return shape that would otherwise be missing without an output schema. It could mention error or already-released behavior, but annotations cover idempotency.

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 both parameters are fully documented in the schema. The description adds no parameter semantics beyond what the schema provides, making 3 the appropriate baseline.

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 ('Mark ... as released') and resource ('Jira version'), clearly distinguishing it from siblings like createVersion and listVersions.

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 guidance, prerequisites, or alternatives are given. The action implies releasing an existing version, but the agent must infer the context.

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, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds the return contract ({ok, linkId}), which the annotations cannot supply, but does not restate irreversibility or failure 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?

Three short sentences: action, prerequisite, return value. Nothing is redundant and the operative verb is 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?

There is no output schema, and the description compensates by naming the return fields. For a one-parameter destructive tool whose safety hints come from annotations, only edge cases (what happens on a missing/already-deleted link ID) 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 100% and the single linkId parameter is documented with its source (jcm_getIssueLinks) and a numeric pattern. The description repeats that sourcing hint but adds no new syntax or format detail, matching the baseline-3 case.

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 ('Delete an issue link by its ID') that clearly separates it from the sibling addIssueLink and from getIssueLinks, which only reads. An agent can pick this tool without inspecting the 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 jcm_getIssueLinks to source the link ID, which is the main prerequisite for calling this tool. It stops short of stating when-not-to-use (e.g., prefer editIssue for changing links), so it is slightly under 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine value beyond that by disclosing the return payload shape ({id, title, space, spaceKey, lastModified}), which matters because there is no output schema. It omits any note about auth requirements or what happens when the 25-result cap is hit.

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. The query mechanism and the resource are front-loaded, followed immediately by the return shape.

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 2-parameter read tool with full annotation coverage, complete schema descriptions and an inline return-shape disclosure, the definition gives an agent everything needed to invoke it. The remaining gaps are pagination behavior past the 25-item cap and explicit routing versus sibling lookup/search tools.

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%: the cql parameter carries a concrete example query and maxResults documents default and bounds. The description adds nothing about parameter semantics beyond that, so the baseline 3 applies. No enum or format hints are added for CQL syntax beyond the schema example.

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 ("Search Confluence pages") plus the query language used (CQL), which separates it from jcm_getArticle/jcm_createArticle/jcm_updateArticle by naming the retrieval-by-query behavior. It does not explicitly say how it differs from sibling search tools like jcm_searchIssues, so it stops short of full differentiation.

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

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

Usage is only implied: an agent can infer this is the tool for finding pages when it lacks an ID, whereas jcm_getArticle takes a known identifier. There is no explicit when-to-use, when-not-to-use, or named alternative for cases where CQL is unavailable or where space listing (jcm_lookupSpace) is the better path.

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

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

With no output schema, the description discloses the exact return envelope {total, issues:[{key, summary, status, assignee, updated, updatedJql}]}. It goes further by explaining updatedJql's minute-flooring in the user's timezone and warning that polling is at-least-once so callers must dedupe — behavioral context the readOnly/idempotent annotations cannot convey.

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 tight sentences, all load-bearing: purpose first, then return shape, then the polling semantics. No filler, and the most decision-relevant facts (return shape, dedupe) are 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?

Compensates for the missing output schema by fully specifying the return structure, and covers the subtle polling-increment semantics unique to this tool. Combined with 100% schema coverage of maxResults/jql, an agent has everything needed to call and consume it correctly.

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

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

Schema coverage is 100%, so `jql` and `maxResults` are already documented in the schema. The description reinforces JQL usage and shows a query template (key/updated), which adds modest value but no parameter-level detail beyond the structured data. 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: 'Search Jira issues using JQL'. The verb 'search' plus the JQL mechanism distinguishes it implicitly from jcm_getIssue (single fetch) and jcm_searchArticles (different resource), but it never names a sibling or scoping rule 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?

Provides a concrete usage pattern for polling with `key = X AND updated > "<updatedJql>"` and warns about at-least-once semantics requiring dedupe. It does not say when to prefer this over jcm_getIssue for a single known key, so usage is implied rather than fully 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 destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that by stating the return shape ({ok, key, transitionId}), which no output schema provides, though it stops short of saying what side effects a transition triggers (notifications, workflow post-functions, required fields).

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 the action, then the prerequisite, then the return shape. Every sentence carries distinct information and none is padding.

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 mutation with no output schema, the description supplies the action, the prerequisite and the response shape, which is enough to call it correctly. It could add one line on what a failed or partial transition looks like, but the gaps are minor.

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 both parameters carry their own descriptions plus patterns (issue key format, numeric transition ID). The description's mention of transition IDs sourced from jcm_getTransitions only repeats what the schema's parameter description already says, 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: 'Move a Jira issue to a new workflow state.' That is clearly distinct from the read-only siblings (jcm_getIssue, jcm_getTransitions) and from the field-editing sibling jcm_editIssue, so an agent can pick it without opening a 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?

'Use jcm_getTransitions first to get valid transition IDs' names the prerequisite tool and the condition that requires it, which is the single most important routing decision for this call. Nothing about sequencing 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 declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the risk profile is covered. The description adds real value by disclosing the version auto-increment behavior and the return shape {ok, id, version}. It does not disclose whether body is a full replacement or merge, nor how concurrency/stale-version failures surface, which is the key behavioral detail an agent needs before calling a destructive page update.

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 purpose, then the critical precondition, then the return shape. No filler sentences.

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?

Return-shape disclosure compensates for the absent output schema, and the version precondition is stated. However, a destructive, open-world mutation should also tell the agent that title/body fully overwrite existing content and how to recover from a version mismatch.

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 all four parameters are already documented. The description's '(auto-incremented)' note reinforces the version parameter's mechanics but adds nothing about body replacement semantics beyond the schema's markdown hint.

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 ('Update a Confluence page'), which is immediately distinguishable from jcm_getArticle and jcm_createArticle. It does not explicitly name those siblings, but the mutating intent is unambiguous.

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

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

The version sentence implies the read-then-update workflow (get current version, then update), but the description never says to call jcm_getArticle first or what to do on a version conflict. Usage is only implied, not directed.

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