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

With no annotations provided, the description carries full burden. It explicitly states the mutating action (add a comment) and adds context about preserving the audit trail, which provides useful behavioral insight beyond the bare action. It doesn't cover permissions or reversibility, but for a simple tool this is sufficient.

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 three short sentences, each serving a distinct purpose: stating the action, providing usage context, and noting a behavioral trait. It is efficiently front-loaded with the purpose in the first sentence and contains 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?

The tool is simple (2 parameters, no nested structures, no output schema). The description covers purpose, usage scenarios, and a behavioral note, which is adequate. It doesn't explain return values, but for add_comment this is not necessary given the tool's simplicity.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already fully describes both parameters (comment and issue_key) with examples. The description does not add parameter-specific details beyond what the schema provides, so a 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 with a specific verb and resource: 'Add a comment to a Jira issue.' It also provides specific use cases (investigation steps, evidence, findings, remediation actions) and naturally distinguishes itself from siblings like create_issue, update_issue, and transition_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?

The description gives clear context on when to use the tool ('Use to record investigation steps, evidence, findings, or remediation actions directly on the ticket.'). However, it does not explicitly name alternatives or state when not to use it, which would merit 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?

With no annotations, the description carries the full burden. It adds useful context (returns key/URL, common issue types, project-dependency) but does not disclose potential side effects, permission requirements, or error behaviors. This is adequate 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?

Two sentences, front-loaded with the primary action, then usage context, return value, and common types. 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 an 8-parameter create tool with no output schema, the description covers purpose, when to use, and return value. The schema handles parameter details. It lacks discussion of error scenarios or prerequisites, but is largely complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal parameter-specific meaning beyond the schema's own descriptions, but it does mention common issue types and return behavior that indirectly reflect parameters. No major 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 description clearly states the verb ('Create'), resource ('Jira issue'), and scope ('security incidents, vulnerabilities, or remediation tasks'), and it specifies the return value (issue key and URL). This distinguishes it from siblings like update_issue or search_issues.

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

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

It provides explicit context for when to use the tool ('Use to file security incidents, vulnerabilities, or remediation tasks') and notes that issue types depend on project configuration. It does not explicitly name alternative tools for other actions, but the usage context is clear enough.

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?

Without annotations, the description carries the burden and does disclose what data is returned. However, it does not explicitly state the read-only nature, error behavior, or token-limit handling, leaving some behavioral gaps.

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

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

Two sentences, front-loaded with the main purpose and key details. Every sentence contributes to understanding the tool's use and output.

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 explains the tool's return values and usage context, which is important given no output schema. It lacks error handling or pagination details, but for a single-issue fetch the core information is 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%, so the schema already documents all parameters. The description adds context on return fields but does not add meaningful syntax or detail beyond what the schema provides.

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

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

The description uses a specific verb ('Get') and resource ('single Jira issue by key'), and uniquely identifies the input format with an example (SEC-123). It lists the fields returned, clearly distinguishing it from the sibling search_issues tool.

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 instructs when to use this tool ('Use after search_issues') and provides the purpose ('inspect a specific issue in depth'). This gives clear context relative to the sibling tool.

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

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

With no annotations, the description carries the full burden. It discloses the behavior (a read-only connection test), what it returns (authenticated account info, server version), and the purpose. It doesn't mention edge cases like network errors or permission requirements, but for a simple health check this is adequate.

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 core purpose, and every sentence adds value. No fluff 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 sufficiently explains what the tool does and what it returns, covering the essentials despite having no output schema. It omits details like whether it makes a network call or how long it takes, but that's less critical for a health-check tool.

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

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

