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

Annotations only indicate readOnly=false, idempotent=false, and destructive=false. The description adds substantial behavioral detail beyond those: the Markdown-to-Jira rich text conversion set, the fact that unsupported markup remains literal, the return shape alignment with get_comments, and the permanent inability to edit/delete the comment.

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 with no waste. The action is front-loaded, the Markdown details are compactly enumerated, and the limitation sentence adds necessary operational context. 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 two-parameter tool, the description covers the action, body formatting behavior, return shape, and an important operational limitation. It does not describe issue_key format, but the tool's low complexity and the return-shape note make the definition essentially 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 0%, so the description must compensate. It richly explains body semantics, specifying which Markdown constructs are converted and that everything else stays literal. However, issue_key is left completely unelaborated — no format, source, or example — so only one of the two parameters receives meaningful semantic enrichment.

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 opens with a specific verb and resource: 'Add one comment to an issue.' This clearly distinguishes it from read-oriented siblings like get_comments and from update_issue, and the mention of return shape reinforces its role as a create-comment 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?

The description makes the usage context clear: it creates a comment, returns the same shape as get_comments, and explicitly warns that the server cannot edit or delete the comment afterwards. It does not explicitly name alternatives or when-not-to-use conditions, but the context is strong enough for an agent to route correctly.

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

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

Annotations already cover read-only, open-world, and idempotent traits. The description adds valuable behavior beyond those by explaining the process-scoped temporary cache and its lifecycle (removed at server shutdown). No contradiction with annotations exists.

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

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

Two short sentences with no filler. The core action and side-effect behavior are front-loaded, and 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 single-parameter read operation, the description provides the key outcome (local_path), the temporary-cache behavior, and its lifecycle. An agent can call the tool correctly without needing to know return structure, since the return value is explicitly stated.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining attachment_id. However, it only restates 'by id' and does not explain what an attachment_id is, how to obtain it, or whether it maps to get_attachments output. This adds almost no meaning beyond the parameter name.

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 ('Download'), a specific resource ('one attachment by id'), and a clear result ('return its local_path'). This is clearly distinguishable from sibling get_attachments, which presumably lists attachments rather than fetching a single one's content.

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

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

The description makes it evident this tool is for fetching a single attachment's local file path, while siblings like get_attachments are more likely for listing or metadata. It does not explicitly name an alternative or state when not to use it, but the context is clear enough for an agent.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety. The description adds the crucial behavior of not downloading content and lists the metadata fields returned, which goes beyond the annotations. It does not contradict the annotations and adds useful behavioral context, though it stops short of detailing output structure or edge cases.

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 with no waste. The purpose is front-loaded, key fields are listed compactly, and the alternative tool is stated in one short clause. Every word earns its place.

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

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

For a simple metadata-list tool with one required parameter, the description covers the purpose, returned fields, and the sibling to use for downloads. It omits details like pagination, sorting, or behavior for invalid issue keys, but these are reasonable to leave implied given the annotations (readOnly, idempotent) and the straightforward nature of the operation. Overall, it is sufficiently complete for an agent to call it correctly.

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

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

The input schema has only one parameter, issue_key, with zero description coverage. The description implies its meaning by referencing 'an issue' but does not explicitly state the expected format (e.g., project key like 'PROJ-123' vs. numeric ID). Since the burden is higher with 0% coverage, the description partially compensates but lacks explicit parameter semantics.

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 resource ('attachment metadata') and explicitly enumerates the returned fields (id, filename, mime_type, size, author, created). It clearly distinguishes from the sibling tool download_attachment by stating it does not download content, making the tool's scope 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 states exactly when to use this tool (to list attachment metadata without downloading) and explicitly names the alternative for fetching bytes (download_attachment). This gives the agent clear routing criteria and leaves no ambiguity about selecting the right 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?

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint), the description discloses meaningful behavior: default ordering, the special limit=0 behavior, tie-breaking by entry id, and the human-readable nature of field changes. This gives the agent a real sense of what happens during pagination and output without needing to guess.

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 carry high informational density with no filler: purpose first, then ordering semantics, pagination behavior, and output nature. Each sentence earns its place and the most actionable details are 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 read-only, paginated listing tool with no output schema, the description is complete: it names the required resource, defines the two pagination parameters and edge cases, and tells the agent what entries contain. An agent can call this tool correctly without further 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?

