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

Without annotations, the description carries full responsibility for behavioral disclosure. It fails to mention important traits such as required permissions, side effects (e.g., auto-saving, notifications), any constraints on content (e.g., required Confluence storage format), or whether the operation is idempotent. This is a significant gap for a creation 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, direct sentence ('Create a new page in Confluence') with no fluff. Every word earned its place, and it is immediately understandable without parsing.

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

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

Given no output schema and no annotations, the description should provide more context about return behavior, error handling, or critical input details (e.g., that content must be in Confluence storage format). It is too sparse to reliably guide an agent through a successful 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 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for parameters. It does not explain how parameters interact (e.g., parentId usage) or emphasize required fields, but the schema itself is sufficient for basic understanding.

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 'Create a new page in Confluence' clearly states the action and resource. It distinguishes from sibling tools like confluence_update_page (update) and confluence_get_page (get) through the verb 'create'. However, it provides no additional context about scope or special behaviors, but remains 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 offers no guidance on when to use this tool versus alternatives such as confluence_update_page or Jira tools. There is no mention of prerequisites, typical scenarios, or exclusions, leaving the agent without context for selection.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It only indicates a read operation ('Get') but does not disclose error behavior (e.g., if pageId is invalid), rate limits, authentication needs, or whether the response includes full content or just metadata. The existence of the expand parameter is not hinted at in the description.

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. It earns its place by stating the core purpose, but it could include more detail 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?

For a simple read tool with full schema coverage, the description is adequate but has gaps: it lacks explanation of return values (since no output schema is provided) and does not differentiate from sibling tools or mention the expand parameter's role in controlling the response.

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 input schema already documents both parameters (pageId required, expand optional with an example). The description adds no extra meaning or usage context for the parameters beyond 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 'Get a specific Confluence page by ID', specifying the verb (get) and resource (Confluence page) with the method (by ID). It implicitly distinguishes from sibling tools like confluence_search and confluence_create_page, but does not explicitly elaborate on what is returned (e.g., full content) or scope.

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 offers no guidance on when to use this tool versus alternatives like confluence_search (for finding pages) or confluence_get_spaces (for a different resource). It does not mention prerequisites, context, or exclusions.

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

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

No annotations are provided, so the description must disclose behavioral traits. However, it only states the action without describing pagination, sorting, permissions, or response format. This is a minimal disclosure that provides no safety or behavior information.

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 conveys the tool's primary function without redundancy. It is appropriately sized for a simple list operation.

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

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

Given the lack of annotations and output schema, the description is too sparse. It omits important contextual details such as pagination behavior (implied by limit/start), the shape of the returned data, and when to prefer this over confluence_search. This makes it incomplete for an agent to use effectively.

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

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

The schema covers both parameters (limit and start) with descriptions and defaults, meeting 100% coverage. The description adds no additional parameter context beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool gets a list of spaces in Confluence, using a specific verb and resource. It distinguishes itself from siblings like confluence_search and confluence_get_page, which serve different purposes.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for listing all spaces, nor does it contrast with search or page retrieval. There is no explicit or implied usage context beyond the basic verb phrase.

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, but it only states what the tool does. It does not disclose behavioral traits such as rate limits, pagination behavior, authentication requirements, or whether results are filtered by user permissions. The agent gets no behavioral context beyond the verb 'search'.

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

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

The description is short and front-loaded with the key purpose. However, it could benefit from a brief expansion to add usage or behavioral guidance without losing conciseness.

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

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

Given the tool has no output schema and no annotations, the description is incomplete. The agent lacks information about return format, error handling, CQL syntax considerations (especially for complex queries), and pagination. For a search tool with a powerful but unfamiliar query language, more context is essential.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no parameter-specific meaning beyond the schema; 'CQL' is mentioned but not explained, and 'spaceKey' meaning is clear from the schema. The description does not compensate beyond what is already documented.

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

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

The description clearly identifies the tool as a search function for Confluence using CQL, which is more specific than a generic 'search'. It distinguishes from sibling tools like confluence_get_page (retrieving by ID) and Jira 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?

No guidance is provided on when to use this tool versus alternatives like jira_search_issues or when CQL is appropriate. The usage context is implied but lacks explicit when-to-use or when-not-to-use statements.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'Update', implying mutation, but reveals nothing about side effects (e.g., version creation, permissions required, atomicity, or response behavior). This is insufficient for an AI agent to understand the tool's operational characteristics.

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 efficient but arguably too sparse given the missing behavioral and contextual details. Conciseness is good, but it trades off completeness, preventing a perfect score.

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

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

