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 that this is a raw pass-through, implying direct API behavior without added safety checks, but it does not mention authentication requirements, error behavior, rate limits, or that arbitrary endpoints may be destructive. The description is honest about its nature but lacks depth.

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

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

Two short sentences with zero waste. The core purpose is front-loaded, and the usage guidance is concise. Every word earns its place.

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

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

For a raw pass-through tool with a rich schema and output schema, the description is mostly complete. However, it lacks guidance on how to construct paths, what authentication context applies, and any warnings about destructive operations. The output schema exists, so return values need no explanation, but the missing safety/usage context leaves a gap.

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 four parameters. The description adds no additional parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate because 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 states a specific verb ('Raw pass-through') and resource ('any Jira or Confluence REST endpoint'), which clearly distinguishes it from the sibling tools that wrap specific endpoints. It could be slightly more explicit about what 'raw pass-through' means operationally, but it is clear enough to differentiate from the specialized 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 says 'Use when no other tool fits,' which gives a clear when-to-use signal and implies that specialized siblings should be preferred. It does not explicitly name alternatives or exclusions, but the sibling list and the 'no other tool fits' phrasing provide adequate guidance.

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

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

With no annotations, the description must disclose behavioral traits. It states 'Add' (a mutation) and 'markdown' (format), but nothing about side effects, idempotency, permissions, error behavior, or whether it appends to existing comments. The description adds minimal value beyond the tool's 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 a single, concise sentence with no redundant information. It front-loads the core action and resource. However, it may be too sparse given the lack of annotations, but for sheer conciseness it earns a 4.

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 two string parameters and an output schema (not shown), the description is minimally sufficient. It states the operation and target. However, it omits prerequisites, error conditions, and any specifics about the returned data. The output schema could cover return values, but it's not provided, so the description alone feels 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 description coverage is 0%, so the description must compensate. It hints that 'body' is the comment content in markdown and 'page_id' is the target page, but it doesn't explicitly define either parameter. No constraints, formats, or examples are given, leaving agents to infer meaning from parameter names alone.

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 target (a footer comment to a page). It is specific enough to distinguish from creating or updating pages, though it doesn't explicitly name alternatives. The term 'footer comment' adds specificity, but the description doesn't mention how this differs from other comment tools like 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 guidance is provided on when to use this tool versus alternatives. It doesn't mention when not to use it, prerequisites (e.g., page existence), or compare with sibling tools like confluence_update_page or jira_add_comment. The context is implied but not 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 zero annotations, the full burden falls on the description. It discloses the input format (markdown) and the post-creation side effect ('return it re-read'), but omits permission conditions, failure handling for duplicate titles, or any reversibility considerations.

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?

