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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses a non-obvious behavior — Markdown is automatically converted to Confluence storage format (HTML) — and lists supported formatting, but it says nothing about required permissions (check_confluence_permissions exists as a sibling), notification side effects, or what the call returns.

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, front-loaded with the purpose before the requirements. It is efficient, though the Markdown formatting guidance is duplicated verbatim in the schema and could have been trimmed.

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 tool with no output schema this is adequate, but there is a gap: it promises an 'inline' comment while the schema offers only pageId and markdownContent with no anchor or selection parameter, which may mislead an agent about what can actually be placed. Permission requirements and return value also remain unaddressed.

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 both parameters are already fully documented in the schema, including the Markdown formatting examples and the HTML conversion note. The description restates that same information rather than adding new meaning, 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?

States a specific verb and resource ('Add an inline comment to an existing Confluence page') and the Confluence context implicitly separates it from the sibling jira_add_comment. It does not, however, clarify whether 'inline' means an anchored/highlighted comment versus a footer comment, nor does it name any sibling explicitly.

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 a hard precondition for the content parameter ('REQUIRED: Always provide Markdown content') and implies the page must already exist, but it never says when to use this tool versus create_confluence_page, jira_add_comment, or other siblings, and gives no exclusions or permission prerequisites.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses that the scope of checking expands conditionally (auth + read/search always, write only when a page ID is given). It does not disclose what happens on failure (exception vs. boolean) or any rate-limit/permission caveats, so it falls short of full transparency.

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

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

Two sentences, front-loaded with the core purpose before the conditional detail. Every clause 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 diagnostic tool with no output schema, the description should indicate what a call yields (a pass/fail verdict, error message, or per-check breakdown), and it does not. The behavior is described but the result contract is left unspecified.

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 the single parameter is fully documented in the schema itself, so the baseline is 3. The description only restates that write access is checked against a specific page, adding no format or syntax 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?

States a specific verb (check/validate) and resource (API token permissions), and enumerates exactly what is validated: authentication, read/search access, and write access. No sibling among search_confluence, jira_* etc. performs credential validation, so it is trivially distinguishable.

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 usage context (validating token validity before or during operations) and explains the read-vs-write branching, but never states when to call it versus other tools or what situation motivates it (e.g. diagnosing auth failures). Usage is inferable rather than explicit.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that Markdown is auto-converted to Confluence storage format (HTML), which is real behavioral context. However, it omits permission requirements (notable given the check_confluence_permissions sibling), duplicate-title behavior, and what the tool returns on success.

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

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

Four short sentences, front-loaded with the action and the hard requirement ('Always provide Markdown content'). The markdown feature enumeration is slightly list-heavy but earns its place by setting expectations for input format.

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 mutation tool with no annotations and no output schema, the description covers input format well but leaves gaps on permissions, failure modes, and the created page's identity in the response. Adequate but not complete for a write 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?

Schema description coverage is 100%, so all four parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the markdownContent requirement and lists supported syntax, but largely restates what the schema's own parameter description already says rather than adding new semantics.

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

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

States a specific verb and resource ('Create a new Confluence page in a given space'), which cleanly separates it from siblings like update_confluence_page and get_confluence_page. The nesting capability is also named up front, so an agent knows this is the creation path rather than a read or edit path.

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?

Usage is only implied: the description establishes creation context and mentions optional parent nesting, but never says when to prefer this over update_confluence_page or what to do if a page with the same title already exists. No prerequisites or alternatives are named.

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

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

With no annotations, the description must carry behavioral burden. It discloses the return format (storage format HTML) and lists returned fields, which is useful. However, it doesn't mention permission requirements, error behavior, or whether it's read-only (implied by 'Read' but not explicit). It adds some value but has gaps for a no-annotation 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 sentences, front-loaded with the core action and followed by return details. No wasted words, though it could be slightly more streamlined.

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 single-parameter read tool with no output schema, the description is adequate. It covers what the tool does and what it returns, but lacks usage context and permission details that would be helpful given 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 coverage is 100%, so the parameter is fully documented. The description adds no additional 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?

