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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the useful detail that the comment is authored 'as the authenticated user' (implying auth attribution), but says nothing about where the comment lands, whether it is editable/deletable afterwards, or what permissions are needed.

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 and no redundancy. Its brevity is efficient, though it borders on under-specification for a mutation tool with undocumented parameters.

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 and no parameter documentation, so the description carries the full burden of explaining inputs and results — and it does not. For a write tool whose required payload is a raw storage-format body, failing to explain format expectations leaves the agent likely to call it incorrectly.

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 0% and the description only vaguely gestures at contentId via 'content item'. The critical 'bodyStorage' parameter is completely unexplained — an agent has no way to know from either the schema or the description that it expects Confluence storage-format XHTML.

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 ('Add') and resource ('comment') scoped to a Confluence content item, which clearly separates it from the sibling read tools like confluence_list_comments. It does not, however, explicitly mention the sibling it complements (list_comments) or distinguish header/footer vs. inline comments.

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

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

There is no guidance on when to use this versus confluence_rest, confluence_update_page, or when commenting is inappropriate. An agent must infer the use case entirely from the name.

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, openWorldHint=true, destructiveHint=false. The description adds real value beyond that by mandating Confluence Storage Format for bodyStorage and explaining the parent/child effect of parentPageId. It does not cover what happens on duplicate titles, required permissions, or 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, front-loaded with the action, and every sentence contributes new information: the scope, the format constraint, and the optional hierarchy behavior. 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 create/mutation tool with no output schema and only default annotations, the description covers format and hierarchy but omits permissions, duplicate-title behavior, and any indication of the created page identifier an agent would need for follow-up calls.

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 0%, so the description must carry parameter meaning. It does well for bodyStorage (Storage Format, HTML plus macros) and parentPageId (child-page creation), but says nothing about spaceKey format or title constraints such as uniqueness — two of four parameters remain undocumented.

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 page in a space') and immediately scopes the content format. An agent can tell this is the creation counterpart to confluence_update_page without opening the schema, though the description 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 implied by 'Create' and the parentPageId hint, but there is no explicit when-to-use versus confluence_update_page or when-not guidance, and no mention of prerequisites such as permissions on the target space.

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?

The annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description reinforces destructiveness and adds that the operation may delete or archive depending on server API and permissions, but it omits irreversibility, child-page impact, and required permission details.

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?

It is two short sentences with the destructive warning front-loaded. The second sentence is concise, though it partly repeats what the annotations already state.

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 mutation tool with one undocumented parameter and no output schema, the description is thin. It should clarify what is destroyed, whether descendant pages are affected, and what conditions trigger delete versus archive.

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 sole parameter, contentId, is not mentioned in the description, and schema description coverage is 0%. The agent gets no added meaning about what ID is required or what content types are acceptable.

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: delete or archive a Confluence content item. It is clear enough to distinguish this from read-oriented siblings, though it says 'content item' rather than matching the page-specific title and sibling set.

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 not explain when to use this tool versus alternatives such as updating or archiving through another path. The phrase 'according to the server's REST API and permissions' hints at preconditions but gives no actionable 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing beyond restating the read, and does not mention authentication prerequisites or that an unauthenticated call will fail.

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 zero filler, correctly sized for a trivial zero-argument lookup.

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 is the only place an agent could learn what the returned user object contains (id, username, display name, email), and it omits that entirely. For a retrieval tool whose main value is its return shape, this is a meaningful 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?

The tool takes no parameters and has 100% schema coverage, so there is nothing for the description to disambiguate. Baseline 4 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 states a specific verb and resource ('Return the authenticated Confluence user'), so an agent immediately knows what the tool does. It does not explicitly distinguish itself from the sibling jira_get_current_user, but the naming and wording make that separation 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?

There is no explicit when-to-use guidance or mention of alternatives. For a zero-parameter identity lookup the correct usage is strongly implied, but the description never says to use it to resolve the acting user's identity before other Confluence 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — the default expansions returned — which is beyond what annotations say. It omits error behavior, auth requirements, and what happens when an expanded field is unavailable, so it is additive but thin.

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 zero filler, front-loaded with the verb and resource, then the scope, then the return content. 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?

