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

No annotations are provided, and the description only states the action without disclosing side effects, permission requirements, or return behavior. As a write operation, it would benefit from noting whether it requires edit permissions or returns the created 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?

The description is a single, clear sentence that front-loads the action and resource 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?

The tool is simple with two fully documented parameters, but the description lacks any mention of return values or success indicators, and no output schema exists to fill that gap. It is adequate for a basic understanding but not 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?

The input schema fully describes both parameters (issueKey and body) with examples, so the description adds no additional parameter-level information. Baseline of 3 applies due to high 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 clearly states the action (add) and the resource (a comment to a JIRA issue), distinguishing it from sibling tools like jira_get_issue_comments or jira_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?

No guidance is provided on when to use this tool over alternatives, such as jira_get_issue_comments for reading comments or jira_update_issue for editing fields. The description simply states the action without any context or exclusions.

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

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

The description discloses that the tool creates an issue and returns the key/ID, which conveys the mutating nature and basic return behavior. However, with no annotations, it does not cover permissions, error conditions, or other side effects, leaving some transparency gaps.

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

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

The description is two concise sentences, front-loaded with the action and a clear return value. Every word earns its place with no fluff.

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

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

Given the tool's complexity (10 parameters, nested customFields) and lack of output schema, the description provides minimal context. It covers the core purpose and return value but does not address edge cases or special considerations, making it adequate but not comprehensive.

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 each parameter described. The description adds no parameter-specific information beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action 'Create a new JIRA issue' with a specific verb and resource. It distinguishes this tool from siblings like update or transition by explicitly indicating 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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention scenarios, prerequisites, or refer to sibling tools, leaving usage decisions entirely to the 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?

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It only states the action and does not mention side effects such as overwriting an existing file, required permissions, error conditions, or what is returned after the download.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the core purpose without 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?

The tool is simple, with only two fully documented parameters, so the description is adequate for basic understanding. However, it lacks information about return values, overwrite behavior, or error handling, leaving some gaps given that no output schema or annotations are present.

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%, and both parameters (attachmentId and outputPath) are clearly described in the schema. The description adds no additional semantic value beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: "Download an attachment from JIRA to a local file path." It clearly identifies the action (download), the object (attachment), and the destination, distinguishing it from sibling tools like jira_upload_attachment and jira_list_attachments.

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 intended use is implied: use this tool when you need an attachment's content saved locally. However, there is no explicit when-to-use guidance, no mention of prerequisites like getting the attachment ID from jira_list_attachments, and no 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states what is returned, but does not mention read-only semantics, error behavior, or what happens if no active sprint exists. This is insufficient for a tool with no annotations.

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

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

The description is a single sentence, directly stating the action and return value. It is front-loaded and contains no unnecessary words, making it highly concise and well-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 simple getter with one parameter, no output schema, and no annotations, the description covers the core purpose and return fields. However, it omits edge-case behavior (e.g., no active sprint) and does not specify the exact response format, leaving some gaps.

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

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

The schema already describes boardId as 'The ID of the JIRA board' with 100% coverage. The tool description adds no additional parameter semantics, so a baseline score of 3 is appropriate since 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 clearly states the tool gets the currently active sprint for a specific board, with a specific verb and resource. It distinguishes from sibling tools like jira_list_sprints by focusing on the active sprint and explicitly listing return fields (ID, name, dates, goal).

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

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

The description implies usage when the active sprint is needed, but does not explicitly mention alternatives or exclusion criteria. It is clear from context, but lacks direct guidance such as 'use jira_list_sprints to see all sprints'.

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?

Discloses default grouping, custom pivoting, and aggregation actions. However, it claims 'any field pair' pivoting, which the schema's enum lists contradict—behavioral overstatement. With no annotations, the description carries burden but is partially misleading.

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?

One dense sentence that front-loads the core function and key capabilities without wasted words. Efficient and well-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 tool with 9 parameters, nested pivot object, and no output schema, the description gives a good overview but omits several filter parameters (sprint, boardId, assignees, etc.). The overstatement reduces reliability, though schema fills most gaps.

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

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