States a specific verb (Read) and resource (Confluence page by ID). It doesn't explicitly differentiate from siblings like get_confluence_page_versions or search_confluence, but the operation is clear.

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 on when to use this tool versus alternatives like search_confluence or get_confluence_page_versions. It simply states what it does without context about when it's appropriate.

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 usefully discloses the return shape – a list of versions with author, timestamp, and optional version message – and 'Get' implies read-only semantics. It says nothing about permission requirements or ordering of results, leaving meaningful 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 short sentences, front-loaded with the core purpose, then the return contents. No filler, no redundancy with 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?

For a simple two-parameter read tool with no output schema, the description covers purpose and return fields adequately. It could add a note on defaults or result ordering, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so both pageId and limit (including range and default) are fully documented in the schema. The description adds no parameter detail beyond that, which is the baseline 3 case.

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

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

States a specific verb+resource: 'Get the version history of a Confluence page.' It clearly distinguishes itself from the closest sibling, get_confluence_page, by scoping to version history rather than page content. It stops short of naming that sibling explicitly, so it is clear but not maximally differentiated.

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 when-to-use or when-not-to-use guidance and no mention of alternatives such as get_confluence_page. Usage is only implied by the name and description; an agent must infer that this is the tool for historical revisions.

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 usefully discloses that Markdown is auto-converted to ADF for Jira Cloud, but says nothing about permissions required, whether watchers are notified, or failure modes for an invalid issue key.

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?

Purpose is front-loaded in the first sentence and the format contract follows. The lengthy enumeration of Markdown constructs is somewhat redundant with the schema but stays on one coherent point.

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 two-parameter tool with no output schema, the description covers the key inputs and the notable conversion behavior. It omits error handling and notification side effects, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description restates the Markdown/ADF behavior and the key format, adding marginal value rather than new semantics; baseline 3 applies when 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?

States a specific verb and resource ('Add a new comment to a Jira issue'), names the lookup key ('by its key or numeric ID'), and lists target issue types. The word 'new' implicitly separates it from jira_update_comment, but no sibling is named, so it stops short of 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?

The description prescribes a format for the body but never says when to use this tool versus jira_update_comment or any alternative, nor does it state prerequisites or exclusions. Usage must be inferred from the name alone.

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 full burden. It does disclose two useful non-obvious behaviors (default unassigned assignee, markdown auto-converted to ADF), but omits permission requirements, error/failure behavior, and what happens when fields like priority or labels are invalid.

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 zero waste: purpose first, default-behavior second, hard requirement last. Every sentence earns its place and the constraint is 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?

For a mutation tool with seven parameters, no annotations, and no output schema, the description covers required inputs and default assignment but leaves gaps around permission requirements, failure modes, and confirmation of what is created. Adequate but not complete.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema (including markdown formatting rules and the assignee-cloning caveat). The description only restates the required-description requirement, adding no meaning beyond the structured fields; 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?

States a specific verb (Create) and resource (Jira issue) plus concrete issue types (Story, Bug, Task), scoped to a project. This is easily distinguishable from the write-sibling jira_update_issue by verb, but it never explicitly names an alternative, which is what a 5 would require.

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 one behavioral hint about when to omit assignee ('New issues are created unassigned by default' and the cloning caveat), which implies how to call it, but it never states when to use this tool versus jira_update_issue or jira_search. Usage is only 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?

No annotations are provided, so the description carries the full burden. 'Get full details' makes the read-only nature clear and the list of returned fields compensates somewhat for the absent output schema, but nothing is said about permissions, rate limits, or behavior for missing/invalid keys.

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 tight sentences, front-loaded with purpose and following immediately with the return payload. 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?

With no output schema, the description usefully enumerates the returned fields, which is the key missing piece for a simple single-resource fetch. Only the absence of error/permission behavior keeps it from being 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 description coverage is 100% and there is only one parameter, which the schema already documents with the same 'PROJ-123' / numeric ID example. The description adds no format or edge-case detail 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?

