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

No annotations are provided, so the description carries the full behavioral burden. It does add genuinely non-schema value: the Jira wiki-markup embed syntax '!filename.png!' and the fact that the file must be local. But it is silent on attach-file permissions, size limits, what happens when a file of the same name already exists, and what the call returns — meaningful gaps for a mutation tool with zero annotation coverage.

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

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

Two short sentences, zero waste, with the core action front-loaded and the secondary embed trick placed after it. Nothing needs trimming.

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 a fully documented schema and no output schema, the description covers what to send and one useful post-upload convention. It is still thin on operational reality — permissions, file-size caps, duplicate-name behavior, and error outcomes — which an agent acting without annotations would want.

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 file_path (absolute path, relative resolution against the server working directory) and ticket_id (e.g. GEM-234) fully documented in the schema itself. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Upload a local file to a Jira ticket as an attachment'), which is unmistakably distinct from every sibling (add_comment, create_ticket, link_issues, etc.). An agent can select it 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?

Usage is implied by the upload framing, and the second sentence hints at the follow-up flow (embed the uploaded image in a comment or description), which points implicitly at add_comment/update_ticket. However, it never states when to prefer this over alternatives, nor any prerequisites 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?

With no annotations, the description carries full burden but only states 'Add a comment'. It does not disclose whether the operation is idempotent, requires permissions, or what the response looks like. Minimal behavioral info.

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, front-loaded, and contains no wasted words.

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

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

Given the tool has 2 parameters with full schema descriptions and no output schema, the description is minimal. It lacks behavioral transparency and usage guidelines, making it insufficient for a complete contextual picture.

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 parameters (body and ticket_id) with descriptions. The tool description adds no additional meaning 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 'Add a comment to a Jira ticket' clearly identifies the verb (Add), resource (comment), and context (Jira ticket). It effectively distinguishes from sibling tools like create_ticket, update_ticket, and transition_ticket.

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. For example, it does not mention that it is for adding new comments as opposed to editing existing ones, nor does it reference any prerequisites.

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

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

With no annotations, the description carries the full behavioral burden for a mutation tool. It does not say whether adding an existing watcher is idempotent or errors, what permissions are required, or whether notifications are triggered — all material 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?

A single front-loaded sentence with zero filler. It is appropriately terse for a simple two-parameter tool, though there was room to fold in one clause of behavioral context at little cost.

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, fully required parameters are documented in the schema, and no output schema exists, so little is strictly missing. However, for a mutation with no annotations, the absence of permission/idempotency guidance leaves the definition only minimally viable.

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 username and ticket_id already carry descriptions, including the format example 'GEM-234'. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (Add) and resource (a user as watcher of a Jira ticket), so the action is unambiguous. It does not explicitly name or contrast with its natural sibling remove_watcher, but the verb+object pairing makes the direction of the operation obvious.

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

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

The description gives no context on when to use this versus remove_watcher or any other tool, and it omits prerequisites such as whether the caller needs permission to modify watchers or whether the user must already exist in Jira. Usage must be entirely inferred.

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 behavioral burden, yet it discloses nothing beyond the basic action. It does not mention permission requirements, whether the ticket is created in a default status, how sub-task types require parent_key, or what happens to optional fields left unset.

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 single sentence is front-loaded and wastes no words, but its brevity reflects under-specification rather than efficiency. There is no structure to help an agent understand the multi-field creation flow.

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?

This is a 10-parameter mutation tool with no annotations and no output schema, so the description needs to carry more context than it does. Critical creation behavior, such as the requirement that parent_key be set for any sub-task type and what the tool returns, is absent.

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 every one of the 10 parameters is already documented in the schema with examples (project key 'GEM', issue type names, date format YYYY-MM-DD). The description adds no parameter meaning beyond that, which is the baseline case when the schema does the heavy lifting.

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

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

