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

No annotations are provided, so the description carries the full burden of disclosing behavior. It clearly describes a read-only identity lookup and specifies the returned data, which is sufficient for a simple whoami-style tool. It does not discuss authentication details or potential errors, but nothing in the description contradicts the observable 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?

The description is a single well-structured sentence that front-loads the core action and then lists the concrete output fields. Every part of the sentence adds information; there is no filler or repetition.

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

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

For a zero-parameter, no-output-schema tool, the description is complete. It names the tool's purpose and the exact fields returned, which is all an agent needs to invoke it 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?

The tool has zero parameters, so the schema already fully covers parameter information. The description appropriately adds value by explaining what the tool returns rather than attempting to document nonexistent parameters.

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

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

The description uses a specific verb ('Returns') and resource ('identity of the currently authenticated Atlassian user'), then enumerates the exact fields returned: account ID, display name, email, and accessible site URLs. It is clearly distinguishable from the Jira and Confluence content-operation 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?

The description implies this is the tool to call when the agent needs to know who the authenticated user is, but it does not explicitly state when to prefer it over alternatives or mention any exclusions. Since no sibling tool duplicates this function, the ambiguity is low, but explicit guidance is absent.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It communicates that a comment is created, but it does not mention side effects, visibility to other users, edit/delete behavior, or error cases. The word 'footer' is a small behavioral detail, but overall the transparency is minimal.

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 or repetition. Every word is meaningful and the action is immediately clear.

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 2-parameter tool, the description plus schema is minimally sufficient to invoke the tool correctly. However, with no annotations and no output schema, there is no information about response behavior, failure modes, or when not to use this tool, which leaves noticeable gaps for an autonomous agent.

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

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

Schema coverage for parameters is 100%, so the baseline is 3. The description adds no extra meaning beyond what the schema already provides for pageId and body; the body conversion to ADF is documented only in the schema, not in the 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 action ('Add') and resource ('Confluence page'), and the term 'footer comment' adds placement specificity that distinguishes it from general comment-adding siblings like jira_add_comment. An agent can immediately tell what this tool does without opening 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?

The description gives no guidance about when to choose this tool over other comment or page tools, such as jira_add_comment or confluence_update_page. There is no mention of exclusions, prerequisites, or alternatives, so the agent must infer usage 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?

There are no annotations, so the description carries the full burden for behavioral disclosure. It only states that a page is created and does not mention permissions, side effects, response shape, draft behavior, or whether the operation can be safely retried. This is a mutation tool with no safety information in annotations, so the description is 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?

The description is a single concise sentence that is front-loaded with the main action and object. There is no redundant wording or filler, and every word contributes to identifying the tool's purpose.

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 five parameters, all covered by the schema, but no output schema and no annotations. The description explains what the tool does but not return values, exclusions, or behavioral context such as permissions or draft semantics. It is adequate for a simple create operation but 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 description coverage is 100%, so the parameters are already well documented. The description adds no parameter-level meaning beyond 'specified space,' which matches the spaceId parameter already described as a numeric space ID. The baseline of 3 is appropriate because 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 uses a specific verb ('Create'), a clear resource ('a new Confluence page'), and a scope ('in the specified space'). It is immediately distinguishable from sibling tools like confluence_update_page, confluence_get_page, and confluence_search because 'new page' makes the operation explicit.

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

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

The description implicitly signals this tool is for creating pages, but it gives no explicit guidance about when to choose it over alternatives such as confluence_update_page or confluence_add_comment. The schema does reference confluence_get_spaces for ID lookup, but the description itself does not provide when-to-use or when-not-to-use guidance.

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

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

No annotations are present, so the description carries the behavioral burden. It clearly indicates a read-only 'Get' operation and enumerates the returned fields (title, spaceKey, markdown body, version number, last-modified date), giving the agent a solid expectation of the result.

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, focused sentence that front-loads the core action and then lists the return payload. Every phrase earns its place, with 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?

