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

Goes beyond annotations by specifying the Markdown-to-rich-text conversion rule (which constructs convert, which stay literal), the return shape matching get_comments, and the key limitation that this server cannot edit or delete the comment afterward. idempotentHint=false already implied each call creates a new record; the description enriches that with the no-edit/delete constraint.

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?

Four sentences, each earning its place: purpose, body format, return shape, limitation. The purpose is front-loaded. The Markdown enumeration is slightly long but necessary for precision about what converts versus what stays literal.

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?

Covers purpose, body semantics, return shape (reinforced by the existing output schema), and the post-creation limitation. What's absent — permission requirements, error cases, validation of the issue key — is peripheral for a comment-creation tool and the output schema already documents the return value.

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 compensate, and it does substantially for body by detailing the accepted Markdown subset and conversion behavior. issue_key receives no explicit treatment, but it is highly self-explanatory in a Jira context (e.g., PROJ-123), so the omission is minor.

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: 'Add one comment to an issue.' This clearly distinguishes it from read siblings (get_comments, get_issue, search_issues) and mutation siblings (update_issue, transition_issue) because 'add' uniquely signals comment creation.

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 purpose statement implies when to use it — when a comment needs to be created — but there is no explicit when-not guidance or mention of alternatives. The sibling set is mostly reads and other mutations, so the distinct verb mostly self-selects, yet the description never names a condition that would rule it out in favor of another 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?

The description adds meaningful behavioral context beyond the annotations by explaining that downloads go to a process-scoped temporary cache and that the cache is removed on server shutdown. This gives the agent important expectations about the returned local_path's lifetime and scope.

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, both necessary. The main action and return value are front-loaded, and the cache lifetime detail is placed second, making the description both concise and logically structured.

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 single-parameter tool with a true output schema and read-only/idempotent annotations, the description covers the essential behavioral details: download action, cache scoping, and lifetime. It is slightly incomplete only in that it doesn't mention typical downstream usage of local_path or how it relates to get_attachments.

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 the parameter. It only says 'by id', which essentially restates the schema's 'attachment_id'. It does not clarify where to obtain the id, what format it takes, or distinguish it from other identifiers.

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

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

The description states a specific action (download one attachment by id) and a concrete outcome (returns local_path), and clearly distinguishes itself from sibling tools like get_attachments by focusing on a single attachment and returning a cached file path rather than listing or retrieving 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?

No guidance is given about when to use this tool versus alternatives such as get_attachments or get_issue. The description implies it should be used when an attachment_id is already known, but it does not explicitly state prerequisites, exclusions, or alternatives.

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, idempotentHint, and openWorldHint. The description adds meaningful context that content is not downloaded and that only metadata is returned, which helps the agent understand the tool's non-destructive behavior beyond the 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?

Two sentences, front-loaded with the action and returned fields, ending with a pointer to the sibling tool. Every word adds value; 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?