The description states a verb and resource ('Create a new Jira ticket'), which is enough to know it makes a Jira issue. But it is essentially a restatement of the tool name create_ticket and adds no differentiation from siblings like update_ticket, transition_ticket, or link_issues.

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

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

There is no guidance about when to use this tool versus alternatives such as update_ticket or transition_ticket, and no mention of prerequisites like needing an existing project or parent ticket. The agent must infer all of this from the schema 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, the description must carry the behavioral burden, and it does disclose the most important trait: the deletion 'cannot be undone'. It does not mention required permissions, error behavior on invalid IDs, or side effects, but the irreversibility warning is the critical disclosure for a destructive 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?

Three short sentences, front-loaded with the action and immediately followed by the irreversible-destruction warning. Every sentence earns its place with no filler.

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

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

For a low-complexity 2-parameter destructive tool with no annotations and no output schema, the description covers purpose, danger, and ID sourcing. It could add permission requirements or failure behavior to be fully complete, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by telling the agent where comment_id values come from (get_ticket with include_comments). That is information the schema's 'Comment ID, e.g. 10001' does not convey.

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

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

States a specific verb (Delete) and resource (a comment from a Jira ticket), which cleanly separates it from the sibling add_comment and update_comment tools. No ambiguity about what the 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?

Usage is implied by the destructive nature rather than stated; there is no when/when-not guidance versus update_comment or alternatives. The pointer to get_ticket with include_comments is a helpful prerequisite but is framed around obtaining an ID, not around when to choose 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 carries the full burden, but it does disclose the most important trait: 'This cannot be undone.' It omits permission/auth requirements, behavior when the worklog_id is invalid or already deleted, and any error/response shape, leaving real gaps for a destructive operation.

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

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

Three short sentences with zero waste: the action leads, the irreversibility warning follows immediately, and the ID-source hint closes. Nothing is padded or repeated.

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

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

For a two-parameter, no-output-schema delete tool, the description covers action, irreversibility, and prerequisite ID source. It is close to complete, with only permission/error semantics left unstated.

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, and the description adds value beyond the schema by explaining how to obtain worklog_id via get_ticket. It does not clarify the ticket_id format beyond the schema's own example.

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

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

Specific verb+resource ('Delete a worklog from a Jira ticket') that cleanly separates it from update_worklog, log_work, and delete_comment. The scope (deleting an existing worklog, not the ticket) 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?

Tells the agent where the required worklog_id comes from ('shown by get_ticket with include_worklogs'), which is genuine routing guidance toward a sibling. It does not, however, discuss when not to delete or contrast with update_worklog for corrections.

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 provided; description lacks behavioral details. Does not state whether it is read-only, what happens if fix_version is invalid, any permissions needed, or side effects.

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

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

Single sentence, efficient and front-loaded. No wasted words, but could potentially add more context 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?

No output schema, no annotations. Description omits details like scope of tickets included, required project, any filters applied. Incomplete for an agent to assess applicability.

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 covers both parameters with descriptions (100% coverage). Description adds grouping context but no deeper parameter meaning beyond 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?

Clear verb 'Generate', specific resource 'Markdown release notes', and constraints 'for a fix version' and 'grouped by issue type'. Distinct from siblings which are CRUD and workflow actions.

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

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

No guidance on when to use this tool vs alternatives. No mention of prerequisites, when-not-to-use, or context like requiring an existing fix version.

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, and it does add a useful cost signal ('cheaper than get_ticket'). However, it says nothing about behavior on a missing or inaccessible comment, permission requirements, or what the returned comment contains, which matters for an unannotated 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?

Two short sentences, zero filler, with the identity and the cost/routing rationale both front-loaded.

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

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

For a simple three-parameter read with full schema coverage and no output schema, this covers purpose, ID provenance, and cost tradeoff. Only error/not-found behavior is left unstated.

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 already 100%, setting a baseline of 3. The description earns the extra point by explaining where comment_id comes from ('?focusedCommentId= link'), giving provenance the schema does not provide.

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

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