Schema covers 100% of parameters with descriptions, so baseline applies. The description adds context for pivot and fieldFilters, but the 'any field pair' claim is inaccurate given the schema enums, so it adds no real value 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 states it 'gets aggregated statistics for issues matching a JQL query' and lists default groupings, clearly distinguishing it from raw issue retrieval tools like jira_search_issues. Specific verb and resource make it 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 implies use for statistical aggregation via 'aggregated statistics' and mentions pivoting/filtering, but it does not explicitly contrast with alternative tools or state when not to use it. Clear context, but no 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 the transparency burden. It adds behavioral context: returns all required fields, includes custom fields, allowed values, and format hints. It does not disclose side effects, but this is a read-only operation. It could elaborate on response structure, but the essentials are present.

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

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

The description is concise and front-loaded, beginning with an imperative directive and followed by a clear explanation of return contents. Every sentence earns its place, with no unnecessary detail.

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

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

Given no output schema and no annotations, the description gives a high-level overview of the returned data. It informs the agent of the key information needed to invoke the tool correctly. A bit more detail on response format would push it to 5, but it is adequate for the tool's purpose.

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 each parameter clearly described. The description does not add extra parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the function: to discover required fields and formats before creating an issue. It distinguishes from siblings like jira_create_issue by focusing on pre-creation field discovery and from jira_get_field_schema by targeting required fields for a specific project and issue type.

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 usage guidance: 'Call this BEFORE creating an issue' with rationale (prevents errors). Does not mention alternatives or when-not-to-use, so it lacks full exclusion criteria, but the context is clear and actionable.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. The description appropriately indicates it returns field metadata, but does not explicitly state that it is read-only or what side effects (if any) exist. For a 'get' tool, this is acceptable but not rich.

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

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

The description is concise, consisting of two sentences that state the purpose and provide a practical use case. It avoids unnecessary details and is well-structured for quick understanding.

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 tool with three optional parameters and no output schema, the description is sufficiently complete. It explains what the tool returns and why it is useful, though it does not detail the response structure or edge cases.

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

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

The input schema provides 100% coverage for all three parameters, each with descriptive text. The description adds a small amount of context by mentioning custom field IDs and providing an example for searchTerm, but it does not substantially enhance the schema's explanations.

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 retrieves JIRA fields with their IDs, names, and types, and even provides a concrete use case (discovering custom field IDs for stats aggregations). It does not explicitly distinguish itself from sibling tools like jira_get_create_fields, but the focus on field metadata is evident.

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 a clear usage scenario (discovering custom field IDs) and implies the tool is for retrieving field schemas. It does not mention when not to use it or list alternative tools, but the context is sufficient for a simple read-only operation.

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 behavioral burden. It discloses that the tool returns all fields by default, includes custom fields, and that the fields parameter can reduce response size. The verb 'Get' appropriately signals a read-only operation.

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

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

Two short sentences front-load the core purpose and add only valuable usage guidance. No filler or repetition.

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

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

For a simple 2-parameter read tool, the description covers the essential behavior and the fields parameter. It lacks explicit return-value structure, but the default-to-all-fields mention plus schema enumerations provide adequate 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 description coverage is 100%, so the baseline is 3. The description adds no significant meaning beyond the schema; it repeats the example key and the field-reduction guidance already present in 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 tool 'gets detailed information about a specific JIRA issue by its key' with an example key format. It also notes that all fields are returned by default, distinguishing it from sibling tools like history or comments.

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

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

The description establishes when this tool is appropriate: when you have a specific issue key and need its details. It does not explicitly name alternatives, but the context is clear enough to differentiate from search/list siblings.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only mentions the return fields and gives no information about pagination (maxResults), ordering, authentication needs, or side effects. For a read operation, the lack of these details leaves the agent under-informed.

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, efficient sentence that states the purpose and key return values with no filler. It is front-loaded and every word contributes meaning.

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?

With no output schema and no annotations, the description needs to explain the return behavior more fully. It lists the returned fields but omits critical details about maxResults (defaults to 20, implying pagination) and does not clarify whether all comments are returned or just a subset. This leaves an incomplete understanding of the tool's 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?