For a simple one-parameter page retrieval tool, the description is complete: it explains what is fetched, how to identify the page, what fields are returned, and how page IDs can be found. No output schema exists, but the return fields are explicitly enumerated.

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 pageId parameter is already well documented with a type, example value, and a pointer to confluence_search. The tool description adds only the 'numeric' detail, so it does not significantly go beyond what the schema already provides.

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

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

The description clearly states the action ('Get'), the target resource ('full content of a Confluence page'), and the accessor ('by its numeric page ID'). It distinguishes itself from sibling tools like confluence_search and confluence_create_page by focusing on retrieving existing page content rather than searching or mutating pages.

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 this tool is appropriate when the caller already has a numeric page ID, and the schema explicitly routes ID discovery to confluence_search. It provides clear contextual guidance, though it does not explicitly state when not to use the tool.

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

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

No annotations are provided, so the description carries the full burden. 'List' signals a non-mutating operation, and 'accessible to the authenticated user' plus the returned fields sets clear expectations. It could explicitly state read-only behavior or auth requirements, but for a simple listing tool this is sufficient.

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

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

A single sentence with no filler. The action, scope, and output fields are all present and front-loaded, making it easy for an agent to parse quickly.

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 list operation with two optional, well-described parameters, the description is nearly complete. It names the return fields, partially compensating for the lack of an output schema, though it does not explicitly address pagination or filter behavior beyond what the schema states.

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

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

Schema description coverage is 100%, with both parameters documented including enum values, default, min, and max. The description adds no additional parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

Clearly states a specific verb (List), resource (Confluence spaces), and scope (accessible to the authenticated user), and enumerates the returned fields. It is readily distinguishable from siblings like confluence_get_page and confluence_search, which target pages/content rather than spaces.

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 explains what the tool does but provides no guidance on when to use it versus alternatives. It does not mention when confluence_search or confluence_get_page might be more appropriate, leaving the choice 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It does state that the tool returns matching pages, blog posts, and spaces with title, spaceKey, URL, and an excerpt, which is useful. It does not disclose response list structure, pagination behavior, auth/permission requirements, or behavior on no matches, but these are less critical for a read-style search tool.

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 one sentence with no filler, front-loads the action and resource ('Search Confluence content using CQL'), and then states the return fields. Every word 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 low-complexity search tool with fully documented parameters, the description is largely complete. It explains what content is searched and what fields are returned, partially compensating for the missing output schema. It could still mention result ordering or pagination, but limit is already in the schema and the usage pattern is straightforward.

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 for parameters is 100%, and the schema already documents cql with examples and limit with default/min/max. The description does not need to add param semantics, but it also does not contribute anything beyond mentioning CQL by name. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Search Confluence content using CQL' and lists what is returned (pages, blog posts, spaces). This clearly differentiates it from sibling tools like confluence_get_page (retrieving a specific page) and jira_search_issues (searching Jira).

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 context is clear: this is the Confluence search tool, and sibling names imply alternatives like confluence_get_page for known pages. However, the description does not explicitly say when to use it instead of another tool, nor does it mention exclusions such as 'use confluence_get_page when you already have the page ID.'

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

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

With no annotations, the description carries the behavioral disclosure burden. It does reveal a meaningful constraint: Confluence rejects updates that omit the current version number. However, it omits side effects, permission needs, and the fact that title and body are both required despite the 'and/or' phrasing.

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 clauses with no filler: the action is front-loaded and the critical version caveat follows immediately. Every word 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?

No annotations or output schema mean the description must provide operational context. It gives the versioning caveat but leaves the 'and/or' ambiguity unresolved regarding required fields, and it does not clarify that unchanged fields must still be passed. Adequate, but a meaningful gap remains.

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; the description does not need to restate parameter meanings. It adds the current-version requirement, but the schema already documents fetching with confluence_get_page and incrementing by 1, so the added value is minimal.

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?

Clearly identifies the operation (update), the resource (existing Confluence page), and the scope (title/content), which distinguishes it from create_page and get_page. The 'and/or' phrasing is slightly imprecise, 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 word 'existing' and the version-number requirement imply this is for editing pages that have already been created and that the current version must be fetched first. It does not explicitly name alternatives like confluence_create_page, but the usage context is clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, but it only restates the core action. It does not mention side effects, authentication requirements, whether the comment is immediately visible, or what happens on repeated calls. 'Add a comment' implies mutation but adds no behavioral context beyond the tool name.

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

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