States a specific verb and resource ('Get one comment of a Jira ticket by its ID') and scopes it to a single comment, which cleanly separates it from get_ticket and from comment-mutation siblings like update_comment and delete_comment.

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

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

Explicitly names the preferred-over alternative ('Cheaper than get_ticket when only that comment matters'), giving an agent a clear selection rule. It stops short of covering when other comment tools apply, but the key routing decision is made.

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 behavioral burden. It correctly implies a safe read ('Get full details') but says nothing about what happens with an unknown key, permission requirements, or that comments/worklogs/images are excluded unless toggled on and that include_worklogs costs an extra request — that cost signal lives only in the schema.

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

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

Two sentences, zero waste, with the primary action front-loaded and the disambiguation clause second. Every sentence earns its place.

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

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

There is no output schema, but the description plus the fully-covered input schema tell the agent how to shape the response via the include_* toggles. Missing only a note on error behavior for invalid keys and the fact that the default response omits comments/worklogs, which an agent could easily misread as 'full details' includes everything.

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 (ticket_id, include_images, image_limit, include_comments, include_worklogs) are already fully documented with defaults and caps. The description adds only the general notion that the response is the 'full details' of the keyed ticket, no format or behavior detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Get full details of a Jira ticket by its key') and immediately contrasts with the sibling get_comment. An agent can tell get_ticket apart from get_comment, search_tickets, and update_ticket without opening any schema.

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

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

Explicitly routes the single-comment case (a ?focusedCommentId= link) to get_comment, which is a concrete when-not-to-use rule. It does not address the search_tickets relationship (find a key vs. fetch by key), so guidance is clear but not exhaustive.

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

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

Annotations are absent, so the description must fully convey behavioral traits. It only says 'Create a link' without disclosing whether the operation is idempotent, what happens if the link already exists, authorization requirements, or side effects.

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

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

Extremely concise (one sentence, 9 words). It earns its place but lacks some behavioral detail. Slightly too sparse for optimal 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 tool's simplicity and well-documented parameters via schema, the description is minimally adequate. However, missing behavioral context and usage guidance make it less complete.

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

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

Schema coverage is 100% with clear descriptions for each parameter (e.g., 'Issue key being linked FROM'). The tool description adds no extra meaning beyond the schema, so 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 clearly states the action ('Create a link') and the resource ('between two Jira tickets'). It distinguishes from sibling tools which deal with individual tickets (get, update, transition) or comments, not linking.

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

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

No guidance on when to use this tool versus alternatives. No mention of when not to use it, prerequisites, or limitations.

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, and the description does not disclose behavioral traits such as idempotency, permissions required, or side effects. It only states the basic action without deeper 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?

Single sentence, front-loaded with action, no superfluous words. Efficient and 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?

Missing return value description and error handling context. For a mutation tool with no output schema, the description should explain what the response indicates (e.g., worklog ID), which is absent.

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 description adds limited value beyond parameter names and descriptions. The mention of WorklogPRO provides minimal extra context, but mostly restates schema info.

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 ('log') and resource ('work/time on a Jira ticket'), clearly distinguishing it from sibling tools like add_comment or update_ticket.

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

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

No guidance on when to use this tool versus alternatives like add_comment or transition_ticket. The description does not mention when not to use it or any prerequisites.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only discloses the sprint-state constraint. It does not say whether moving a ticket already assigned to another sprint overwrites it, what permissions are required, whether the operation is idempotent, or how failures on individual tickets are reported.

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 tight sentence with the verb and destination front-loaded and zero filler. Every clause earns its place.

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

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

The operation is low-complexity (2 fully documented params, no nesting), so the schema does most of the work. Still, as a mutation with no annotations and no output schema, the description leaves side effects (overwriting existing sprint assignment, partial failure handling) unexplained.

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 both parameters (sprint, ticket_ids) are already fully documented with examples. The description's "by sprint name or ID" merely restates the schema's sprint field and adds no new syntax or format detail, so the baseline of 3 applies.

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

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