With no output schema, the description does useful work by enumerating the default returned sections. However, for a tool whose only real lever is the expand array, leaving that parameter entirely unexplained leaves a gap an agent will hit as soon as it wants anything beyond the defaults.

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 0%, so the description carries the full burden and only partly delivers. "by ID" effectively explains contentId, but the phrase "by default" gestures at expand without ever naming it, listing accepted values, or explaining how it changes the response. Half the parameters remain undocumented in both schema and description.

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 ("Read a Confluence content item") scoped by "by ID", which separates it from search/list siblings. It also names the default returned sections (body, version, space, ancestors), so an agent knows what it gets. It does not name a sibling explicitly, but the by-ID framing is clear enough.

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 "by ID" phrasing signals this is the tool for retrieving a known page rather than searching. There is no explicit guidance on when to prefer confluence_search, when to use confluence_rest, or any prerequisite (IDs, permissions). 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=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description contributes only the pagination note and says nothing about ordering, total counts, or what happens with an invalid contentId.

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 purpose front-loaded and zero filler. It is efficient, but the second sentence spends its space on the least ambiguous parameters rather than the undocumented ones.

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 4 parameters at 0% schema coverage and no output schema, the description should at minimum explain contentId and expand. As written, an agent cannot tell what identifier format is expected or what expand accepts, leaving real gaps for a listing 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 description coverage is 0%, so the description must carry parameter meaning, but it only mentions start and limit as pagination controls and leaves contentId and expand entirely unexplained. Defaults, the limit of 100, and what expand values are valid are absent.

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 ('List attachments on a Confluence content item'), which is enough to separate it from siblings like confluence_list_comments and confluence_get_page. It stops short of naming the sibling it complements, so it lands just below 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?

There is no guidance on when to use this versus confluence_get_page (which may also expose attachments) or confluence_rest, and no prerequisites such as needing a valid content id or read permissions. Usage is only implied by the purpose statement.

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 structurally. The description adds essentially nothing behavioral beyond that: no mention of ordering, whether replies/inline comments are included, whether pagination results carry a total/next link, or whether extra fetches are needed for full comment bodies.

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 operation front-loaded and zero filler. The brevity is efficient, though the second sentence spends its space on pagination mechanics rather than the undocumented parameters.

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 tool with 0% schema coverage and no output schema, the description is too thin: expand is unexplained and the return shape of a comment is not described. An agent could call it, but not confidently or optimally.

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 0%, so the description must carry the load, yet it only alludes to start and limit as pagination controls. The required contentId is only vaguely implied by "a content item," and expand — an array whose valid values are entirely undiscoverable — is never mentioned at all.

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 ("List comments on a content item"), which is clear enough to distinguish it from confluence_add_comment or confluence_get_page. However, it never names the near-sibling jira_list_comments or otherwise explains scope differences across the two comment-listing tools.

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 "Use start and limit for pagination," which is a parameter mechanic, not a when-to-use rule. There is no statement of prerequisites, no indication of when to prefer confluence_rest or confluence_search, and no exclusion of cases where this tool is the wrong choice.

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's only added behavioral fact is the visibility/authorization scoping, which is useful but thin; nothing is said about ordering, default result volume, or how pagination terminates.

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 no filler, and the scoping constraint is front-loaded before the pagination note. Sizing is right for the complexity, though the space could have been spent on the undocumented parameters.

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?

Five parameters at 0% schema coverage, no output schema, and no annotations explaining the data model — the description covers only two of five inputs. For a list tool whose filtering options (type, status, expand) materially change results, that is a substantial omission.

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 0% across 5 parameters, so the description must compensate and it largely does not. It explains only start and limit; type, expand and status remain completely undocumented anywhere, leaving an agent to guess at their accepted values.

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 ("List spaces") plus a scope qualifier ("visible to the authenticated user") that tells the agent results are permission-filtered. Siblings like confluence_search and confluence_get_page are obviously different operations, so no explicit differentiation is needed.

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 concrete pagination guidance (start and limit), which is genuinely actionable. However, it never says when to reach for this tool versus confluence_search or confluence_rest for space discovery, and there are no exclusions 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 flag destructive=true, openWorld=true, and readOnly=false, so the safety profile is largely covered. The description adds useful operational context: write/delete calls act as the configured user, and credentials must never be placed in apiPath, query, or body. It does not describe response or error behavior, keeping 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?