The description is a single, grammatically complete sentence with no filler or redundant detail. It is front-loaded with the action and target, making it immediately scannable.

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 tool with no output schema, the description plus schema is arguably callable, but it does not describe the return value, error cases, or whether the comment is created immediately. The lack of annotations and output schema makes the description minimally adequate rather than 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 the parameter details are fully documented in the schema. The description adds no parameter-specific meaning beyond what the schema already provides, such as noting that body is plain text and auto-converted to ADF, which 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?

The description clearly states the verb 'Add' and the resource 'comment to a Jira issue', which distinguishes it from sibling tools like jira_create_issue or confluence_add_comment. It is not a pure tautology because it specifies the target platform and resource, though 'add a comment' largely mirrors the tool 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?

The description gives no guidance on when to use this tool versus alternatives such as jira_update_issue, jira_transition_issue, or confluence_add_comment. There is no mention of prerequisite context, exclusions, or conditions that would route an agent to a different sibling.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that an issue is created, which essentially restates the tool name, and does not mention side effects, permissions, validation behavior, or what happens after creation.

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

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

The description is a single sentence with no filler or repetition. It front-loads the core action and resource without unnecessary elaboration.

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 eight parameters and no output schema, yet the description does not mention what the agent should expect as a result, such as the created issue key or ID. The schema covers parameters well, but for a mutating tool with no annotations and no output schema, the description could provide more operational context.

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

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

Schema description coverage is 100%, so the input schema already documents all eight parameters. The description does not add meaning beyond naming the project, but the schema fully compensates for parameter-level details, so the minimum viable score of 3 is appropriate.

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

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

The description clearly identifies the action ('Create'), the resource ('a new Jira issue'), and the scope ('specified project'). It is immediately distinguishable from sibling tools like jira_update_issue and jira_transition_issue because it explicitly targets creation of a new issue.

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

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

The intended use is implied by the creation semantics, but the description does not explicitly state when to choose this tool over alternatives such as jira_update_issue or jira_transition_issue. An agent can infer the right choice from the tool name and siblings, but the guidance is not made explicit.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It indicates a read-only operation via 'Get' and lists included return fields, which is useful. However, it does not mention permissions, response size limits, error behavior, or whether the optional fields parameter affects the returned structure beyond what the schema states.

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

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

A single, well-structured sentence that front-loads the action and resource, then lists representative return fields. No filler or redundancy.

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

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

The description is sufficient for a low-complexity read tool: it explains the input (key), the scope (single issue), and the output categories. Since there is no output schema, the description is the only source of return-value context, and it provides enough orientation for an agent to invoke the tool correctly, though it omits error/permission details.

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

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

Schema description coverage is 100%, so the schema already documents both issueKey and fields. The description adds the issue key example and mentions some returned fields, but it does not meaningfully expand on the optional fields parameter beyond the schema's own explanation.

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

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

The description clearly states the tool fetches full details of a single Jira issue by key, with a concrete example (PROJ-123). This distinguishes it effectively from sibling tools like jira_search_issues and jira_update_issue.

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

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

The description implies the correct context: use this when you already have an issue key and need complete issue details. It does not explicitly name alternatives or exclusion criteria, but the 'single issue by key' framing provides clear guidance relative to search-based siblings.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses the access scope ('accessible to the authenticated user'), the read-only list nature, and the returned fields. It does not mention pagination or ordering, but that is a minor gap for a simple list tool.

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

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

The description is a single concise sentence that front-loads the action and resource, then immediately states the return contents. There is no filler or redundancy.

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

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

For a simple two-parameter list operation, the description plus schema cover the essentials: scope, parameters, and return fields. The only notable gap is the potential tension between 'List all projects' and the maxResults cap, and the absence of explicit pagination guidance.

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

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