States a specific verb ("Move"), resource ("Jira tickets") and destination ("active or future sprint"), which is precise and actionable. No sibling tool touches sprints, so no sibling differentiation is needed or given; the scope constraint (active/future only) adds useful 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?

The phrase "active or future sprint" implies when the tool applies (not closed sprints), giving implied usage guidance. However, it never states prerequisites (e.g., board/sprint membership, permissions) or when to use this versus update_ticket/transition_ticket, so guidance remains incomplete.

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 behavioral burden. It does not state what happens when the user is not currently a watcher, whether the operation is idempotent, what permissions are required, or what the response indicates.

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

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

A single front-loaded sentence with no filler. Every word earns its place 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 two-parameter mutation with a fully documented schema and no output schema, the description is minimally viable. It omits error/edge-case behavior (user not a watcher, invalid ticket) that an agent would benefit from knowing before calling.

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%, with both parameters documented in the schema (including the GEM-234 issue-key format), so the schema does the heavy lifting. The description adds no format or constraint detail beyond that, making 3 the correct baseline.

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

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

States a specific verb (remove) and resource (user from watchers of a Jira ticket), which is unambiguous. It implicitly distinguishes itself from the sibling add_watcher via the verb, but never names or contrasts that sibling explicitly.

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

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

The description gives no when-to-use context, no prerequisites, and no alternates (e.g. add_watcher for the inverse). Usage is only inferable from the verb itself, which is minimal 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 provided; description lacks any behavioral details such as pagination behavior, error handling, authentication requirements, or rate limits. Only states the obvious purpose.

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?

Single sentence, concise and front-loaded. However, it sacrifices informational value for 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?

Simple tool with 2 parameters and no output schema, but description fails to mention return format, sorting, or any constraints. Missing key behavioral 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 covers 100% of parameters with descriptions (e.g., jql with example, max_results with default). Description adds no additional meaning beyond what 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?

Description clearly states verb 'Search', resource 'Jira tickets', and method 'JQL query language'. Distinguishes from sibling tools like get_ticket (single retrieval) and add_comment (add operation).

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

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

No guidance on when to use this tool vs alternatives like get_ticket for individual tickets, or when JQL is appropriate. No exclusion criteria or context provided.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses alias resolution and the error-carries-valid-options contract, but says nothing about permissions, side effects like notifications, or whether the transition is reversible.

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

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

Three sentences, front-loaded with the core action, and each sentence contributes (core purpose, matching rules, error contract). No padding, though the alias parenthetical is slightly dense.

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

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

For a two-param mutation with no annotations and no output schema, the description covers argument resolution and error recovery but omits preconditions and post-state effects. Adequate to invoke, incomplete for understanding consequences.

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 already 100%, but the description goes beyond it by defining that 'status' may be a transition name or a target status and that aliases (Closed/Resolved -> Done) are accepted. That matching semantics is not derivable from the schema's 'Target status name' text, so it adds real value.

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

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