The description is four concise sentences with no wasted text. Scope, examples, method support, and security constraints are front-loaded and easy to scan.

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 generic, open-world, destructive REST passthrough with no output schema, the description covers endpoint scope, method support, credentials handling, and acting-user identity. It does not explain response shape, error behavior, pagination, or when specialized siblings should be used instead, leaving meaningful gaps for a high-complexity 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 description coverage is 0%, so the description must carry parameter meaning. It explains apiPath well, including that it is relative to /rest/ and giving examples, and it restates the supported methods from the enum. However, query and body semantics remain thin: body is untyped and query structure is only implied by the schema, so key usage details are missing.

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

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

The description clearly states a specific action: call any JSON Confluence Server/Data Center REST endpoint on the configured host. It gives concrete apiPath examples under /rest/, making the tool's scope understandable. It does not explicitly distinguish itself from the many specialized Confluence siblings, so a 4 rather than 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 implied by the statement that it can call any JSON REST endpoint and supports GET/POST/PUT/PATCH/DELETE. However, it does not say when to prefer this generic tool over dedicated siblings like confluence_get_page, confluence_search, or confluence_create_page. The security warning and acting-user note give context, but routing guidance is missing.

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 the safety profile is known. The description adds that search uses CQL and supports pagination, but does not disclose result format, rate limits, permission requirements, or what happens with invalid CQL.

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 tight sentences with no wasted wording. The core purpose is front-loaded, followed by a useful pagination note.

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 zero parameter descriptions, the definition leaves important gaps: it does not explain CQL syntax, what expand does, or what the search response contains. An agent can make a basic call but lacks enough context to use the tool fully or interpret results 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 0%, so the description must compensate, but it only mentions start and limit for pagination. The required cql parameter's format and the expand parameter's purpose are left undocumented.

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: search Confluence content including pages, blog posts, and comments using CQL. It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools like confluence_get_page or confluence_rest.

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 a note about using start and limit for pagination. There is no explanation of when to choose this search tool over alternatives such as confluence_rest, confluence_get_page, or confluence_list_comments.

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 declare it is a non-read-only, non-destructive, open-world write; the description adds the genuinely useful operational fact that the server reads the current version and increments it, which changes how the agent must call it. It stops short of saying what happens on a version mismatch (error vs. silent overwrite) or whether bodyStorage replaces the entire body.

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, zero filler, and the most important capability statement is front-loaded before the version-increment and concurrency 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?

For a mutation tool with no output schema and no schema descriptions on any of its five parameters, the description covers the highest-risk concern (version conflicts) but leaves contentId identification, versionMessage purpose, and body replacement semantics 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 description coverage is 0%, so the description must carry parameter meaning, and it covers three of five: title, bodyStorage (storage-format body), and expectedVersion's concurrency guard. contentId and versionMessage are left entirely unexplained, and bodyStorage's replace-vs-merge semantics are unstated.

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 page's title and/or storage-format body'), and the mention of storage-format narrows the scope meaningfully. It does not explicitly name confluence_create_page or confluence_delete_page as alternatives, but the verb makes the boundary obvious against its CRUD siblings.

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 guidance is limited to one conditional: set expectedVersion to avoid overwriting a page that changed since you read it. There is no explicit statement of when to use this versus confluence_create_page, whether an existing read is a prerequisite, or what permissions are needed.

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 a non-destructive, open-world write operation. The description adds useful auth context by saying the comment is added as the authenticated Jira user, but it does not explain permissions, success behavior, or return value.

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 wasted words. The action and actor are stated 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 simple two-parameter mutation, the description plus annotations cover the core action and safety profile. However, with no output schema and undocumented parameters, it leaves some gaps around expected inputs and response 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 0%, so the description must carry parameter meaning. It only implies issueKey and body through 'issue' and 'comment'; it does not explain the expected issue key format or comment body constraints.

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: add a comment to a Jira issue. It is clearly distinguishable from list-comments siblings, though it does not explicitly compare with confluence_add_comment or jira_add_worklog.

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 implies when the tool is relevant by naming the action, but gives no explicit guidance on when to use it versus jira_list_comments, jira_add_worklog, or confluence_add_comment. No prerequisites or exclusions are 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?