The input schema describes both parameters fully (query and maxResults), so schema coverage is 100%. The description adds no additional parameter semantics beyond what the schema already provides, which warrants the baseline score of 3.

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

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

The description states a clear, specific verb ('List') and resource ('all Jira projects accessible to the authenticated user'), and specifies the returned fields (key, name, type, lead). This differentiates it from sibling tools that operate on issues, comments, or Confluence content.

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

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

The intended use is implied: call this when you need an agent to enumerate accessible Jira projects. However, it never explicitly names alternatives or says when NOT to use it, such as when a search across issues would be more appropriate.

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

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

With no annotations provided, the description carries the full burden. It discloses the output shape (list with key, summary, status, assignee, priority), which is useful. However, it does not state that the operation is read-only, how the 'fields' parameter modifies the returned set, or any pagination/error behaviors. It offers minimal behavioral context beyond the obvious search semantics.

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, clear sentence with no redundancy. It front-loads the action and immediately specifies the return contract, making it easy to scan and every word 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 low-complexity tool with one required parameter and complete schema coverage, the description covers the core purpose and default return shape. However, it does not clarify how the 'fields' parameter changes the return fields, so an agent could be surprised if results do not always contain the listed default fields. This is a notable gap in an otherwise adequate description.

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

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

Schema description coverage is 100%, so the schema already fully documents jql, fields, and maxResults. The description adds a mention of default output fields but does not explain how the 'fields' parameter interacts with those defaults. It contributes little beyond the schema, earning the baseline score.

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

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

The description clearly states the action ('Search Jira issues using JQL') and the resource being searched, and it explicitly lists the returned fields. This sharply distinguishes it from sibling tools like jira_get_issue (retrieve single issue) and jira_create_issue (create new issue).

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 clearly frames this as a JQL-based search operation, implying it is for filtering/listing issues rather than fetching a single known issue or modifying issues. It provides clear context without explicit exclusions or alternative tool names, so an agent can reasonably route to it for search scenarios.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does reveal that the operation is a mutation and names the mechanism (workflow transition), but it does not mention that valid transitions depend on the issue's current status or what error/response behavior to expect.

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 communicates the action, mechanism, and examples, with no filler or repetition. The core purpose is front-loaded and immediately usable by an agent.

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 tool with two fully documented required parameters, the description covers the essential operation well. Missing details like response format and workflow-availability constraints are minor, and the tool remains invokable from the description plus schema 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?

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds some context by tying transitionName to a new status, but it mostly reinforces the schema's own param descriptions rather than providing deeper semantic detail.

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

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

The description states a specific action ('Move a Jira issue to a new status') and the mechanism ('triggering a workflow transition'), with concrete examples. This clearly distinguishes the tool from siblings like jira_update_issue, which handles field updates rather than status changes.

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 guidance is given about when to use this tool versus alternatives, nor when not to use it. The intended use is implied by the wording, but the agent is not told to prefer this over jira_update_issue for status changes or warned that only currently available workflow transitions can be applied.

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

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

With no annotations, the description carries the full burden, but it only states that fields are updated. It does not disclose whether unspecified fields are preserved, whether updates are partial or full-replacement, what permissions are needed, or what side effects occur. The schema's 'Replace labels' and ADF-conversion notes add detail, but the description itself is minimal.

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, direct sentence with no filler. It front-loads the action and target and efficiently conveys the core purpose. Nothing extraneous is present.

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 mutating tool with no annotations and no output schema, this description is too terse. It omits partial-update behavior, expected response, and when to choose this over jira_transition_issue. The schema covers parameters, but the description does not complete the operational picture for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already provides; the schema property descriptions like 'Replace labels with this array' and 'New summary' carry that burden.

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 ('Update') and resource ('fields on an existing Jira issue'), which distinguishes it from create/comment/transition tools. It clearly names the action and target, though it does not explicitly differentiate itself from jira_transition_issue, which also updates an issue.

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 is provided on when to use this tool versus alternatives like jira_create_issue, jira_transition_issue, or jira_add_comment. The usage is only implied by the word 'Update'; there are no exclusions, prerequisites, or alternative-selection cues.

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