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

With no annotations provided, the description carries the burden of behavioral disclosure. It does reveal that the body is treated as Confluence storage-format XHTML, which is a non-obvious behavioral trait. However, it omits other useful behaviors like return value, error handling, or permission requirements, leaving those to the agent's inference.

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, with the core purpose front-loaded. Every word earns its place; there is no redundancy or 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?

The tool has 4 parameters, no output schema, and no annotations. The description covers the core action and the body format caveat, but it lacks guidance on return values, error conditions, prerequisites (e.g., space existence), and when to use create vs update. It is minimally adequate but leaves several usage questions unanswered.

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 75% (3 of 4 params have descriptions). The description adds a small clarification about body format ('pass HTML-ish markup, not markdown') that goes slightly beyond the schema's body description, but it does not add meaning for title, spaceKey, or parentId. Overall, the schema does most of 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 opens with 'Create a new Confluence page'—a specific verb+resource that clearly distinguishes this tool from sibling tools like confluence_update_page, confluence_search, and confluence_get_page. The additional note about body format reinforces the purpose by clarifying what kind of content is expected.

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 for creating pages but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. The body format note is more about parameter usage than tool selection, so it does not fully address how this tool fits relative to 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 carries the full burden. It does disclose a key behavior: body is converted from storage format to plain text by default, and mentions the format parameter controls this. However, it does not discuss potential errors, auth requirements, or what other fields are returned, leaving some behavioral aspects undisclosed.

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 that immediately states the action and resource, then clarifies the body handling. Every word adds value, with no redundancy or 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 low complexity (2 params, 1 required) and no output schema, the description is sufficient to convey the core function and body format behavior. It could mention that other page fields are returned, but for a simple fetch-by-id tool this is not a critical omission. The absence of annotations is partially compensated by the explicit body conversion note.

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 describes both parameters fully (pageId as numeric string, format enum with descriptions). The description's reference to 'storage format converted to plain text' aligns with the schema but does not add meaning beyond it. With 100% schema coverage, 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 uses the specific verb 'Fetch' with the resource 'Confluence page by id', and explicitly notes the body conversion behavior. It clearly distinguishes from sibling tools like confluence_search, confluence_create_page, and confluence_update_page, which have different verbs and purposes.

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 indicates when to use the tool: to fetch a page by its id. It does not explicitly mention exclusions or alternatives, but the context of 'by id' implies this is for targeted retrieval rather than search or modification. The lack of explicit 'when not to use' is a minor gap.

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 behavioral disclosure. It states that the tool returns title, space, and URL, but it does not address pagination, rate limits, permissions, or whether the search is read-only. While a search operation is inherently non-destructive, the absence of any safety hints or additional behavioral details leaves some 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 a single sentence with an inline example, front-loaded with the verb and resource. It is concise and every word earns its place, achieving maximum efficiency.

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

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

For a simple two-parameter search tool with no output schema and no annotations, the description covers the core purpose, provides a usage example, and states the return fields. It does not explain pagination or result-count behavior, but given the low complexity and the schema detailing limit, this is reasonably 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 schema covers both parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by providing a concrete CQL example, clarifying the query format beyond the schema's generic 'CQL query'. The limit parameter is already well-documented in the schema, so no further description is needed.

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: 'Search Confluence content with CQL' with a specific verb and resource. It provides an example query and listing return fields, which distinguishes it from sibling tools like jira_search (Jira) and confluence_get_page (retrieves a specific page).

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 for when to use this tool: searching Confluence content via CQL. The example query illustrates usage, and the return fields indicate practical output. However, it does not explicitly mention when not to use it or contrast with alternatives like jira_search or confluence_get_page, though the Confluence-specific scope is implied.

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 a non-obvious Confluence constraint (drafts stay at version 1) and clarifies status transition behavior, going beyond a simple 'update' statement. It doesn't mention response/error behavior, but that's not critical for this 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 primary action. Every clause 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?

For a 4-parameter update tool with no output schema and no annotations, the description is fairly complete. It covers the key behavioral nuance (status/versioning) and leaves parameter details to the schema. It doesn't mention return values, but that's not essential for an update 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 schema already provides descriptions for body, title, and status (75% coverage). The description adds the version-1 constraint for drafts, but largely mirrors the schema's status explanation. It doesn't add meaning for pageId or other parameters.

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

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