The annotations already declare this is a non-read-only, non-destructive, open-world operation. The description adds useful context that typeName must be available in the specific Jira instance, but it does not explain permission requirements, duplicate-link behavior, or directionality.

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 compact sentences with no wasted words. The core action is front-loaded, followed by the only specific guidance it provides.

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 mutation tool with four parameters and no schema descriptions or output schema, the description does too little. Annotations cover the safety profile, but the description does not explain inward/outward issue direction or the comment parameter, which are necessary for correct invocation.

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 0%, so the description must compensate. It explains typeName with examples like Blocks or Relates, but it says nothing about inwardIssueKey, outwardIssueKey, or the optional comment parameter, leaving critical directionality semantics undocumented.

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 gives a specific verb and resource: "Create an issue link." This clearly distinguishes it from siblings such as jira_add_comment or jira_add_worklog, though it does not explicitly name alternatives.

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 when to use the tool by stating it creates an issue link, and it gives guidance on choosing a valid typeName. However, it does not explicitly say when to use this versus other Jira tools or mention any exclusions.

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

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

The annotations already declare this is a non-read-only, non-destructive, open-world mutation, and the description adds no further behavior: it doesn't say what permissions are required, whether the issue must exist, whether the log can be edited/removed afterward, or what a failed call looks like. The duration/date syntax note is really parameter guidance, so it does not compensate on the behavioral side.

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, the action stated first and the format constraints immediately after. Nothing is padded or 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 simple 4-parameter mutation with no nested objects this is close to adequate, but with no output schema the description should still indicate what comes back (e.g. the created worklog/ID) and any preconditions such as time-tracking being enabled on the project.

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 0%, so the description has to carry all four parameters. It usefully pins down the two ambiguous ones (timeSpent in Jira duration syntax, started as ISO date-time) but says nothing about issueKey or the optional comment 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?

States a specific verb+resource: recording work (a worklog) against an issue, which is distinguishable from siblings like jira_add_comment or jira_update_issue. It does not explicitly name an alternative, so it stops 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 — you call it when you need to log time. There is no statement of when not to use it, no prerequisites (e.g. worklog permissions), and no routing to a sibling such as jira_update_issue or jira_add_comment for non-time notes.

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, openWorldHint=true, and destructiveHint=false, so the mutation and safety profile is clear. The description adds that required fields may vary by configuration, but does not describe permissions, side effects, or the created issue response. It is consistent with annotations and adds modest context.

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 key parameter instruction. There is no redundant 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?

The tool has a complex free-form nested fields object, no output schema, and no parameter descriptions in the schema. The description gives only a minimal hint about required subfields and says nothing about the return value or field formats, leaving an agent likely to need external Jira knowledge to call 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 0%, so the description must carry parameter meaning. It usefully names project, issuetype, and summary within the fields object, but with one arbitrary nested object, it does not explain field formats, allowed values, or how project/issuetype should be identified.

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 clear verb and resource: 'Create an issue.' This distinguishes it from sibling mutation tools like jira_update_issue and jira_delete_issue. It stops short of explicit sibling differentiation, so it is clear but not exceptional.

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

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

The description gives no guidance about when to use this tool versus alternatives such as jira_rest or jira_update_issue. It only tells the agent to provide the fields object, which is parameter guidance rather than usage 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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description still adds real value by stating the deletion is permanent (irreversible) and permission-dependent, which annotations do not encode. It omits the subtask side effect, which is the main unaddressed behavioral risk.

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 padding, and the destructive/permanent nature is front-loaded before the caveat. 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?