States a specific verb and resource ('Get full details of a single Jira issue'), names both accepted input formats, and enumerates the returned fields. It implicitly separates itself from jira_search by scoping to a single issue, though it never names that sibling explicitly.

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 'a single Jira issue' implies the contrast with jira_search, but there is no explicit when-to-use statement or named alternative. An agent can infer the split, but the description does not state it.

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. 'List' implies a safe read and the description frames it as a discovery step, which is useful, but it says nothing about permission requirements or the shape/cost of the returned data (e.g. whether transition IDs are included, pagination). 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 short sentences with zero waste; the purpose leads and the routing advice follows 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 single-parameter read tool with no output schema, the description covers purpose and downstream use adequately. The only gap is that the agent doesn't know what a 'transition' entry contains (name vs. id), which matters for wiring the result into jira_transition_issue.

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% for the single issueIdOrKey parameter, including format examples ('PROJ-123'), so the schema does the heavy lifting. The description adds no syntax or constraint beyond that, so the 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?

States a specific verb + resource + scope ('List all available workflow transitions for a Jira issue'), which is precisely distinguishable from the sibling jira_transition_issue that performs the transition rather than enumerating 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?

Explicitly names the alternative and the condition that selects it: 'Use this to discover valid transition names before calling jira_transition_issue.' This tells the agent both when to call it and which sibling to call afterward, leaving nothing to inference.

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 behavioral burden, and it does disclose the shape of the response (a list of issues with status, assignee, priority, description). However, it says nothing about permission requirements, result ceilings, sorting, or what happens when no issues match, which are meaningful gaps for an unannotated 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 sentences, zero filler: the action and its input mechanism come first, and the return contents are summarized second. Nothing could be cut without losing 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?

With no output schema, the description usefully compensates by summarizing the returned fields, and the JQL syntax itself is covered by the schema example. The main gap is the absence of usage/routing guidance, which is a description-level concern rather than a structural one.

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 jql, limit, and startAt are already fully documented with examples and defaults. The description adds no parameter-level detail 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?

The description states a specific verb (Search) and resource (Jira issues) plus the mechanism (JQL query string), and the promise of a 'list of matching issues' implicitly distinguishes it from the single-issue sibling jira_get_issue. It stops short of naming any sibling explicitly, so it does not reach the top score.

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 when-to-use or when-not-to-use guidance: nothing explains when to prefer jira_search over jira_get_issue, or how to page through results. Usage is only implied by the verb 'Search'.

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 behavioral burden. It implies a state-mutating write operation but never states permission requirements, whether the transition is reversible, workflow-dependent behavior, or what the response looks like. The mention that an invalid name returns an error listing available transitions is useful but appears only in the schema.

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 core action, no padding. Slightly wasteful in restating the parameter forms already covered by the schema, but the prerequisite tip is well placed.

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?

No output schema exists, but for a two-parameter workflow tool the description covers purpose, inputs, and the practical prerequisite of checking current status. Missing only workflow-specific caveats (permission needs, workflow-dependent valid transitions) to be fully self-contained.

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 both parameters are already fully documented with examples and the case-insensitivity/error fallback rule. The description's restatement that either a name or numeric ID is accepted adds no 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?

States a specific verb and resource ('Change the status of a Jira issue by performing a workflow transition') and clarifies the two accepted identifier forms. It references jira_get_issue, but does not distinguish itself from the most closely related sibling, jira_get_transitions, which is the tool most likely to be confused with it.

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

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

Gives clear context: read the current status with jira_get_issue before transitioning. There is no explicit when-not guidance (e.g. how to discover valid transitions vs. jira_get_transitions), so it falls short of full 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, the description carries the full burden. It usefully discloses that input is auto-converted to ADF for Jira Cloud and that comments cannot be deleted through this server. However, it omits auth/permission requirements and whether the new body fully replaces the old one.

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

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

Front-loads the core action, then gives identification, required input, and conversion note in a tight sequence. Every sentence carries information; capitalization draws attention to the required field 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?

For a three-parameter mutation tool with no output schema, the description covers identification, required input, format handling, and a deletion caveat. Only permission/auth expectations and the replace-vs-append semantics of the body are left implicit.

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 all three parameters are already documented. The description reinforces the required Markdown body and the source of the comment ID, but adds no syntax or format detail beyond what the schema provides; 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?