States a specific verb and resource ('Change a Jira ticket's status'), which cleanly separates it from the generic update_ticket sibling. It stops short of naming that sibling explicitly, so the differentiation is implied rather than spelled out.

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?

Explains how the status argument is matched (transition name or target status, with alias fallback) and that valid options surface in the error, which is genuinely useful retry guidance. However, it never says when to prefer this tool over update_ticket for status changes, so alternative selection is left to inference.

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

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

With no annotations, the description carries the full burden. It usefully discloses that link direction is irrelevant and that multiple links can coexist, but says nothing about permissions, error behavior for nonexistent links, or whether only the matching link type is removed.

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

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

Three short sentences, front-loaded with the core action, then the two behavioral caveats. 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 three-parameter tool with full schema coverage and no output schema, the description covers the essential action and the multi-link case. Minor gaps remain around failure modes and permissions, but nothing an agent needs to invoke it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: link_type is optional and only needed when several links connect the two issues, which the schema's 'Link type name or verb' text does not convey.

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

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

States a specific verb and resource: 'Remove a link between two Jira tickets.' The inverse relationship to the sibling link_issues is inferable, but the description never names or contrasts that sibling explicitly, so it falls short of the top score.

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

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

Usage is only implied by the operation itself. It explains the link_type disambiguation case ('If several links connect them, pass link_type to pick one') but gives no guidance on when to use this versus link_issues or what prerequisites exist.

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 behavioral burden. 'Replace the text' usefully discloses overwrite semantics (vs. appending), which the name update_comment alone does not convey. It still omits permissions required, reversibility, and error behavior for a mutation tool, leaving material 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?

Two short sentences, no filler, with the core action front-loaded and the ID-sourcing note appended. Every sentence earns its place.

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

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

For a simple three-required-parameter mutation with no output schema and no annotations, the description covers the action and how to source an ID. It does not address permissions, what happens to existing content/metadata, or failure modes, so it is adequate but 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?

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description only adds that comment IDs come from get_ticket with include_comments, a small sourcing hint that does not change the baseline 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?

States a specific verb (Replace) and resource (text of an existing comment on a Jira ticket), which cleanly separates it from add_comment and delete_comment in the sibling list. It does not name any sibling explicitly, so it earns a 4 rather than a 5.

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

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

The second sentence tells the agent where to obtain comment_id (from get_ticket with include_comments), which is genuinely useful invocation guidance. However, it gives no when-to-use/when-not guidance and does not contrast it with update_ticket or add_comment, so it stays at implied-usage level.

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 of behavioral disclosure. It discloses the issue-type conversion limitation, but omits important mutation details such as whether omitted fields remain unchanged, permission requirements, reversibility, and what the tool returns.

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

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

The description is two sentences and front-loads the core purpose before the important limitation. There is no redundant or wasted language.

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 schema is richly described and covers all parameters, and the description adds a key non-obvious limitation. However, for a 13-parameter mutation tool with no annotations and no output schema, it leaves significant behavioral context unstated, including partial-update semantics and response behavior.

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

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

Schema description coverage is 100%, so the schema already explains all 13 parameters in detail. The description adds a useful caveat about issue_type conversion, but otherwise does not supplement parameter semantics 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 the verb and resource: 'Update fields of a Jira ticket.' It is specific enough to distinguish from create_ticket and get_ticket, but it does not explicitly separate field updates from transition_ticket or update_comment.

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

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

It gives one useful exclusion and alternative: converting between standard issue types and Sub-tasks should be done via Jira's UI 'Move' action. However, it does not provide broader guidance on when to use this tool versus siblings such as transition_ticket for status changes.

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 does disclose one genuinely non-obvious trait — that Type of Work/Activity is immutable here and requires delete-plus-re-log — but says nothing about permission requirements, whether omitted fields are left unchanged (partial vs. full replace), or reversibility of edits.

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

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

Two tight sentences with zero filler; the core capability is front-loaded and the ID-sourcing hint and immutability caveat follow in priority order.

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

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

For a mutation tool with no annotations and no output schema, the definition covers the edit scope and one key constraint but omits partial-update semantics, required permissions, and what a successful response contains. Adequate to invoke, incomplete to invoke confidently.

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

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

Schema description coverage is 100%, so all five parameters including ticket_id and worklog_id already carry examples and formats. The description names the editable fields but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Edit) plus the exact mutable fields (time, start, comment) on a named resource (worklog), and implicitly separates itself from log_work (creation) and delete_worklog by describing the delete+re-log path for Activity changes. An agent can distinguish it from all four worklog/comment siblings without opening a schema.

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

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

Gives concrete routing: worklog IDs come from get_ticket with include_worklogs, and it explicitly names the alternative (delete_worklog + log_work) for the one case this tool cannot handle. It stops short of stating prerequisites like edit permissions or whether the caller must own the worklog.

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