For a destructive, no-output-schema tool the description covers the essential warnings (permanent, permission-gated), which is roughly minimum viable. It falls short on the subtask behavior — an agent cannot tell whether deletion fails, cascades, or silently drops children — and gives no hint about error conditions when permissions are insufficient.

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 0% schema description coverage across two parameters, the description carries the full burden and adds nothing: issueKey is never mentioned and deleteSubtasks — a default-false flag that determines whether child issues are also destroyed — goes entirely unexplained in both schema and description. That is the single most consequential parameter for this tool and it is undocumented.

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 ("delete an issue") and qualifies it with "Permanently," which distinguishes it from state-changing siblings like jira_update_issue or jira_transition_issue. It never names a sibling explicitly, so 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 implied by "permanently delete" — an agent can infer this is the tool for irreversible removal rather than for closing or transitioning an issue. However, there is no explicit when-to-use, no exclusion (e.g., "use jira_transition_issue to close instead"), and no stated prerequisite about permissions beyond a vague mention.

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 openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: the Jira server and PAT come from the MCP process's private environment, which tells the agent it must not supply credentials and that results depend on the server's ambient configuration.

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, the core action front-loaded, and the credential-source note placed second where it belongs as supplementary context. Nothing redundant.

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 is the only place the return value could be characterized, yet it says nothing about what fields come back (account ID, display name, email) or whether the response is null if auth fails. For an otherwise trivial tool this is a minor but real 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?

Zero parameters, so the baseline is 4. The description also implicitly confirms no arguments are accepted, matching the empty 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 precise verb and resource: "Return the authenticated Jira user." It is unambiguous and distinguishable from the Confluence analogue of the same name and from the many Jira read tools in the sibling list.

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: a zero-parameter identity lookup whose purpose (who am I on this server) is self-evident. It never states when to prefer it over, say, jira_search_issues with a username filter, or that it is useful as a precondition check before writes.

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 only that exactly one issue is returned, and says nothing about error behavior for an unknown key or about the shape/verbosity of the returned 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?

A single front-loaded sentence with no redundant restatement of the title; every word contributes.

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 0% parameter description coverage, the description should explain what 'expand' and 'fields' do and roughly what comes back, but it does neither. For a 3-parameter read tool this leaves meaningful 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 0% for 3 parameters, and the description only implies the meaning of issueKey. The 'expand' and 'fields' parameters, which materially change the response, are undocumented in both schema and description.

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 ('Read one issue') and clarifies the identifier forms (key or numeric ID), which separates it from the sibling jira_search_issues and the mutation tools like jira_update_issue. It stops short of naming an alternative, so a reader must infer the single-vs-list distinction.

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 guidance on when to use this versus jira_search_issues (lookup by known key) or jira_rest (arbitrary endpoints). The agent has to infer the situation from the purpose line 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered without description help. The description adds one real behavioral fact — the Jira Software installation dependency — but says nothing about visibility rules, pagination, or how results are ordered.

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 operation and followed by the hard prerequisite. There is no redundant or filler text; the sparseness is a completeness problem, not a conciseness one.

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 list endpoint with four entirely undocumented parameters, no output schema, and no pagination guidance, the description is too thin. An agent can see the tool lists boards but cannot tell how to filter, page, or interpret visibility scoping from the definition alone.

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 0%, so the description carries the full burden of explaining the four parameters, and it explains none of them. It never mentions that the call can be filtered by 'name' or 'projectKeyOrId' or that 'startAt'/'maxResults' control pagination, so an agent must infer everything from bare property names.

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 ('List ... Jira Software boards') with a scope qualifier ('visible'), so the agent knows exactly what resource is returned. It does not distinguish itself from the related jira_list_sprints or explain what a board contains, but the core purpose 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 description gives a prerequisite ('Jira Software must be installed'), which is genuinely useful context, but offers no when-to-use guidance, no exclusions, and no pointer to related siblings like jira_list_sprints. Usage is only implied by the verb 'List'.

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's one addition, that only comments visible to the authenticated user are returned (permission-based filtering), is genuinely useful context. It omits result ordering and pagination behavior, which matter given the startAt/maxResults params.

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 no filler, so it is perfectly concise. The terseness crosses into under-specification, though: it is front-loaded but has nothing after the first clause to earn its brevity.

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 paginated list tool with no output schema, the description should indicate the shape of returned comments and how paging works. Neither is present, and with 0% param coverage the agent is left to infer pagination semantics entirely from schema defaults.

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 0% and the description mentions none of the three parameters. issueKey, startAt, and maxResults are documented only by type and default values in the schema; the description adds no meaning about what issueKey identifies or how paging should be driven. With zero coverage the description is expected to compensate and does not.

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 verb and resource ('List comments') plus a scoping qualifier ('visible to the authenticated Jira user'), which is more than a pure restatement of the title. However, it never distinguishes itself from nearby siblings like jira_get_issue (which may also surface comments) or jira_add_comment, so the agent must infer the boundary itself.

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 when-to-use guidance: no mention of when to prefer jira_get_issue vs this tool, no prerequisite that an issueKey must be known, and no exclusions. The only implied usage is that this is the read path for comments, which an agent could guess 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that results are limited to 'visible' projects and are paginated; it says nothing about result volume, ordering, or what visibility entails for 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?