The input schema provides full descriptions for both parameters (issueKey and maxResults), which covers 100% of the parameter documentation. The description adds no additional parameter semantics beyond that, so the baseline score of 3 is appropriate.

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

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

Clearly states the verb 'Get' and the specific resource 'comments on a specific JIRA issue', which distinguishes it from siblings like add_comment, update_issue, and get_issue_history. It also lists the returned fields (author, body, creation date), adding clarity.

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 explicit guidance is provided on when to choose this tool over alternatives such as jira_get_issue_history or jira_search_issues. The usage is only implied by the verb and resource, with no exclusions or 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 burden for behavioral disclosure. It conveys a read-only intent via the verb 'get' and specifies the scope of returned data, but it omits details about error handling, response structure, or pagination 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 a single, focused sentence that communicates the core purpose without redundant wording. It is front-loaded and easy to parse.

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

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

For a simple read tool with no output schema, the description provides a useful summary of the returned data and the operation's scope. However, it omits details about the response format or how pagination works via maxResults, which would be helpful for an agent to correctly process the results.

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

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

The input schema fully documents both parameters (issueKey and maxResults) with clear descriptions, achieving 100% schema coverage. The tool description does not add additional meaning or constraints beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool as retrieving the changelog/history of a JIRA issue, explicitly listing the types of content returned (field changes, status transitions, modifications). This distinct resource and scope differentiates it from siblings like jira_get_issue, which retrieves current state.

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

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

The description implies usage when historical changes are needed, but it does not explicitly reference alternatives or state when not to use the tool. There is no mention of jira_get_issue or search tools, making the guidance implicit 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?

With no annotations, the description carries the transparency burden. It discloses the filtering behavior, return fields (keys, summaries, statuses, priorities), default sort order, and the ability to customize fields. It does not mention pagination behavior or error cases, but the schema covers maxResults and the core behavior is well explained.

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 purpose, followed by filter, return values, sorting, and customization. Every sentence earns its place with no redundant information or fluff.

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

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

For a simple read tool with clear schema and no output schema, the description explains the purpose, filter, returned fields, sorting, and field customization. It does not mention how to obtain sprintId, but sibling tools like jira_get_active_sprint and jira_list_sprints cover that, and the schema makes sprintId required. Overall, it provides enough context 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 100%, so the baseline is 3. The description adds context about the fields parameter's purpose and the default field set, but it does not add meaning to sprintId or maxResults beyond their 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?

The description clearly states the tool gets issues assigned to the current user in a specific sprint, with the filter 'assignee = currentUser()' explicitly stated. This distinguishes it from sibling tools like jira_get_sprint_issues, which likely returns all issues in a sprint.

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

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

The description provides clear context that this is for the current user's issues in a sprint, implying when to use it. It does not explicitly name alternative tools or state when not to use it, but the 'currentUser()' filter and mention of specific fields make the use case unambiguous.

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 discloses default return fields and customization via the fields parameter, which is useful. However, it does not mention pagination behavior (despite maxResults being in the schema), potential large result sets, or any limitations like whether 'all' truly means all or is capped. No side effects or auth requirements are mentioned, but for a read tool this is partially acceptable.

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, front-loaded with the primary purpose, and every word earns its place. It avoids redundancy with the schema while providing just enough overview.

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 straightforward read tool with 3 parameters and no output schema, the description covers the main purpose, default return shape, and customization capability. It lacks explicit usage guidance and pagination nuances, but it is largely complete for an agent to invoke correctly. Minor gaps prevent a 5.

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 each parameter having a description. The description adds minimal value—only reiterating that the fields parameter allows customization. Since the schema already documents defaults and the customFields enum, the baseline of 3 is appropriate.

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

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

The description clearly states the specific action: 'Get all issues in a specific sprint.' It also lists the default returned fields, distinguishing this from other sprint-related tools like jira_get_active_sprint or jira_get_sprint_report. The verb and resource are explicit and 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 implies usage when you need issues for a given sprint, but it does not explicitly contrast with sibling tools such as jira_get_my_sprint_issues or jira_search_issues. No when-not-to-use scenarios or alternative suggestions are provided, leaving the agent to infer from context.

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 explains what data is returned but does not state read-only nature, permission requirements, or potential side effects (e.g., heavy API usage). This is acceptable but leaves some behavioral ambiguity.

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 concise sentences, front-loaded with purpose and clear outcome enumeration. Every word adds value, with no fluff or repetition.

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

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