This is a simple one-parameter tool with an output schema and safety annotations. The description covers the key metadata-vs-content distinction and names the sibling, making it complete for correct invocation without excessive detail.

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 issue_key. It implies issue_key identifies the issue ('an issue's attachment metadata'), but does not specify format or provide examples. This is minimally viable but leaves ambiguity about the expected key format.

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 states a specific verb ('List'), resource ('issue's attachment metadata'), and explicitly lists fields returned (id, filename, mime_type, size, author, created). It also differentiates itself from download_attachment by noting it does not download content, 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?

Explicitly names download_attachment as the alternative for fetching file bytes, giving a clear when-to-use-this vs when-to-use-that. The condition is stated: metadata vs content, leaving no ambiguity about 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?

Annotations indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds substantial behavior beyond these: it explains the default order, pagination tie-breaking by entry id, limit=0 behavior, and that entries are human-readable. This enriches the agent's understanding of edge cases and return content.

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 compact yet information-dense. It front-loads the core purpose, then systematically explains ordering, pagination, and output content. No sentence is redundant; every clause contributes to correct usage.

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 moderate complexity (sorting, pagination) and the existence of an output schema (which presumably details the return structure), the description covers all behavioral aspects needed to call the tool correctly. It is complete without needing to enumerate return fields.

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?

Although schema description coverage is 0%, the description fully explains the non-obvious parameters: order (desc/asc), start_at and limit pagination semantics, and limit=0 special case. issue_key is self-explanatory. This adds significant meaning beyond the schema's defaults and types.

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 lists an issue's field-change history, a specific verb and resource. It is distinct from siblings like get_issue or search_issues, which focus on current state or search, not history.

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 detailed usage instructions for ordering and pagination (order, start_at, limit semantics including limit=0 meaning no cap). It does not explicitly mention alternatives or when not to use, but the tool's purpose is self-evident and the guidance is clear for correct invocation.

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/idempotent/openWorld annotations, the description discloses default ordering, pagination semantics, tie-breaking by comment id, the special limit=0 behavior with no 100-comment cap, the since filter format, and that total reflects the filtered collection. This is excellent behavioral disclosure.

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 core purpose and then packs detailed behavior into a compact, well-organized set of clauses. No sentence is wasted; every detail adds necessary invocation semantics.

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 moderate complexity (filtering, sorting, pagination, cap behavior) and the presence of an output schema, the description covers all essential invocation details. It even explains edge-case pagination and how total is computed, making it fully adequate for correct usage.

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: it explains order values and default, start_at/limit pagination with tie-breaking, limit=0 special behavior, since's ISO-8601 offset requirement and filtering semantics, and the meaning of total. Even issue_key is implied by 'an issue's comments'.

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 opening sentence 'List an issue's comments' states a specific verb and resource, clearly distinguishing this tool from siblings like get_issue, get_attachments, and get_changelog. It leaves no ambiguity about what the tool returns.

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 clear the tool retrieves comments for an issue and provides detailed pagination/filtering behavior, giving a strong sense of when to use it. It does not explicitly name alternatives or exclusion conditions, but the purpose statement is sufficiently specific to route an agent 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 declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it discloses that fields replaces defaults entirely (not merges), that fields=[] returns only the key, and that certain data (comments, attachments, changelog) is deliberately excluded. This is meaningful behavioral disclosure that helps the agent predict the tool's behavior. A small gap is that it doesn't mention pagination or error behavior, but the annotations plus the explicit exclusions are strong.

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 compact and front-loaded: the core action ('Fetch one issue by key') comes first, followed by the most important parameter behavior, then the exclusions. Every sentence earns its place, and the exclusions are grouped efficiently. No fluff or repetition of schema details.

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 an output schema, so return values are already documented structurally. The description covers the key behavioral aspects an agent needs: what the default fields are, how to override them, and what is not included. It also names sibling tools for the excluded data. The only slight gap is that it doesn't mention whether the response includes any metadata (e.g., expand) or how errors are surfaced, but given the output schema and annotations, the description is largely complete for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains the fields parameter's semantics in detail (replaces defaults entirely, default list, fields=[] behavior) and names the required issue_key parameter. The only minor gap is that it doesn't explicitly restate that issue_key is the Jira issue key format (e.g., PROJECT-123), but the parameter name and tool name make that obvious. Given the 0% schema coverage, the description carries the burden well.

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 ('Fetch') and resource ('one issue by key'), and immediately distinguishes itself from sibling tools by explicitly listing what it does not include (comments, attachments, changelog history) and pointing to dedicated tools for those. This makes the tool's purpose unmistakable and differentiates it from get_comments, get_attachments, and get_changelog.

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 guidance on when to use this tool versus alternatives: it says to use dedicated tools for comments, attachments, and changelog history. It also explains the fields parameter behavior, including the default field set and the fields=[] special case, which tells the agent exactly how to control the response. This is clear, actionable usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral details beyond annotations: pagination semantics (opaque token, null on last page), the fact that fields replaces the default field set entirely, and that fields=[] returns only the issue key. This is exactly the kind of non-obvious behavior an agent needs to know.

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, each dense with useful information. The most important facts (search with JQL, pagination token) are front-loaded, and the fields behavior is explained precisely. No filler or repetition of schema defaults that are already visible.

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

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

The description is complete for a read-only search tool: it covers pagination, limits, field selection, and the output schema exists to explain return values. It doesn't mention error cases (e.g., invalid JQL) or rate limits, but those are minor for a read-only, idempotent operation. The output schema covers return structure, so the description doesn't need to.

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 does: it explains the meaning of jql (Jira query language), the valid range and default for limit, the replacement semantics of fields, and the pagination contract for page_token. It doesn't give JQL syntax examples, but the core semantics of all four parameters are covered, which is strong compensation for zero schema coverage.

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 ('Search'), a resource ('Jira Cloud issues'), and the query mechanism ('with JQL'). It clearly distinguishes this from sibling tools like get_issue (single issue retrieval) and get_comments (comments), so an agent can tell them apart without opening schemas.

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 clear operational context: it explains pagination via next_page_token/page_token, the valid range for limit, and how fields behaves. It doesn't explicitly say 'use this instead of get_issue when you need to search by JQL', but the purpose is clear enough that an agent can infer when to use it. It lacks explicit exclusions or alternative routing, but the context is strong.

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, the description discloses important behavioral details: matching ignores case and surrounding space, transition names may differ from resulting statuses, duplicate statuses are possible, error responses list all available transitions, comments are Markdown, and the comment is posted atomically with the move. This aligns with destructiveHint=true rather than contradicting it.

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 efficient: every sentence adds value, from the primary purpose to matching rules to error behavior to comment semantics. It is front-loaded with the core action and contains 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 state-changing tool with an output schema and annotation coverage, the description provides all necessary invocation details: how to specify the target, what happens on ambiguity, what the error contains, and how comments are handled. 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 coverage is 0%, so the description carries full responsibility for explaining parameters. It thoroughly explains 'to' (transition vs status matching, case/space rules, error fallback) and 'comment' (Markdown, posted in same call). 'issue_key' is self-explanatory from its name, and the description handles the rest with no gaps.

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 opening sentence 'Move an issue through its workflow' uses a specific verb and resource, clearly identifying the operation. It also states 'Changes issue state,' which distinguishes it from siblings like add_comment and update_issue without ambiguity.

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 clear context: use this tool to move an issue through its workflow, with detailed guidance on transition names vs status names. It does not explicitly exclude alternatives or name siblings, so it stops short of a 5.

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?

Goes well beyond the destructiveHint annotation by specifying precisely which fields null clears (assignee, description, priority, parent, duedate) and that labels/components REPLACE the entire list rather than append. This is exactly the 'what gets destroyed' context the rubric credits.

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?

Front-loaded with the purpose, then organized as: accepted formats, null semantics, list-replacement warning, and exclusions. Every sentence earns its place; the dense format list is justified because the schema provides zero descriptions.

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 complex tool with an open-ended fields object, the description covers input formats, null-clearing behavior, destructive list semantics, and exclusions with alternatives. The output schema exists, so not describing return values is acceptable per the rubric.

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 bears full responsibility, and it delivers: it defines the value format for every field type (text, Markdown, account id/'me', list, name, YYYY-MM-DD, issue key, raw Jira JSON for customfield_*). The fields object's additionalProperties true is made meaningful by explaining how to handle custom and unknown fields.

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 ('Set issue fields') and enumerates the exact value formats accepted, referencing get_issue as the source of truth. It explicitly distinguishes itself from siblings by noting it cannot change status (transition_issue) or add a comment (add_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?

Gives explicit when-not guidance with named alternatives: 'Cannot change status (use transition_issue) or add a comment (use add_comment).' Also instructs to read the issue first when intending to add to labels/components, since those lists are replaced wholesale.

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