A single front-loaded sentence with no filler. It is efficient, though its brevity is achieved by omitting needed detail rather than by disciplined editing.

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 three-parameter tool with no output schema and zero schema coverage, the description leaves the filtering parameter and pagination contract undefined, and does not describe the returned project shape. Not enough for an agent to call it confidently beyond the trivial no-arg case.

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 0%, so the description must compensate and largely fails: 'pagination' loosely hints at startAt/maxResults but gives no defaults, limits, or offset semantics, and the 'query' parameter is never explained (name/key filter? fuzzy match?).

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 ('List Jira projects') and adds the scope qualifier 'visible', so an agent knows it enumerates accessible projects rather than fetching one. It does not explicitly contrast with siblings like jira_search_issues or jira_rest, which keeps it from 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?

There is no guidance on when to reach for this tool versus alternatives such as jira_list_boards, jira_search_issues, or the generic jira_rest passthrough. The agent must infer usage purely from the name.

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 description carries little extra burden, but it adds nothing new: no pagination behavior, no default page size, no maxResults cap of 100, no note that an empty result is possible. The state-filter sentence restates schema information rather than disclosing 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 resource and scope, with no filler. It is efficient but the brevity is achieved by omission rather than by tight editing of necessary content.

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 no annotation coverage of return shape, so the description should say what comes back (sprint ids, names, dates) and how pages work. Neither is present, leaving an agent unable to plan pagination or know what it can do with the returned sprint objects.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate and does not: boardId being required, startAt pagination, and maxResults (default 50, maximum 100) are all undocumented. The only parameter touched is state, whose three values are already enumerated 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 ('List sprints for a Jira Software board'), which is enough for an agent to distinguish it from jira_list_boards or jira_search_issues. It does not explicitly contrast with any sibling, so it stops short of 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 only guidance is that state filtering is optional; there is no statement of when to use this versus jira_list_boards or jira_search_issues, and no prerequisites such as the board needing to be a Scrum board. Usage is implied from the name only.

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?

The annotations already establish that this is a read-only, non-destructive operation. The description adds useful behavioral context by noting that the transitions are 'currently available' for a specific issue, implying dynamic workflow-state dependence, but it does not describe permissions, output shape, or pagination.

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

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

The description is a single front-loaded sentence with no filler. It is appropriately sized for a simple read tool.

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 tool with annotations covering safety, the description is minimally adequate. However, with no output schema it does not explain what the returned transition objects contain, and it leaves the issueKey format implicit.

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 parameter, issueKey, and schema description coverage is 0%. The description only says 'for an issue' and does not explain the expected issue key format or constraints, so it does not compensate for the schema's lack of documentation.

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 ('Return') and resource ('workflow transitions') scoped to an issue, so its purpose is clear. It does not explicitly distinguish itself from the sibling jira_transition_issue, which performs the actual transition, but the listing versus performing distinction is inferable.

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 not state when to use this tool versus jira_transition_issue or other Jira tools. A reader can infer it is for discovering available transitions before transitioning, but no explicit usage guidance or alternatives are provided.

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?

Goes beyond annotations in useful ways: writes/deletes act as the configured user, credentials must not be embedded, and apiPath is relative to /rest/. Annotations already flag destructive/openWorld, so this adds real operational context. It misses what happens on error responses and whether it returns raw JSON unmodified.

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, front-loaded with what it does, then path format, then methods, then the credential and identity caveats. Examples are inline and earn their 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?