Despite having 10 parameters and no output schema, the description covers the key output categories and comparison behavior. The rich schema compensates for parameter details, but the description could be slightly more explicit about the report's structure or configuration options.

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 every parameter having a description. The tool description adds no extra parameter syntax but does align report metrics with parameter groups (status categories, bug metrics, labels), which is mildly helpful. Baseline 3 applies.

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

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

The description clearly states the tool generates a sprint report for retrospectives, listing specific output categories (issue counts, story points, bug metrics, label tracking) and the comparison with the previous sprint. This distinguishes it from sibling tools like jira_get_sprint_issues or jira_get_backlog_stats.

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

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

The description explicitly mentions 'for retrospectives', providing a clear use case. It does not name alternative tools or exclusions, but the context is sufficiently clear for an agent to select this tool when a retrospective sprint report is needed.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only restates the function ('Get available status transitions') without disclosing whether it is read-only, any permission requirements, or side effects. This adds little beyond the tool name.

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

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

The description is concise at two sentences, but the second sentence ('Use this to see...') is somewhat redundant with the first, though it does serve as a usage guideline. Minor redundancy prevents a perfect score.

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

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

For a simple read-only tool with one well-documented parameter, the description is adequate: it clearly states the purpose and usage. It does not mention output format or permission restrictions, but the simplicity and schema coverage keep it complete enough for selection and 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?

The schema fully documents the single parameter issueKey with a description and example, giving 100% coverage. The description does not add extra meaning beyond associating the parameter with an issue, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get available status transitions for an issue.' The verb 'Get' and resource 'status transitions' are specific, and the description naturally distinguishes this from sibling tools like jira_transition_issue (which performs the transition) and jira_get_issue_history (which shows 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 explicit usage context with 'Use this to see what statuses an issue can be moved to,' which tells the agent when to use it. However, it does not explicitly name alternatives or state when not to use it, though the sibling tool names imply the distinction.

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 burden of behavioral disclosure. It discloses the return fields (IDs, filenames, sizes, types) but does not mention side effects, pagination, auth requirements, or error behavior. 'List' implies read-only, but the description could be more explicit about what to expect.

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

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

The description is two concise sentences, front-loaded with the primary purpose and followed by return details. No wasted words, and every clause adds value.

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 (one parameter, no output schema), the description is complete: it explains what it does and what it returns. It does not need to explain pagination or edge cases for a straightforward list operation, and sibling tools cover upload/download separately.

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

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

The input schema already provides 100% coverage for the single parameter (issueKey) with a clear example. The description adds no additional parameter semantics beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('List') and resource ('attachments on a JIRA issue'), and mentions the return type. It distinguishes from sibling tools like download/upload attachments by focusing on listing.

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

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

The description implies usage (when you need to list attachments) but does not explicitly mention alternatives or exclusions. It does not say 'use this instead of download_attachment' or provide when-not-to-use guidance, so it relies on the agent's inference from the tool name and purpose.

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 transparency burden. It discloses the operation is a read-only listing ('List'), and specifies the return fields. It does not mention pagination, rate limits, or authentication requirements, but for a simple list operation, the key behavioral traits are covered.

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, well-structured sentence that front-loads the action and resource, then lists the output fields. Every word adds value, with no filler or repetition.

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

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

Given the zero-parameter schema and absence of an output schema, the description sufficiently explains what the tool does and what it returns. It is complete enough for an agent to select and invoke the tool correctly. Slight gap: no mention of whether 'accessible' includes archived boards or permissions constraints, but this is not critical for a list operation.

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

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

The tool has zero parameters, so the schema is empty. The description adds meaningful information about what the tool returns, which is the only semantic context needed. No parameter documentation is required, earning the baseline of 4.

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

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