With 0% schema description coverage, the description fully compensates by explaining order values ('desc' vs 'asc'), how start_at/limit paginate the sorted collection, and the meaning of limit=0. issue_key is implied by 'an issue's field-change history' and by its schema title, so all parameters are effectively covered.

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 opens with a specific verb and resource: 'List an issue's field-change history.' This clearly distinguishes it from sibling tools like get_issue and get_comments, which retrieve current state or comments rather than history. The purpose is unambiguous and immediately actionable.

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 establishes the context for use—when you need an issue's field-change history—and the detailed pagination semantics helps the agent invoke it correctly. It does not explicitly name alternatives or say when not to use it, but among the siblings its niche is distinct enough that the context 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses important non-obvious behavior: pagination is on the logical filtered collection, ties are broken by comment id, limit=0 removes the 100-comment cap, and total reflects the filtered collection. This is rich, useful 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 front-loaded with the purpose and then packs dense, relevant details into a few sentences. There is no fluff or repetition; every segment adds meaningful operational information.

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

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

Given five parameters, zero schema descriptions, and no output schema, the description provides enough detail for an agent to invoke the tool correctly. It explains ordering, pagination, filtering, and a result-level concept (total) that would otherwise be unknown.

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

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

Schema description coverage is 0%, so the description must carry the full parameter documentation burden. It does: order values, start_at/limit pagination semantics, limit=0's special behavior, since's ISO-8601 offset requirement, and total semantics are all explained. issue_key is obvious from the purpose statement.

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 begins with a clear, specific verb and resource: 'List an issue's comments.' This distinguishes it from sibling tools like add_comment, get_issue, and get_changelog, whose names/purposes are different. The resource and action are 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 provides clear operational guidance: it explains how ordering, pagination, and the since filter behave, including the special limit=0 behavior. It does not explicitly name alternatives or say when not to use this tool, but the context is sufficient and not misleading.

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

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

Annotations already declare readOnly and idempotent hints, but the description adds significant behavioral context: fields replacement semantics, default fields, special handling for watches/votes (including an extra request), customfield mapping, and the fact that transitions are returned with status names. This goes well beyond annotations and discloses real 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 dense but every sentence adds value. It opens with the core purpose, then logically explains parameter behavior, and ends with exclusions and sibling routing. Well-structured and front-loaded with the most important information.

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

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

Given the tool's complexity (fields behavior, special values, exclusions) and lack of output schema, the description covers all essential aspects: return shape (default fields, field_names for customfields, transitions list format), edge cases (fields=[]), and what is not included. It gives an agent everything needed to call the tool correctly.

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

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

Schema coverage is 0%, so the description fully compensates. It thoroughly explains the `fields` parameter: default values, fields=[] behavior, special values for watches/votes, customfield handling, and transitions. The `issue_key` parameter is self-evident from context. The description provides rich semantic detail beyond the bare schema.

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

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

States a specific verb and resource: 'Fetch one issue by key.' It clearly distinguishes from siblings by explicitly listing what it does not include (comments, attachments, changelog) and pointing to dedicated tools, making the purpose 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?

Explicitly says when to use alternatives: 'use the dedicated tools for those' for comments, attachments, changelog. It also explains the transitions field relates to transition_issue, implying when to use this tool to preview transitions. Clear exclusions and alternatives are provided.

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

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

