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 the action without revealing any behavioral traits: it does not mention that it modifies the issue, whether the operation is idempotent, what happens on success or failure, or any authentication requirements. The transparency is therefore 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 sentence: 'Add a comment to a Jira issue.' It is concise, front-loaded, and contains no extraneous information. Every word contributes to the meaning, making it an exemplar of 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?

The tool has only two parameters and no output schema, so the description is not required to explain return values. However, since there are no annotations, the description should ideally disclose behavioral aspects such as success response or side effects. The description is complete for purpose but lacks depth for a mutation 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 100%: both 'id' and 'comment' have descriptions in the schema, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already provides. It does not clarify the format of the comment (beyond 'Markdown' already in schema) or how the id should be supplied.

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: 'Add a comment to a Jira issue.' It uses a specific verb ('Add') and resource ('comment'), and the target ('Jira issue') is immediately clear. This distinguishes it from siblings like jira_fetch_comments, which retrieves comments, and jira_update_issue, which updates issue fields.

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

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

The description implies usage: use this tool when you need to add a comment to a Jira issue. However, it does not explicitly mention alternatives or provide exclusions, such as noting that jira_fetch_comments should be used for retrieving comments. The guidance is minimal but present.

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 primary behavior (assign/unassign) but does not mention permissions, side effects, or error handling, which limits its 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 exceptionally concise—two sentences with no extraneous words. It clearly states the purpose and the necessary prerequisite, making it highly 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 tool with no output schema, the description provides the essential purpose and a usage hint. It does not detail return values or edge cases, but these are not critical for assignment operations.

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 covers 100% of parameter descriptions, including the behavior of omitting accountId. The description adds no extra parameter-level insight beyond what the schema states, 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?

The description specifies the verb 'assign' and the resource 'Jira issue', and also mentions the unassign case. This clearly distinguishes it from related tools like jira_update_issue by focusing on assignment.

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

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

It explicitly instructs users to use jira_search_assignable_users first to find the accountId, providing a clear usage guideline and naming an appropriate alternative tool for a prerequisite step.

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 burden. It discloses one behavioral trait (placement is ignored for subtasks) but does not mention prerequisites, permissions, side effects, or response behavior. It adds some context beyond the schema but not comprehensive for a write 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?

Two sentences, front-loaded with the core action, and the second sentence efficiently conveys the subtask exception. No unnecessary words 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?

The tool has 6 params but the schema covers all with descriptions. The description adds the key subtask behavior and is sufficient for routine use. It lacks mention of return values or error conditions, but given the rich schema and simple create operation, it is mostly 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 baseline is 3. The description repeats schema-specified facts (parentId for subtasks, placement not used for subtasks) without adding new semantic details. It reinforces but does not extend parameter 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 clearly states the tool creates a new Jira issue with specific verb and resource ("Create a new Jira issue"), enumerates supported issue types (Task, Bug, Story, Subtask), and differentiates itself from siblings like jira_update_issue and jira_fetch_issue. The subtask nuance adds precision.

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

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

It provides clear context on when to use this tool (creating issues) and gives specific parameter guidance for subtasks (provide parentId, placement ignored). It does not explicitly name alternatives, but the purpose is unambiguous against the sibling list, and the subtask usage is directionally helpful.

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 says 'Download' without explaining what happens to the file (saved? returned as bytes?), side effects, authentication needs, or error behavior. The schema implies saving to a filename, but the description doesn't affirm this 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 two sentences, with the first stating the core action and the second providing a necessary prerequisite. No fluff or repetition; 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?