The description opens with 'Update a Confluence page' – a specific verb and resource. It clearly differentiates from sibling tools like create_page and get_page by focusing on updating existing pages, and adds unique status-handling details.

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 clear context for when to use status='current' to publish a draft and explains the default preservation of draft/current status. It doesn't explicitly name alternatives, but the update-vs-create distinction is evident from the tool name and sibling list.

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 carries the full burden. It does not disclose side effects (e.g., comment append), permissions required, or error behavior. The phrase 'plain-text' offers a minor detail but does not explain conversion to Atlassian Document Format as the schema does, nor any other behavioral traits.

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 concise sentence with a clear verb-object structure (`Add a plain-text comment to a Jira issue`). Every word is meaningful, and there is no redundant or irrelevant information.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description covers the core behavior adequately. However, it lacks any mention of what happens on success (e.g., return value) or edge cases, but for a simple mutation this is acceptable.

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

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

Schema description coverage is 100% (both key and body are described). The description adds no parameter information beyond the schema, so the baseline of 3 applies. It merely reinforces the 'plain-text' aspect already implied by the schema's body description.

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 'Add' and clearly identifies the resource: 'a plain-text comment to a Jira issue'. This distinguishes it from sibling tools like jira_create_issue (creates issues) and jira_update_issue (updates fields), making its 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?

No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description merely states the action without contextualizing decision-making, such as when to choose this over jira_create_issue or jira_update_issue.

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 carries the full burden of behavioral disclosure. It only states the action without detailing side effects, permissions, idempotency, or behavior when issues are already in the sprint. For a mutation tool, this is insufficient 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 a single, front-loaded sentence with no unnecessary words. Every word contributes to understanding what the tool does, making it 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 2-parameter tool with complete schema coverage, the description is minimally viable. It lacks information on return values or error handling, but the low complexity and clear action make it adequate, though not rich in 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 coverage is 100%, with clear descriptions for sprintId and issueKeys. The description does not add extra parameter semantics beyond the schema, but it also does not need to, given the schema's clarity.

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 moves one or more issues into a sprint, using a specific verb and resource. It also mentions 'Agile API' to distinguish it from standard Jira operations, aligning with its function among siblings.

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 the use case (moving issues to a sprint) but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like jira_list_sprints or jira_update_issue. This leaves some ambiguity about the preferred 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 provided, the description carries the full burden of disclosing behavior. It reveals that description text is converted to ADF, and provides project-specific constraints (e.g., CAKE issues are Feature-type epics only). These details go beyond a simple 'create' statement, though it does not address permissions, return values, or error handling.

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 sentences, front-loaded with the primary purpose, and every sentence adds distinct value: purpose, conversion/linking guidance, and project-specific rules. 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?

Given the 9-parameter schema with strong coverage and no output schema, the description provides sufficient context for correct usage by covering the key decision points (linking and project rules). It omits explicit return-value/error details, but these are less critical for a create operation with no 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?

Schema coverage is high (89%), so the baseline is 3. The description adds meaningful parameter guidance by explaining when to use epicKey (company-managed) vs parentKey (team-managed or sub-task grouping) and by mapping projectKey/issueType to specific projects (NUTLA for stories/defects, CAKE for feature epics). This clarifies decision-making 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 starts with 'Create a new Jira issue', a specific verb+resource that clearly distinguishes it from sibling tools like jira_update_issue, jira_search, and jira_add_comment. It further clarifies the tool's scope by explaining epic/parent linking and project-specific issue types.

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 offers clear context on when to use epicKey vs parentKey based on project management style, and specifies that Stories/defects go in NUTLA while CAKE is for Feature epics only. It does not explicitly name alternative tools or state when not to use this tool, but the create-only purpose is implicit from the name.

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 convey behavior. It adds useful context about the response including 'description and recent comments', but it does not explicitly state that this is a read-only operation or describe error handling. The 'Fetch' verb implies safety, but more disclosure would be better.

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, compact sentence that leads with the action and resource. 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?

For a simple read tool with two well-documented parameters and no output schema, the description gives enough context to understand the tool's purpose and output highlights. It does not describe all return fields, but that is acceptable given its simplicity. A more explicit statement about the full response shape would warrant 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% for both parameters (key and includeComments), so the baseline is 3. The description adds no extra meaning beyond the schema; it only mentions 'description and recent comments' which relates to the response, not parameter details.

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 ('Fetch'), the resource ('a single Jira issue'), and the key mechanism ('by key'). It also differentiates from siblings like jira_search by indicating it retrieves one specific issue rather than searching.

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

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