Given the lack of output schema and annotations, the description should compensate with richer context. It does not explain what happens on success (e.g., returns updated page), how versioning works, or specifics about the content format (beyond schema). The tool has 4 required params and is a mutation, so the description is not complete enough for safe agent 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 100%, so each parameter already has a clear description. The tool description adds no new meaning beyond the schema. Per guidelines, baseline is 3 when coverage is high, and the description does not compensate or elaborate on parameter nuances such as the format of 'content' or the role of 'version' in optimistic locking.

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 'Update an existing Confluence page' clearly states the verb (update) and resource (existing Confluence page), but does not explicitly distinguish it from sibling tools like confluence_create_page or confluence_get_page. It implicitly differentiates by specifying 'existing', yet an explicit reference to alternatives would be stronger.

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

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

The description provides clear context on when to use: when an existing Confluence page needs modification. However, it offers no guidance on when not to use (e.g., for creation or retrieval) and does not mention prerequisites such as having the current version number. The context is clear but lacks full usage boundaries.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It does not mention side effects (e.g., whether the comment is visible immediately, permissions required, or if it appends to existing comments). The description is too brief to convey behavioral traits.

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 that efficiently conveys the core purpose. It is front-loaded and free of unnecessary words, though it is too brief for completeness.

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

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

Given the low complexity (2 simple parameters, no nested objects, no output schema), the description is incomplete. It lacks behavioral context (e.g., return value, confirmation) and usage guidance. A minimal viable description for this tool would include a note about permissions or format.

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 does not add new meaning beyond the schema's property descriptions. It does not clarify acceptable formats for 'body' (e.g., plain text vs. Jira wiki markup) or constraints on 'issueKey'.

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 ('Add') and resource ('comment to a Jira issue'), which clearly distinguishes it from tools like jira_search_issues or jira_create_issue. However, it could be more precise by mentioning it adds a comment to an existing issue, but the context signals and tool name make it clear.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as when updating an issue via jira_update_issue might be more appropriate. There is no mention of prerequisites (e.g., issue must exist) or exclusions.

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

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

No annotations are provided, so the description carries full burden. It only states 'Create a new issue' and does not disclose behavioral traits such as whether the operation is idempotent, what authentication scopes are needed, what happens to existing data, or what the response format is (e.g., returns issue key). For a mutation tool, this is a significant gap.

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 wasted words. It is front-loaded and immediately clear. However, it is slightly under-specified for the complexity of the tool; a few more sentences would improve completeness without sacrificing conciseness.

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

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

Given 5 parameters, 3 required, no output schema, and no annotations, the description is insufficient. It does not explain return values, error handling, or any constraints (e.g., valid issue types). A creation tool typically needs more context for correct invocation, and the current description falls short.

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 5 parameters with descriptions. The description adds no additional meaning beyond what the schema provides. Baseline is 3, and the description does not compensate with extra context like parameter constraints or examples.

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 'Create a new issue in Jira' uses a specific verb ('Create') and resource ('issue in Jira') clearly distinguishing it from sibling tools like 'jira_search_issues', 'jira_get_issue', and 'jira_update_issue'. It is unambiguous and directly states the action.

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

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

The description provides no guidance on when to use this tool versus alternatives such as 'jira_update_issue' or 'jira_add_comment'. It does not mention prerequisites (e.g., needing a project key from 'jira_get_projects') or any context for when creation is appropriate. 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?

With no annotations present, the description carries full responsibility for behavioral disclosure. It states the operation is read-only in name ('Get'), but fails to explicitly confirm non-destructive behavior, authentication requirements, or what happens if the issue does not exist. The lack of any safety or side-effect information limits transparency.

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 earns a high score for efficiency, though a small addition (e.g., 'This is a read-only operation') would not detract from conciseness.

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 retrieval tool with no output schema and no annotations, the description should at least hint at the typical response structure (e.g., issue fields, metadata) or note any limitations (e.g., pagination). The current description covers only the input identifier, leaving the agent without guidance on what to expect from the result.

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

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