The description clearly states the action ('List'), the resource ('all accessible JIRA boards'), and the output scope (IDs, names, types, project keys). This unambiguously distinguishes it from sibling tools like jira_list_sprints or jira_list_attachments.

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 explicit guidance on when to use this tool versus alternatives. However, the phrase 'List all accessible' implies it serves as a discovery mechanism for boards, and sibling names don't overlap with this function. Usage context is implied but not stated.

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 transparency burden. It discloses supported field types but does not explicitly state the read-only nature, output format, or pagination behavior. The 'list' verb implies non-mutating, but lacks detail.

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 concise sentences, front-loaded with the main action, and no filler or redundant 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?

For a simple tool with a rich schema, the description adequately covers purpose and usage. While it doesn't describe return values (no output schema), it is acceptable for a listing tool. Missing notes on pagination/defaults, but schema covers parameter details.

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 descriptions cover all 4 parameters with 100% coverage, including the enum for field and projectKey requirement for components. The description restates supported fields but adds little beyond schema; the usage context is a minor addition.

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 uses specific verb 'List' with resource 'discrete values for a JIRA field' and enumerates supported field types (labels, priorities, statuses, etc.), clearly distinguishing it from sibling tools focused on issues, sprints, and attachments.

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?

States 'Useful for discovering valid values before creating/updating issues,' providing a clear use case. It does not explicitly exclude alternatives, but the context is sufficient to guide 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?

With no annotations, the description carries the transparency burden. It does disclose useful behavior: return fields, sorting order, and pagination support. However, it does not explicitly state that the operation is read-only, nor does it mention potential errors or permission requirements. This is a moderate disclosure level for a list operation.

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

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

The description is concise, consisting of two sentences, and is front-loaded with the action verb. Every sentence contributes value without repetition. It avoids unnecessary fluff and is easy to scan.

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

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

The description covers the tool's primary purpose, return fields, sorting, and pagination, which is decent for a list operation. However, it omits the important constraint that either boardId or projectKey is required (only implied in schema) and does not mention filtering by state. It also lacks any reference to sibling tools or error conditions, leaving the agent to infer some usage 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 description coverage is 100%, so each parameter is already well documented in the input schema. The description adds only high-level context about sorting and pagination, which does not materially enhance understanding of the individual parameters. Baseline 3 is appropriate given the schema already carries the burden.

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

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

The description uses the clear verb 'List' and specifies the resource as 'sprints for a board or project', which is unambiguous. It also names the return fields, adding specificity. However, it does not explicitly distinguish itself from sibling tools like jira_get_active_sprint or jira_get_sprint_report, so it stops short of a full 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that for a single sprint's details one should use jira_get_active_sprint or jira_get_sprint_report, nor does it highlight the either/or requirement for boardId and projectKey. The only implied usage is 'list sprints', which is too vague for effective tool selection.

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

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

With no annotations, the description must carry the full behavioral disclosure burden. It discloses the default result cap and the rejection of unbounded queries, which are important traits. However, it does not mention pagination via nextPageToken (though the schema covers it), nor explicitly state that this is a read-only operation. The description adds context but remains incomplete for full transparency.

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

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

The description is concise, with two sentences and an example. The IMPORTANT warning is prominent and useful. Every sentence adds value, with 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?

The description covers the core operation, default limit, and the critical bounded-query constraint. The schema provides parameter details and pagination via nextPageToken. The absence of an output schema is mitigated by the fields parameter that indicates return structure. Minor omissions like ordering and error handling are not critical for this search tool.

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

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

Schema coverage is 100%, providing baseline parameter descriptions. The description adds extra value by giving a concrete JQL example and emphasizing the bounded-query requirement, which directly enriches the understanding of the jql parameter. This goes beyond merely repeating schema information.

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 'Search for issues using JQL', specifying the verb (search) and resource (issues). It distinguishes itself from sibling tools like jira_get_issue and jira_get_sprint_issues by focusing on JQL-based search. The example further clarifies the exact usage.

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 usage context, notably that queries must be bounded with a project filter or other restriction, and that results default to 50. It doesn't explicitly mention alternatives, but the JQL constraint is a key practical guideline. This is more than implied usage, but lacks direct exclusions or alternative tool mentions.

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 transparency burden. It discloses the return of accountId, which is useful, but does not mention pagination, permissions, or any limitations. The read-only nature of 'search' is implicit but not stated explicitly.

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

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