The phrase 'by key' clearly indicates when to use this tool (when you have a known issue key), and the context is clear. However, it does not explicitly mention when to use alternatives like jira_search or exclude cases where the key might be unknown.

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 behavioral disclosure burden. It adds context about the Agile API and the state filter, but it does not mention pagination, response format, or permission requirements. For a simple read-only list operation, this is acceptable but not highly 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?

Two concise sentences with the action verb front-loaded. Every word adds value, no redundancy. The structure is clean and easily scannable.

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 simple listing operation with a well-defined schema and no output schema. The description covers the core functionality and a key use case. It lacks details on pagination or response shape, but given the simplicity, it is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds a small usage hint for the 'state' parameter (to find the active sprint) but does not go beyond the schema's field descriptions. Base 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 uses a specific verb ('List') and identifies the exact resource ('sprints for a Jira Software board'), also noting the Agile API. It clearly distinguishes this from sibling tools like jira_search or jira_get_issue by focusing on sprint 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 explains that filtering by state helps find the active sprint, giving a practical usage hint. It does not explicitly exclude alternatives, but the verb+resource combination makes the intended use obvious. Lacks explicit when-not-to-use guidance, so not 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 provided, the description carries the burden of disclosing behavior. It states it returns a compact list and enumerates the fields, which clarifies the output format. The verb 'search' implies a read-only operation, though it does not explicitly declare the absence of side effects or any authentication requirements.

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, no filler, and front-loaded with the action and expected output. Every clause adds 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 read-only search tool, the description covers the core purpose, the return payload, and (via schema) parameter constraints, which is sufficient given the tool's simplicity. No output schema exists, but the description compensates by naming the exact fields returned.

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 three parameters have schema descriptions, giving a baseline of 3. The description adds value by specifying the default field set ('key, summary, status, assignee, priority, updated'), which directly clarifies what the 'fields' parameter means by 'beyond the default summary set'. This counts as extra semantic detail 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 opens with 'Search Jira issues with a JQL query', which names a specific action (search) and resource (Jira issues) using the JQL query language. It also specifies the return scope ('compact list' with exact fields), distinguishing it from jira_get_issue (single issue retrieval).

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 clearly states the tool is for searching Jira issues via JQL, implying use for broad queries rather than single-issue retrieval (which is covered by sibling jira_get_issue). However, it does not explicitly mention alternative tools or exclusion cases, so it earns 4 rather than 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses the dual behavior (listing vs applying) and mentions selection by id or name, but it does not mention side effects of applying a transition, such as changing the issue status irreversibly or triggering notifications. This is a notable 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?

The description is a single, compact sentence with no redundancy. It front-loads the primary action and packs both modes concisely, making every word count.

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 return for the list mode ('List available transitions') but leaves the apply mode's return unspecified. Given the simple 2-parameter structure and the clear explanation of the two modes, it is reasonably complete, though it could benefit from noting the result of applying a 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?

The input schema covers both parameters with descriptions ('Issue key' and 'Transition id or name. Omit to just list available transitions'), achieving 100% coverage. The tool description adds minimal extra meaning beyond the schema, simply restating the 'id or name' selection and the omission behavior.

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 available transitions for an issue, or apply a transition by id or name.' It uses specific verbs (list, apply) and identifies the resource (transitions for an issue), distinguishing it from sibling tools like jira_search 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?

The description implies when to use the tool: when you need to list or apply transitions for an issue. It doesn't explicitly state when not to use alternatives, but the exclusive focus on transitions makes the usage context clear without needing 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 discloses that 'Description is converted from plain text to ADF,' a useful behavioral detail. However, it does not mention update semantics (e.g., partial vs full update) or any side effects, leaving some 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 sentences, front-loaded with the main purpose and a key behavioral detail. No redundant wording, making it 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?

Given the tool has 6 parameters and no output schema, the description is minimal. It covers the primary action and one transformation but lacks information about return values, whether updates are partial, or any prerequisites. The schema provides parameter constraints, but overall context is incomplete.

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

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

Schema coverage is 67%, and the description adds meaning for the 'description' parameter by noting plain text to ADF conversion, which is non-obvious. Other parameters like labels and assigneeAccountId have schema descriptions, but the description doesn't elaborate on them. This partial compensation warrants a 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 'Update editable fields on a Jira issue' with a specific verb and resource. It distinguishes from sibling tools like jira_create_issue and jira_transition_issue by focusing on editing existing 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?

The description does not explicitly state when to use this tool vs alternatives. It implies usage for editing existing issues but lacks exclusions or alternative recommendations. No prerequisites or when-not-to-use guidance provided.

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