Annotations already declare readOnly/openWorld/idempotent hints; the description adds substantial non-obvious behavior beyond them: pagination contract (next_page_token null on last page, pass back as page_token), limit validation (1..100, 0 invalid), and the field-replacement semantics including the fields=[] edge case. No contradictions with 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?

Three tightly packed sentences with the main purpose front-loaded, followed by pagination, then limit, then fields. Each clause earns its place, though the fields sentence is dense and could arguably be split for readability.

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, the description covers the tricky parts of this tool: pagination mechanics, validation rules, and non-default field behavior. It doesn't detail the shape of the returned items beyond the default field list, but the field list itself gives a strong hint; nothing needed to call the tool 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 0%, so the description must carry the entire parameter-documentation burden, and it does: jql is implied as the query language, limit gets explicit valid range and default, fields gets full replacement semantics plus a documented default set, and page_token gets its opaque-token contract. This fully compensates for the empty schema descriptions.

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 (search), resource (Jira Cloud issues), and method (JQL), which distinguishes it from siblings like get_issue (single issue retrieval) and get_comments. The purpose is unmistakable and requires no inference.

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

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

The description explains how to use pagination, limit, and fields correctly, which is operational guidance. However, it never names sibling tools like get_issue for single-issue lookup or says when to prefer them over this search tool, leaving use-vs-alternative decisions implied rather than explicit.

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

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

Annotations already mark it as non-read-only and destructive; the description adds valuable detail: it changes issue state, posts the comment in the same call, explains matching behavior, and describes the error response. This goes well beyond what annotations alone convey.

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?

Every sentence adds value: purpose, parameter semantics, matching nuance, error handling, comment behavior, and state change. It is front-loaded with the main action and flows logically, with 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?

For a state-changing tool with no output schema, the description covers all critical aspects: how to specify the target, what happens on no match, the comment being posted in the same call, and the state change. The destructive nature is already in annotations, so nothing essential 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 description coverage is 0%, so the description must explain parameters. It thoroughly explains 'to' (transition name/status, matching rules, error behavior) and 'comment' (Markdown, posted in same call). Issue_key is self-explanatory, but the description compensates fully for the schema's lack of descriptions.

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 'Move an issue through its workflow' – a clear verb+resource. It further explains the 'to' parameter and that it changes issue state, making the purpose unmistakable and distinct from siblings like add_comment or update_issue.

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

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

Provides explicit guidance on how to specify the target: prefer transition name over status, matching is case-insensitive and trims spaces, and the error fallback lists all transitions. It doesn't explicitly name alternative tools, but the usage context is clear and well-specified.

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?

Beyond annotations, the description discloses key behavioral traits: null clears certain fields, labels and components are replaced in total, ambiguous assignee names return an error listing candidates, and unknown/custom fields are stored as raw Jira JSON. This adds substantial value and aligns with the destructiveHint without contradicting any annotation.

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 text is dense but every sentence earns its place. It front-loads the core action and then packs the field-reference mapping and replacement caveats into a compact paragraph. A bulleted list could improve scannability, but the information is efficiently presented 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 tool with a free-form fields object and no output schema, the description covers all critical invocation details: accepted field types, null semantics, list replacement behavior, and restrictions (no status/comment). It leaves no obvious gap that would prevent correct use, even for agents unfamiliar with Jira.

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

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

With 0% schema description coverage, the description carries the full burden for the fields object. It meticulously specifies value types for summary, description, assignee, labels, components, priority, duedate, parent, and custom fields, including edge cases like 'me' and ambiguous-name errors. This is far beyond what the bare schema provides.

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

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

The description opens with a specific verb and resource ('Set issue fields') and then details exactly which fields are supported and their formats. It also distinguishes itself from siblings by explicitly stating it cannot change status (use transition_issue) or add a comment (use add_comment), making the tool's 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 provides explicit when-not guidance: status changes and comments belong to transition_issue and add_comment respectively. It also instructs the agent to read the issue first before adding to labels/components because they replace the whole list, which is concrete usage advice.

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