Two sentences, each with a clear purpose: the first states the action and criteria, the second states the output and use case. There is no redundant or filler content.

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?

With no output schema, the description covers the key return value (accountId) and a high-level use case. It does not describe the full result structure, but for a simple search tool it is sufficient. Missing details like pagination behavior are not critical for the agent's decision to use the tool.

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

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

Schema descriptions cover both parameters (query and maxResults) with clear descriptions, so schema coverage is 100%. The tool description does not add additional parameter semantics beyond what the 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?

The description uses a specific verb 'Search' with resource 'JIRA users' and lists searchable attributes (name, email, display name). It distinguishes this tool from siblings, as no other sibling tool performs user search.

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

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

The description clearly implies when to use the tool (when a user lookup is needed) and explains that the returned accountId can be used for mentions or assignments, giving a concrete use case. It does not explicitly mention exclusions, but no sibling tool overlaps, so this is acceptable.

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

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

No annotations are provided, so the description must disclose side effects. It only mentions the prerequisite for valid transition IDs, but does not explain success/failure behavior, permission requirements, or reversibility. This is a significant gap for a mutation 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 concise sentences, front-loaded with the action verb. Every word earns its place without 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?

The description is adequate for a simple transition but lacks return value info and failure semantics. With no annotations and no output schema, it could do more to explain the outcome of the transition.

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 all 3 parameters at 100% coverage, but the description adds value by pointing to jira_get_transitions as the source for transitionId. The comment parameter is already adequately described in 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?

States 'Transition an issue to a new status' – a clear verb+resource that differentiates from create/update tools. The prerequisite mention adds context without obscuring the primary purpose.

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

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

'Use jira_get_transitions first' explicitly tells the agent the necessary prerequisite. It does not explicitly exclude alternatives, but the direction is clear enough for a transition 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?

No annotations are present, so the description must convey behavioral traits. It only restates the schema fields without explaining mutation semantics (e.g., whether labels are replaced wholesale, whether partial updates are supported, or permission requirements). The description adds no behavioral context beyond the fact that it updates fields.

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 with no filler. The key action is front-loaded and the field list is compact. Every word earns its place.

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

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

The tool is a relatively simple update operation with a rich schema, but the description omits any mention of return value or side effects. Given no output schema and no annotations, a bit more detail (e.g., that only specified fields are changed) would improve completeness. Still, the schema explains the parameters, so it meets the minimum viable level.

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?

All 7 parameters are fully documented in the schema (100% coverage). The description adds no additional semantic detail beyond listing field names, which already appear in the schema. Baseline 3 applies because the schema carries the parameter meaning.

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 'Update fields on a JIRA issue' and enumerates the specific fields (summary, description, assignee, priority, labels, custom fields). This distinguishes it from sibling tools like jira_transition_issue (status changes) and jira_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?

No explicit when-to-use or exclusionary guidance is provided. The list of updatable fields gives an implicit sense of scope (e.g., status transitions are not listed), but the description does not direct the agent to alternatives or warn against misuse. It merely states what it can update.

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, placing the full burden on the description. The description only states the action without disclosing behavioral details such as whether the upload overwrites existing files, size limits, authentication requirements, or error behaviors. This is a significant gap 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?

The description is a single, well-structured sentence that directly states the tool's purpose without any filler or redundant phrases. It is appropriately sized for the tool's simplicity.

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 no annotations and no output schema, the description fails to convey necessary context such as when to use it, potential side effects, or the response format if any. The tool is simple, but the description remains incomplete for an agent to invoke it 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?

Both parameters (issueKey and filePath) are fully described in the input schema, so the schema provides 100% coverage. The description adds no parameter-specific meaning beyond what the schema already offers.

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 'Upload' and clearly identifies the resource: a file as an attachment to a JIRA issue. This distinguishes it from sibling tools like jira_list_attachments and jira_download_attachment, which have different 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?

The description provides no guidance on when to use this tool versus alternatives, such as when to choose it over jira_add_comment for attaching context. There is no mention of prerequisites like existing attachment schemes or exclusions, leaving the agent without decision support.

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