Schema description coverage is 100% for all three parameters, so each parameter already has adequate inline documentation. The tool description adds no additional parameter-level meaning beyond what is in the schema, earning a 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 clearly states the verb 'Get', the resource 'specific Jira issue', and the identifier method 'by key'. This distinguishes it from sibling tools like jira_search_issues (searching) and jira_create_issue (creating), leaving no ambiguity about its purpose.

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 such as jira_search_issues or jira_get_projects. An agent would not know that this tool is appropriate only when the issue key is known, nor does it explain what to do if the key is invalid.

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 states the tool's basic function. It fails to mention whether authentication is required, what projects are included (all user-accessible or all in instance), or any limitations. This is a serious gap for a read operation.

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

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

The description is a single concise sentence that is front-loaded with the key action and resource. However, it is under-specified and could include additional context (e.g., output format) without becoming verbose. It earns its place but could do more.

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 does not explain the return value or output format, and there is no output schema to compensate. Given the simplicity of the tool (no parameters), the description should at least mention what kind of data is returned (e.g., project keys, names) or note if pagination applies. This makes it incomplete.

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 schema coverage is 100% by default. The description adds no parameter information, but none is needed. According to the baseline guideline for 0 parameters, a score of 4 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 'Get a list of projects in Jira' clearly states the action (get) and resource (list of projects). It is specific and distinguishes itself from sibling tools such as jira_search_issues and confluence_get_spaces, as no other tool provides a project listing.

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

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

The description provides no guidance on when to use this tool versus other Jira or Confluence tools. It does not mention alternatives, prerequisites, or context like 'use this to retrieve all accessible projects; for filtered search use jira_search_issues'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that the tool searches using JQL, without explaining any behavioral traits such as rate limits, authentication requirements, pagination behavior, or error handling. The schema already documents maxResults, so the description adds no new behavioral 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 a single sentence of 10 words, which is concise and front-loaded. It states the core purpose without unnecessary words. However, it could be slightly more informative (e.g., mentioning that results are paginated) while still remaining concise, so a score of 4 is given.

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

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

Given the tool has no output schema and no annotations, the description is incomplete. It does not describe the return format, default fields, or how to handle pagination. While the schema covers all parameters, the tool's complexity (JQL queries) warrants more context about capabilities and limitations. The description is minimally adequate but has clear gaps.

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

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

Schema description coverage is 100%, so each parameter has a clear description (e.g., 'JQL query to search for issues', 'List of fields to include in the response', 'Maximum number of results to return'). The tool description adds no additional meaning beyond the schema, such as JQL syntax examples or field name conventions. The baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Search for issues in Jira using JQL'. The verb 'search' and resource 'issues' are specific, and the mention of JQL distinguishes it from sibling tools like jira_get_issue (single issue retrieval) or jira_create_issue. However, it does not explicitly contrast with sibling tools, which prevents a score 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 description provides no guidance on when to use this tool versus alternatives. It does not mention that JQL is a powerful query language for complex searches, nor does it indicate that simpler lookups could use jira_get_issue. There is no context about prerequisites, common use cases, or when to avoid this tool.

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

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

With no annotations provided, the description must disclose behavioral traits. It only states 'update', implying mutation but offers no details on side effects, idempotency, required permissions, rate limits, or error behavior. This leaves the agent with insufficient understanding of what actually happens when the tool is invoked.

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 extremely concise at 5 words. It is front-loaded and free of fluff. However, it may be too sparse given the complexity of the operation; a sentence about return behavior or common use would improve it. Still, it earns a 4 for structure.

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

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

The description covers the basic action but lacks completeness. There is no output schema, yet the description does not indicate what the tool returns (e.g., updated issue details, success confirmation). It also omits constraints like partial vs full replacement or validation. For a 2-parameter tool with no annotations, more context is needed.

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% (both parameters have descriptions). The description itself does not add any parameter information beyond the schema. According to guidelines, baseline is 3 when coverage is high. The schema's description of 'fields' is vague ('Object containing the fields to update'), but that is a schema issue, not a description issue.

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 as 'Update an existing Jira issue'. It uses a verb+resource structure and is distinct from siblings like jira_create_issue (creation) and jira_get_issue (retrieval). However, it does not explicitly differentiate itself from similar update tools (none exist in siblings), so it gets 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?

No guidance is provided on when to use this tool versus alternatives. It does not mention that this is for modifying existing issues only, nor does it direct the agent to jira_create_issue for new issues or jira_get_issue for reading. The description is purely functional with no usage context.

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