States a specific verb (update) and resource (the body of an existing comment on a Jira issue), and specifies the identifiers needed. It implicitly distinguishes itself from jira_add_comment by requiring a comment ID returned from that sibling, though it does not name the distinction explicitly.

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?

Clear context: update an existing comment rather than create one, and it points to jira_add_comment as the source of valid comment IDs. It does not spell out explicit exclusion cases (e.g., when to add a new comment instead), so it falls short of full when/when-not 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 supplied, so the description carries the full behavioral burden. It discloses partial-update semantics (only send changed fields) and that descriptions must use Markdown, which is genuine context. However, it omits permission requirements, what happens to omitted fields, reversibility, and error behavior on invalid field keys.

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

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

Three sentences, front-loaded with the core action, then the partial-update rule, then field specifics. The field enumeration largely duplicates the schema, which is minor padding, but there is no wasted preamble.

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 two-parameter mutation tool whose schema is fully documented and which has no output schema, the description covers the key gotchas: partial updates and the Markdown requirement for description. Missing permission/error context keeps it from 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 description coverage is 100%, so the schema already documents both parameters in detail. The description repeats the same field list (summary, description, assignee/accountId, priority, labels) and the Markdown rule rather than adding new semantics, so it earns only the baseline.

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

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

States a specific verb and resource: 'Update one or more fields on an existing Jira issue'. The scope phrase 'existing Jira issue' implicitly separates it from jira_create_issue and jira_transition_issue, but it never names an alternative explicitly, so it stops short of 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?

'Provide only the fields you want to change' is a useful partial-update guideline, but there is no explicit when-to-use vs when-not guidance and no routing to siblings like jira_transition_issue for status changes or jira_add_comment for comments. Usage is implied rather than 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?

With no annotations, the description carries the full behavioral burden and mostly does not: it does not state that this is a read-only operation, whether results are paginated, ordering, or any permission/rate-limit constraints. Only the schema's limit field hints at result capping.

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 with no filler. It is efficient, though arguably too short to carry the behavioral burden a no-annotation tool needs.

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 read tool this covers the core action, but with no annotations and no output schema the description should at least indicate the return shape (e.g. page ids/titles) or pagination behavior. It is minimally viable, not complete.

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

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

Schema description coverage is 100%: cql is documented with an example and limit with its range and default. The description adds only the CQL acronym expansion, which is marginal value over the schema.

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

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

States a specific verb (search) and resource (Confluence pages) plus the query mechanism (CQL). It is clearly distinguishable from siblings like get_confluence_page, though it does not explicitly contrast itself with 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?

No when-to-use guidance beyond the implied 'you have a CQL query'. It never says when to prefer this over get_confluence_page for a known page, or how it relates to jira_search for cross-product 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?

With no annotations, the description carries the full disclosure burden. It does add real behavior: Markdown is auto-converted to Confluence storage format and version bumping is handled automatically, which meaningfully lowers agent burden. It does not say whether the update replaces the entire page body or merges, nor what permissions are required, so the mutational risk profile is only partly disclosed.

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

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

Front-loaded with the action and resource, then the required-format constraint, then behavioral notes. The Markdown syntax enumeration is somewhat redundant against the schema but stays contained in one sentence.

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?

No output schema exists, but for a mutation tool with zero annotation coverage the description stops short of what an agent needs: whether content is fully replaced, whether conflicts or version mismatches error out, and whether prior permissions checks are required. Not misleading, just 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 100%, so all three parameters (pageId, title, markdownContent) are already documented in the schema, and the description largely restates the Markdown requirement and syntax list verbatim. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb and resource ('Update an existing Confluence page'), and the word 'existing' implicitly separates it from create_confluence_page. However, it never names a sibling explicitly, so an agent must infer the routing itself.

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 create_confluence_page or when to fetch a page first, and no mention of the check_confluence_permissions sibling despite this being a write operation. The 'REQUIRED: Always provide Markdown content' line is a formatting constraint, not usage guidance.

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