For a generic REST passthrough with a 4-param, untyped body and no output schema, the description covers host resolution, path base, methods, auth identity, and the credential-safety rule. It stops short of describing response handling, pagination, or error behavior, which would matter for a raw-API 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 description coverage is 0%, so the description carries the burden — and it does: apiPath semantics (relative to /rest/) with three concrete path examples across core, agile, and servicedesk APIs, the supported method set, and the shape/role of query and body. Strong compensation for an undocumented 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 (call) and resource (any JSON Jira Data Center REST endpoint on the configured host), and immediately scopes it as an escape hatch beyond the curated jira_* siblings. An agent can tell this is the raw-API fallback rather than a purpose-built 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?

Conveys the when-to-use context (anything the curated jira_* tools don't cover) via 'any endpoint', plus a clear prohibition on putting credentials in apiPath/query/body. However, it never explicitly says 'prefer the dedicated jira_* tool when one exists' nor warns about the destructive consequences of a wrong DELETE/PUT.

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 behavior is covered. The description adds pagination and field-restriction context, but it does not mention result limits, defaults, or return shape, which would add meaningful behavioral detail beyond annotations.

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

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

The description is two sentences and front-loads the core purpose before pagination guidance. It is efficient with no obvious waste, though it could be slightly more informative without becoming 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?

With no output schema and 0% schema description coverage across five parameters, the description is too thin. It does not explain the return format, pagination metadata, default and maximum results, or the expand parameter, leaving gaps an agent would 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 description coverage is 0%, so the description must compensate. It mentions jql indirectly, plus startAt, maxResults, and fields, but it omits any explanation of expand, default values, maxResults cap, or JQL syntax expectations.

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: search issues using JQL. It is clear what the tool does, but it does not distinguish itself from siblings such as jira_get_issue or jira_rest.

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 some usage guidance by explaining pagination via startAt and maxResults and restricting returned fields. However, it does not say when to use this tool versus alternatives like jira_get_issue or jira_rest, leaving selection 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 disclose that this is a non-read-only, open-world, non-destructive mutation. The description adds useful behavioral context by requiring a currently available transition and a valid transition ID, though it does not explain side effects of fields/comment or what happens on invalid transitions.

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, both earning their place. The core action is front-loaded and the prerequisite follows immediately with 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?

The description covers the essential workflow prerequisite but is thin for a mutation tool with four parameters, a nested fields object, and no output schema. It should say more about how fields and comment affect the transition, though annotations already carry the basic safety profile.

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 0%, so the description must carry parameter meaning. It only indirectly explains transitionId via the lookup instruction and does not explain the nested fields object, the comment parameter, or the role of issueKey, leaving most parameter semantics undocumented.

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: moving an issue through a workflow transition. It also implicitly distinguishes itself from jira_list_transitions by casting that sibling as the lookup step rather than the mutation step.

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 an explicit prerequisite: call jira_list_transitions first to obtain a valid transition ID. That is concrete when-to-use guidance and names the exact alternative/supporting tool an agent should use before invoking this one.

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, and openWorldHint=true, so the safety profile is covered. The description adds real value by noting that Jira enforces the caller's permissions and workflow rules, warning that updates can be rejected server-side. It does not say what happens to fields not supplied, what validation errors look like, or the default for notifyUsers.

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, mutation stated first, with zero filler or repetition. It is efficiently front-loaded, though the brevity borders on under-specification rather than optimal density.

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 nested free-form payload mutation with no output schema and 0% schema coverage, the description omits the field-map contract, the notifyUsers behavior, and what a successful vs. rejected update returns. The permission/workflow note is helpful but does not fill the gaps an agent needs to call this 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 description coverage is 0% and the `fields` parameter is a free-form object with additionalProperties, so the schema alone gives no hint that keys must be Jira field IDs (e.g. customfield_10010) and values must match field-specific shapes. The description says nothing about field key format, value payloads, or what notifyUsers (default true?) controls, leaving the most error-prone parameter undocumented.

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?

Clear verb+resource: "Update an issue's fields" tells the agent exactly the operation and target object. It doesn't differentiate from nearby siblings like jira_transition_issue or jira_rest, so an agent must infer that field edits (not status changes) are the domain 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?

No guidance on when to use this instead of jira_transition_issue (status changes), jira_create_issue, or the generic jira_rest escape hatch. Usage is only implied by the word 'fields'; nothing states prerequisites or exclusions.

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