Schema description coverage is 100%, so parameters are already fully documented. The description adds no additional meaning beyond the schema, and the parameters (max_tokens, break_token_rule) are generic MCP parameters not specific to this tool.

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 ('Test the Jira connection') and resource (Jira), and distinguishes it from sibling tools by focusing on health check/authentication rather than issue operations. It also specifies the exact output (account info, server version/deployment 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?

The description provides explicit guidance to 'Run first to verify credentials and connectivity,' which tells the agent when to use this tool before other Jira operations. It doesn't explicitly name alternatives or state when not to use it, but the context is clear enough.

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 states the tool lists accessible projects and returns keys, names, and types, but does not disclose aspects like pagination, read-only status, or any side effects. The behavior disclosed is minimal but not 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?

The description is only two sentences long and immediately states the main action. The second sentence provides practical guidance without any wasted words or repetition.

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

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

For a simple list operation, this description adequately covers the core purpose and usage context. The output fields are named, and the tool's relationship to sibling operations is clear. It does not describe every edge case, but the schema handles parameter-level 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 coverage is 100%, with all three parameters described in the input schema. The description does not add additional meaning beyond the schema, nor does it conflict with it. Thus, 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 that the tool lists accessible Jira projects with their keys, names, and types, using a specific verb and resource. It also distinguishes itself from siblings by explicitly connecting to the workflow of finding project keys before creating issues or running JQL queries.

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 explicit context for when to use this tool: to find the correct project key before creating issues or running JQL queries. It does not mention alternatives by name, nor does it provide exclusionary conditions, but the use case is clearly defined.

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

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

No annotations are provided, so the description carries the burden. It discloses the return content (transition IDs and target status names), and the verb 'List' implies a read-only operation. However, it does not explicitly state that no changes are made or mention any prerequisites or error behavior, though the core behavior is transparent.

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 long, front-loaded with the main function, and includes a concrete usage example with status names. 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 listing tool with a fully documented schema, the description provides purpose, return format, and usage context. It is complete enough for an agent to select and invoke the tool correctly, even without an output schema.

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

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

The input schema already provides 100% coverage with descriptions for all three parameters. The tool description does not add parameter-level detail, but since the schema fully documents them, 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: 'List all available status transitions for a Jira issue' and specifies that it returns transition IDs and target status names. It also distinguishes itself from the sibling transition_issue tool by framing this as a preparatory step.

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 says 'Use before transition_issue to find the correct transition ID', providing direct when-to-use guidance and naming the alternative tool. This 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?

With no annotations provided, the description carries the full burden. It discloses the return fields, demonstrates query syntax, and implies a list result. However, it does not mention default ordering, pagination behavior, or error handling, which are minor gaps for a search 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?

The description is efficient and well-structured: first sentence states the function, second lists return fields, third provides domain-specific use cases, and the remaining sentences give concrete examples. No wasted words.

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

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

Given the moderate complexity (6 params, no output schema), the description covers purpose, return fields, and use cases, while the schema handles parameter details. It is complete enough for an agent to select and invoke the tool correctly without additional 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 schema already documents all parameters. The description adds value via JQL examples but does not elaborate on parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Search Jira issues using JQL' with a specific verb and resource, and the JQL method distinguishes it from get_issue and other issue tools. It also lists the exact fields returned, making the purpose unambiguous.

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

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

It provides clear use cases ('Use for finding security incidents, open vulnerabilities, or tracking remediation tasks') and includes example queries that show the intended usage. It does not explicitly contrast with sibling tools like get_issue, but the context is sufficient for an agent to decide when to use this search tool.

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

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

With no annotations provided, the description must carry the transparency burden. It discloses the core mutation (status change) and the optional comment attachment, including an example. However, it does not mention permissions, reversibility, or error behavior, which would be useful for a mutation tool. The disclosed behaviors are accurate but minimal.

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

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

The description is two sentences long and front-loaded: first the primary action, then the prerequisite, then optional behavior with an example. Every clause contributes meaningful guidance with no filler.

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

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

Given the tool's simplicity (three flat parameters, no output schema, no nested objects), the description covers the essential workflow: decide the transition, get the ID from list_transitions, and optionally add a comment. It lacks return value details, but that is acceptable given the absence of an output schema and the straightforward nature of the 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?

User-provided schema descriptions already cover 100% of parameters, so the baseline is 3. The tool description adds value by explicitly linking transition_id to list_transitions output and providing a sample comment rationale, which goes beyond the schema's basic parameter 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 specifies the verb 'Move' and the resource 'Jira issue to a new status', and identifies the mechanism 'using a transition ID'. It distinguishes itself from sibling tools like update_issue by focusing on status transitions and pointing to list_transitions for ID discovery.

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 states 'Use list_transitions first to discover available transition IDs', providing a clear prerequisite and coordinating with a sibling tool. It does not explicitly exclude alternatives or list when not to use, but the context is clear enough for an agent to choose 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?

With no annotations, the description does not disclose mutation implications, partial update behavior, or reversibility. It only repeats the action and field list, offering no additional context beyond what the name implies.

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

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

Three short sentences with no filler. Each sentence provides distinct value: what it does, when to use it, and the status-change alternative.

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 purpose, use case, and a key alternative. However, it does not mention whether unspecified fields remain unchanged or what the response contains, which would be useful for a mutation tool without an output schema.

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

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

The schema has 100% description coverage for all five parameters, so the baseline is 3. The description merely lists field names without adding any extra meaning, such as update semantics for omitted 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?

The description uses 'Update fields of an existing Jira issue' with a specific verb and resource, and lists the affected fields. It also distinguishes itself from transition_issue by explicitly redirecting status changes.

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

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

It states 'Use to enrich a security incident with investigation findings' and explicitly says 'To change status, use transition_issue instead.' This provides both a suggested use case and a clear alternative.

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