The tool is simple, but with no output schema and no annotations, the description should clarify what the agent receives after download (e.g., file path, binary content). It also omits error or overwrite behavior. However, it provides a useful workflow hint (use fetch_issue first), making it minimally 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%: both parameters have descriptive entries ('Filename to save the attachment as' and 'Attachment ID from the issue's attachments list'). The description adds no additional parameter meaning, so baseline 3 applies.

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

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

The description states 'Download a single Jira attachment by its ID,' which is a specific verb and resource with a scoping qualifier ('single'). It clearly distinguishes this from siblings by focusing on downloading attachments, which no other sibling tool does.

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 explicitly instructs 'Use jira_fetch_issue first to get attachment IDs and filenames,' establishing a clear prerequisite and workflow context. It does not mention exclusions or alternatives, but given the sibling list has no other download tool, this is sufficient.

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 adds value by specifying the return order (most recent first) and the empty list behavior, which are not evident from the schema. However, it does not mention permissions, rate limits, or pagination limitations, which are typical for a fetch 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 two concise sentences, front-loaded with the primary action. Every sentence provides necessary information without redundancy, making it highly efficient.

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

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

For a simple fetch tool with one well-documented parameter and no output schema, the description adequately covers the purpose and return behavior. It could detail the structure of comment objects, but the essential aspects (list of comments, ordering, empty list) are addressed, making it sufficiently complete for the tool's simplicity.

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 fully describes the single parameter 'id' with a pattern and example. The description adds no additional parameter semantics beyond restating the Jira issue context, so the baseline 3 for high schema coverage 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 it fetches all comments for a Jira issue, using a specific verb and resource. It distinguishes itself from sibling tools like jira_fetch_issue (which fetches the issue) and jira_add_comment (which adds comments) by focusing solely on comment retrieval.

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

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

The description implies usage for retrieving comments but does not explicitly state when to use this tool over alternatives or any exclusions. It lacks explicit comparison to sibling tools, such as mentioning that jira_fetch_issue is for the issue itself.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. The verb 'Fetch' implies a read-only operation, and the description lists what is returned, which is helpful. However, it does not mention error behavior, permission requirements, or whether the returned data reflects the latest state. This is adequate but not thorough for a tool without 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 a single sentence that efficiently lists the operation and all return fields without redundancy. Every part of the sentence adds value, and there is no filler. The structure is front-loaded with the verb and resource, making it 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 simple one-parameter fetch tool with no output schema, the description adequately covers the return value by naming all included fields. It does not discuss edge cases like non-existent issues, but that is acceptable given the tool's simplicity. The description is complete enough for an agent to invoke the tool with confidence.

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 fully documents the single 'id' parameter with a pattern and example ('PROJ-123'). The description only refers to 'by ID' and adds no additional syntax, format, or contextual meaning beyond what the schema already provides. With 100% schema coverage, 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 starts with the specific verb 'Fetch' and names the resource 'Jira issue by ID'. It also enumerates the exact return fields (key, summary, status, etc.), making the tool's purpose crystal clear and distinct from sibling tools like jira_fetch_comments or jira_search_assignable_users.

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 implies this tool is used when you have a specific Jira issue ID and need its detailed fields. It does not explicitly name alternatives or exclusions, but the context is clear among siblings; there is no other fetch-issue tool in the sibling list. A 4 is appropriate for clear context without explicit when-not guidance.

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

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

With no annotations, the description adds a valuable behavioral detail by stating the API token is redacted, informing the agent that the output is sanitized. The verb 'Return' implies a read-only operation, though it does not explicitly state there are no side effects.

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

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

The description is a single, concise sentence that front-loads the action ('Return') and includes a key detail (token redaction) without unnecessary words 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?

Given the tool's simplicity (no parameters, no output schema), the description adequately conveys what is returned and the redaction behavior. It does not specify the exact return format, but 'environment variables' implies a key-value structure, which is sufficient for this getter.

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 fully covers the input. The description correctly omits parameter details, and the baseline for zero parameters is 4, which is appropriate here.

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 'Return the current Jira MCP configuration (environment variables), with the API token redacted.' This provides a specific verb and resource, and explicitly mentions the redaction behavior, distinguishing it from sibling tools that handle issues and 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?

The description implies usage through its purpose: it returns configuration, so it is used when configuration needs to be inspected. No explicit alternatives or exclusions are mentioned, but no alternative config tools exist among siblings, making the context 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, the description must carry the behavioral burden. It states the filtering constraints (current active sprint, current user) and implies a read-only listing, but does not disclose behavior when no active sprint exists, potential errors, or whether the result is sorted or paginated. It does add some 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, front-loaded sentence that directly states the tool's purpose. No wasteful words 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 list operation with no parameters and no output schema, the description is adequate. It clearly identifies the result set and the implicit filters. It does not specify the shape of the returned issues, but this is not critical for a basic list tool. The presence of jira_list_sprint_issues as a sibling suggests a potential need to clarify differences, but the description already implies the 'my' scoping.

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, and the description implicitly explains why—it operates on implicit context (current user and active sprint). This adds meaning beyond the empty schema, satisfying the baseline for 0-param tools.

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 ('List all issues') and the specific scope ('current active sprint assigned to the current user'). It distinguishes from siblings like jira_list_sprint_issues by the 'my' qualifier and the user assignment filter.

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 conveys a clear use case—retrieving personal issues in the active sprint—but does not explicitly explain when to use this tool versus similar alternatives like jira_list_sprint_issues or jira_fetch_issue. It lacks exclusions or alternative recommendations.

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 scoping behavior (current active sprint for the project, all assignees) and implies a read-only operation, but it omits edge cases like 'no active sprint,' permission requirements, or return format. There is no contradiction, but the behavioral detail 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, tightly worded sentence conveying the core action and its key differentiator ('regardless of assignee') without unnecessary words. Every element contributes to understanding the tool's function.

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 tool with two optional filters, the description adequately states what it does. However, it does not mention how the project is identified (no project parameter exists, so it likely relies on settings or context) nor the response structure. These gaps are minor for a straightforward list operation but reduce completeness.

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 provides descriptions for both parameters (label and status) with examples, giving 100% schema_description_coverage. The tool description does not reference these filters or add meaning beyond the schema, so the baseline 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 uses a specific verb ('List') and a clear resource ('all issues in the current active sprint for the project'). It also explicitly states 'regardless of assignee,' which distinguishes it from the sibling tool jira_list_my_sprint_issues, making the purpose unmistakable.

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

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

The description implies usage for project-wide sprint views but does not explicitly state when to use it over alternatives like jira_list_my_sprint_issues. The phrase 'regardless of assignee' provides an implicit contrast, but there is no direct guidance such as 'use this when you need all issues, not just yours.'

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 only states the tool searches for assignable users, but does not mention whether it is read-only, any authentication requirements, or the shape of results. For a search tool, some indication of return format or pagination would be expected.

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 core action and resource. There is no wasted verbiage, and it is 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?

The tool has only one parameter and no output schema, so the description must convey enough operational context. It mentions 'in the project' but does not specify which project or how it is determined, leaving ambiguity. It also does not describe return behavior, which is necessary since there is no output schema.

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

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

The input schema has 100% coverage for the single parameter 'query', with a clear description. The tool description adds no extra semantic information beyond what the schema provides, but since the schema is complete, a 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 identifies the action ('Search') and the specific resource ('users that can be assigned to issues in the project'). This distinguishes it from sibling tools like jira_assign_issue or jira_fetch_issue, making its purpose immediately apparent.

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 for when to use this tool—finding assignable users for issues in a project. Although it does not explicitly mention alternatives or exclusions, the context is unambiguous enough for an agent to select it appropriately among the sibling tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses only the action and the prerequisite for obtaining transition IDs, but does not mention permissions, reversibility, return values, or error behavior. For a mutation tool, this is insufficient.

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

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

Two sentences, each adding value: the first states the action, the second provides a critical next step. 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 tool is simple, but without annotations or an output schema, the description should clarify expected return/result and any side effects. It provides the core workflow but leaves these aspects to inference.

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 already provides descriptions for both parameters, covering 100% of parameters. The description adds the workflow hint about obtaining transition IDs via jira_fetch_issue, which reinforces the schema but doesn't provide substantially new meaning beyond it.

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 the specific verb 'Transition' with the resource 'Jira issue' and the target 'new status'. It clearly differentiates from sibling tools like jira_update_issue or jira_assign_issue by focusing on 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?

It explicitly instructs to call jira_fetch_issue first to obtain transition IDs, which is a clear prerequisite and workflow hint. It does not explicitly name alternatives or when-not conditions, but the context makes the usage obvious.

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 burden. It discloses the important behavioral trait that labels are modified incrementally (addLabels/removeLabels leave other labels untouched). However, it does not mention other side effects like permissions, whether summary/description are fully replaced, or what the response format is, leaving some gaps.

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 concise and well-structured: two sentences that front-load the main purpose and then add a critical behavioral detail. There is no redundant information or fluff.

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 high schema coverage and the absence of an output schema, the description adequately covers the tool's behavior. It explains the main action, the fields involved, and a key edge case (label accumulation). It does not mention return values, but that is not required since no output schema exists and the focus is on the operation itself.

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 provides descriptions for all parameters (100% coverage), so the baseline is 3. The description adds value by explaining the incremental behavior of addLabels/removeLabels, which is not obvious from the schema alone and clarifies the semantics of these 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 clearly states the tool updates summary, description, and/or labels of a Jira issue, which is a specific verb and resource. It distinguishes this from sibling tools like jira_create_issue, jira_assign_issue, and jira_transition_issue by listing the exact fields it modifies.

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 (when needing to update those fields) but does not explicitly state when not to use it or mention alternatives. It does, however, add a key usage nuance about incremental label modification, which helps the agent choose this over a full overwrite tool.

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