A single, front-loaded sentence that places the action first, then the input format, then the distinctive behavior. Every word contributes; no fluff or redundant restatement of the schema.

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 schema fully documents the four parameters and an output schema exists, so the description focuses on non-schema information: markdown conversion and a verify-by-reread step. For this straightforward create operation, this is enough to call, though it leaves permission and failure handling unstated.

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 phrase 'from markdown' merely mirrors the existing `body` schema description, and no additional meaning is added for space_key, title, or parent_id.

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 the precise verb 'create a markdown page from markdown' and appends a distinctive behavior, 'return it re-read,' which differentiates it from siblings like `confluence_update_page` or `confluence_get_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?

No wording about when to choose create over update, when a page already exists, or what prerequisites to establish (such as an existing space_key). The description says only the tool's name and parameter list imply the usage.

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 burden. It adds the useful detail that the body is returned as markdown, but it does not disclose behavior around missing lookup parameters, duplicate titles, or how include_comments affects the result.

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

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

Two short sentences with no filler. The primary retrieval modes are front-loaded, and the markdown output fact adds value 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?

An output schema exists, so return shape does not need explanation, but the input contract is under-specified: all four parameters are optional in the schema while the tool likely requires at least one lookup key, and include_comments is left unexplained. This creates a meaningful gap for correct invocation.

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

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

Schema description coverage is 0%, so the description must supply parameter meaning. It explains the relationship among page_id, space_key, and title, but says nothing about include_comments and leaves the exact combination rules for lookup keys implicit.

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 names a specific verb ('Get'), resource ('Confluence page'), and both available lookup modes ('by id, or by space key + exact title'). 'Body is returned as markdown' further clarifies what the tool produces and helps distinguish it from search-oriented 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?

It clearly states when to use the tool: when the agent has a page_id or a space_key plus exact title. It stops short of explicitly naming alternatives or exclusions, but the exact-match wording makes the intended use 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?

No annotations are provided, so the description must stand alone. 'List' conveys it is read-only, and 'direct child pages' clarifies it does not return descendants recursively)Skip; still, it does not disclose pagination behavior, error conditions, or required page access.

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 a specific verb and object. No unnecessary words or clutter.

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, the description plus schema is mostly sufficient. However, absent pagination behavior and any explicit relationship to sibling tools makes it slightly incomplete for an agent deciding between tools.

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

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

With 0% schema description coverage)Skip the description should compensate by explaining the parameters. It does not mention page_id or limit semantics; page_id is inferable, but limit's behavior is left entirely undocumented.

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 operation ('List') and the target resource ('direct child pages of a page'), making the tool's purpose unambiguous. It does not explicitly contrast with sibling tools like search or page retrieval, but the phrase 'direct child pages' adequately distinguishes it from fetching a page or its content.

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

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

The description implies this tool is for retrieving immediate children of a page, which gives clear usage context. However, it does not mention when not to use it or point to alternatives such as search or get_page for broader queries.

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. 'Search' implies a read-only operation, but the description does not confirm this, nor does it mention any limits, pagination behavior, or error conditions. It adds no context beyond the verb.

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, which is concise and front-loaded. However, it is under-specified and offers no additional structure or nuance, making it minimally useful beyond the tool name.

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 output schema exists and parameters are fully documented, so the description only needs to state the purpose. It does that, but it fails to mention any usage context or limitations, and with many sibling tools, a bit more context would help an agent choose 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%, with both cql and limit well-documented including examples and defaults. The description adds nothing about parameters, so the baseline of 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 states the verb 'Search' and the resource 'Confluence' with the method 'CQL', clearly indicating a search operation. It is specific enough to distinguish from sibling tools like get_page or get_page_children, though it does not explicitly contrast them.

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 no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, typical scenarios, or when to prefer it over get_page or jira_search_issues. The user must infer usage from the name and schema.

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. It discloses that the body replaces the whole page (overwrite risk), that versioning is handled automatically, and that the updated page is re-read and returned. It does not cover permissions or error conditions, but the key mutation behavior is clearly stated.

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 the core action and versioning in the first sentence, and a crucial warning about overwriting in the second. No fluff, every sentence 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 no annotations, the description covers the essential behavior: overwrite risk, versioning, and return value. It lacks explicit permission requirements and error handling, but for a mutation tool this is reasonably complete. The main gap is the unexplained message parameter.

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

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

Schema description coverage is 0%, so the description must compensate. It explains body (markdown) and title, but the message parameter (likely a version comment) is not mentioned. page_id is obvious from the tool name. Partial coverage, but not fully compensates for the schema gap.

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 (update) and the resource (a page's body and/or title), and it distinguishes from siblings like create and get by mentioning versioning and the overwrite behavior. It is specific 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?

It explicitly instructs to read the page first with confluence_get_page if the user wants to edit rather than overwrite, providing clear conditional guidance. This effectively tells when to use this tool vs. reading first, and implies when overwriting 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 present, so the description must carry the behavioral disclosure burden. It states the mutation ('Add') and the markdown format, but does not mention permissions, reversibility, side effects, or whether the comment is appended to existing comments.

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 no filler, and the core fact—adding a markdown comment—is front-loaded. 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?

The tool is simple and the parameter names are largely self-explanatory, and an output schema exists. Still, with no annotations and no usage guidance, the description leaves the agent to infer operational context such as the key format and the mutating nature of the action.

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

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

Schema description coverage is 0%, so the description is the only source of parameter meaning. It clarifies that 'body' is markdown and 'key' refers to an issue, but it does not explicitly describe either parameter or give examples.

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 resource ('comment to an issue'), and adds 'markdown' as a distinguishing detail. This clearly separates it from sibling tools like jira_update_issue and confluence_add_page_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?

The phrasing implies the tool is for adding comments to Jira issues, which is a distinct operation from siblings like jira_update_issue or jira_transition_issue. However, it provides no explicit guidance on when to use it versus alternatives or any 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 disclosure burden. It usefully reveals that the returned issue is re-read from Jira for verification, but it omits permission requirements, duplicate-creation behavior, and failure modes.

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?

A single front-loaded sentence says what the tool does and why the re-read behavior matters, with no redundancy or repetition of the title.

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 schema thoroughly documents all five parameters, an output schema exists, and the prose adds the re-read verification guarantee. A bit more context about permissions or explicit when-not-to-use conditions would make it fully 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% and every parameter already has meaningful descriptions, including examples for the fields parameter. The description adds no parameter-level semantics, so the high-coverage baseline of 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 states a specific verb and resource ('Create an issue') and adds a distinctive post-condition ('return it re-read from Jira so you can verify it'). This clearly differentiates it from update, transition, and search 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 gives clear context: use this when a new issue needs to be created. It does not explicitly name alternatives or say to use jira_update_issue for existing issues, so it stops short of full 5-level routing guidance.

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

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

With no annotations present, the description carries the behavioral burden. It discloses the return shape and its exact JSON form, which is useful, but it does not explicitly state read-only semantics, side effects, or auth requirements. 'Find' implies a read operation, so this is an adequate but not richly transparent description.

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 carry the exact information the agent needs: lookup by name/email, and the exact output format with a concrete example. Every phrase earns its place; nothing is redundant.

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 2-parameter search tool with an output schema, the description is nearly complete. It explains why accountIds matter by showing their use in assignee/reporter fields, covering the practical context. The only gap is that 'limit' is not explained or given guidance, but the schema's default makes this minor.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that 'query' accepts a name or email, which adds needed meaning to the one required parameter. However, 'limit' is not described at all, so parameter-level guidance is only partial.

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

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

The description opens with a clear verb and resource: 'Find users by name or email.' It then states the concrete purpose of the returned IDs, distinguishing this user-lookup tool from the issue/content tools in its sibling group. No ambiguity about what the tool produces or why it is useful.

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 says the returned accountIds are what assignee/reporter fields need, giving an agent clear guidance on when to use this tool. It does not explicitly name alternatives or exclusions, but the context is specific enough to route an agent correctly.

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

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

The markdown note ('Description and comments are returned as markdown') adds a real behavioral detail. With no annotations, the description is responsible for conveying safety/read-only nature and side effects. 'Get' implies a read but this is not explicit, and no behavior like field defaults or comment inclusion is mentioned. A 3 is fair: some useful detail, but limited.

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

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

Two short sentences with the primary action first and a useful formatting detail second. No filler. Slight ambiguity in 'comments' (only returned when include_comments=true), but structurally it's tight and front-loaded.

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

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

The output schema covers return valueshebthetish and the parameter schema covers arguments. The description does not explain when to choose this over jira_search_issues, nor does it mention that comments are optional and off by default. Still, with schema support, an agent has enough to invoke it correctly for a known issue key.

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?

Parameter schema covers all three parameters at 100%, so the description doesn't need to add much. It does clarify the content/format of the issue description and comments. No enrichment of parameter meaning beyond the schema, so the 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?

Description uses a specific verb ('Get') and a clear object ('an issue'), which distinguishes it from sibling search/create/update tools. It doesn't explicitly say 'by key' but the required 'key' parameter in the schema makes the intent clear. It doesn't explicitly differentiate from jira_search_issues, so not a 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?

No guidance is given about when to use this tool versus jira_search_issues, jira_update_issue, or other siblings. An agent must infer from the schema that a key is required. There is no stated precondition or selection criterion.

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 that the transitions are 'currently available', implying they depend on the issue's current state, which is a meaningful behavioral trait. However, it does not mention any other behaviors like error handling, authentication requirements, or side effects. For a read-only operation, the lack of destructive side effects is implied but not explicitly stated, which is acceptable but not comprehensive.

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 gets straight to the point. It is appropriately sized for a simple read operation, with no filler or redundant information. The core action and resource are front-loaded, making it easy for an agent to parse quickly.

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, and an output schema exists to define return values, so the description need not explain them. However, the description omits critical context about the 'key' parameter, which is undocumented in the schema. Additionally, it does not clarify what constitutes a 'transition' (e.g., status changes) or any prerequisites. While the core purpose is clear, the missing parameter semantics makes the tool incomplete for an agent to call it correctly.

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

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

Schema coverage is 0%, and the description adds no explanation for the single parameter 'key'. It only says 'for an issue', which indirectly suggests 'key' is the issue key, but this is not explicit. The agent must guess that 'key' refers to the issue identifier (e.g., 'PROJ-123'). The description fails to clarify the parameter format or expected values, which is a critical gap given the complete lack of schema documentation.

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

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

The description states a specific verb ('List') and resource ('workflow transitions') with scope ('for an issue'). It clearly distinguishes from siblings like jira_transition_issue (which performs a transition) and jira_get_issue (which retrieves issue details). An agent can accurately identify this tool's purpose without ambiguity.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention that it should be used before jira_transition_issue to discover valid transitions, nor does it contrast with jira_update_issue or jira_get_issue. Usage context is only implied by the verb 'List', leaving the agent to infer the appropriate scenario.

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 behavioral burden. It discloses the core behavior—listing components and returning ids—and adds a useful invariant about exact name matching. However, it does not mention response shape, pagination, permissions, or whether the project parameter accepts a key, ID, or name. This is acceptable for a simple read tool but not fully 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?

One sentence front-loads the core action and outcome, and the parenthetical adds a valuable constraint without padding. 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?

Given the simple one-parameter shape and the presence of an output schema, the description covers the essential context: what the tool returns and why exact names matter. The only notable omission is the accepted format of the project argument, but the overall definition is sufficient for an agent to invoke this tool effectively.

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 only defines 'project' as a string with no description, so 0% coverage. The tool description adds that the parameter refers to 'a project' and that the result exposes components and ids. While it doesn't specify whether a project key or numeric ID is expected, the parameter's meaning is largely conveyed by the description and the tool name.

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

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

The description uses a specific verb and resource: it lists a project's components and includes their ids. The phrase 'a project's components' clearly distinguishes this from sibling tools that operate on issues or Confluence pages, so an agent can disambiguate without needing the schema.

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 parenthetical 'names must match exactly when writing' strongly implies this is the tool to use before creating/updating issue data that references components, but it does not explicitly say 'use this before jira_create_issue or jira_update_issue'. The usage context is clear enough but the intended when-to-use versus alternatives is only implied, 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 full burden of behavioral disclosure. It only restates the core search action and adds no context about read-only behavior, JQL error handling, rate limits, pagination behavior, or result characteristics beyond what the schema already conveys.

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 filler words. It is efficient and readable, though slightly under-specified; that gap is better attributed to contextual completeness rather than to conciseness.

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 output schema and 100% parameter documentation make the tool callable from structured data alone. However, the description lacks usage routing to sibling tools and provides no behavioral context beyond the bare operation, making this minimally viable rather than complete.

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

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

Schema description coverage is 100%, and the schema already documents each parameter well, including a JQL example, pagination token usage, field filtering, and limit bounds. The description itself adds no parameter-level meaning, 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 states a specific verb ('Search'), a resource ('issues'), and a method ('JQL'). This distinguishes it from sibling tools like jira_get_issue, which retrieves a single issue, and create/update/transition operations, though it does not explicitly name those alternatives.

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?

There is no guidance on when to use this tool versus jira_get_issue, jira_list_components, or the Confluence search tools. No exclusions, conditions, or alternative routing are provided, so the agent must infer usage from the tool name rather than from explicit guidance.

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

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

No annotations are provided, so the description must carry the behavioral burden. It discloses a mutation (moving issue through workflow) and a meaningful constraint (comments not accepted), but does not mention likely side effects, such as whether a transition can require extra fields, is irreversible, or changes the issue in ways beyond status. For a state-changing action with zero annotations, this is thin.

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 action and immediately point to the sibling tool for valid transition values; the comment limitation is stated in one clause 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 description tells an agent where to obtain transition IDs and how to handle comments, which covers the main usage pitfalls. It doesn't mention possible required transition fields or permissions, but the tool is simple and has 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 description doesn't define 'key' or 'transition_id' but links transition_id to jira_get_transitions opportunely. Schema coverage is 0% and the description adds little beyond the names, though the sibling reference compensates somewhat for the transition_id parameter.

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

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

Description states a specific verb and resource: 'Move an issue through a workflow transition'. It also references the sibling tool jira_get_transitions, differentiating this operation from related issue actions like jira_update_issue. An agent can tell exactly what this tool does and why it exists.

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 to consult jira_get_transitions for valid transitions and jira_add_comment for comments, stating that comments are deliberately not accepted here. This clearly tells an agent when to use this tool versus its sibling 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, the description carries the full burden for behavioral disclosure. It does state that the issue is re-read after update, which is useful, but it fails to mention mutation risks, permissions, reversibility, or the irreversible-resolution caveat that the schema hints at.

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 filler. Every word earns its place, and the key outcome—update plus re-read—is stated immediately.

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 three-parameter mutation tool with an output schema, the definition is minimally viable but leaves gaps. It does not explain when to use this tool versus jira_transition_issue, and it omits behavioral safety context that would be important with no annotations.

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 per the baseline the description need not elaborate on parameters. The tool description adds no parameter meaning, but the schema already documents 'key', 'fields', and 'description', including important constraints like the resolution warning.

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 a specific action ('Update an issue') and a valuable behavioral detail ('return it re-read from Jira'). It is not a tautology and reasonably distinguishes from jira_create_issue, but it does not explicitly differentiate from jira_transition_issue, which also modifies an 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 tool description provides no when-to-use guidance or alternatives. The important exclusion that status changes must go through jira_transition_issue appears only in the schema's parameter description, not in the tool description, so the description itself offers no usage direction.

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