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

No annotations are provided, so the description must carry the full burden. It correctly discloses key behavioral traits: non-streaming, single-turn, optional model/system prompt overrides, mutual exclusivity of message parameters, and error handling for missing credentials. However, it does not explicitly state whether the tool is read-only or has any side effects, and the return value format is not described.

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, front-loaded with the main purpose, and each sentence adds unique value (features, comparison, parameter guidance). No redundant or filler content.

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

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

Given the absence of an output schema, the description could better explain the return value format or structure. It mentions 'return its response' and error handling, but agents might need more detail. However, for a chat tool, the response is typically straightforward, so the gap is 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 coverage is 100%, so the baseline is 3. The description adds value by reinforcing mutual exclusivity of message and message_path, explaining the CLI comparison for system_prompt, and advising preference for the path form. This goes beyond the schema's description, providing practical usage context.

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

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

The description clearly states the verb 'Send' and the resource 'message to the configured AI', listing supported backends. It distinguishes the tool from siblings by specifying it's a single-message, non-streaming tool, which is unique among the listed siblings that are mostly Atlassian, Datadog, Git, Jira, Snowflake, and transcript tools.

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

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

Provides explicit guidance on when to use (single-turn, non-streaming), mentions optional overrides, compares to the CLI command (noting differences like the system prompt flag), and advises preferring message_path when the message is already on disk. Also describes error behavior on missing credentials, helping the agent decide when this tool is 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 full burden and delivers comprehensively. It discloses that it returns boolean presence flags only, never secrets, returns the instance URL verbatim, is read-only, and outputs YAML. Every behavioral trait is transparently stated, leaving no ambiguity about side effects or data handling.

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

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

The description is front-loaded with the primary purpose and every sentence adds distinct value: secret safety, URL handling, local-only behavior, CLI contrast, no arguments, read-only, output format. It is concise yet information-dense, with no redundant phrases.

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

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

Given the tool's simplicity (no parameters, no output schema, no annotations), the description is remarkably complete. It covers functionality, limitations, return content, safety, and output format. It also provides contrast with a relevant alternative, fully equipping the agent to use and interpret the tool 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?

The input schema is an empty object, indicating zero parameters. The description explicitly states 'Takes no arguments,' which aligns with the schema. With no parameters to document, the description adds no semantic details, but the baseline of 4 is appropriate for a zero-parameter tool.

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

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

The description clearly states the tool's function: 'Report which Atlassian credential scopes have credentials configured.' The verb 'report' and specific resource 'Atlassian credential scopes' make the purpose unambiguous. It also distinguishes itself from the CLI alternative by clarifying what it does not do (validate credentials).

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

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

The description explicitly contrasts this tool with `omni-dev atlassian auth status`, stating it checks local configuration only and does NOT call the API to validate credentials. This provides clear when-to-use and when-not-to-use guidance, with an explicit alternative named for validation.

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 discloses that the tool is bidirectional, fully offline, performs no network I/O, and needs no credentials. It also warns about the 'strip_local_ids' parameter's potential impact on Confluence comments, adding important behavioral context.

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 remarkably concise with no filler. Three sentences cover purpose, behavior, examples, and a critical warning. Front-loaded with the core purpose.

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 high schema coverage, no output schema, and no annotations, the description is adequately complete. It explains purpose, behavior, parameter usage, and even provides example output format for one direction. Lack of explicit output schema description is acceptable.

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

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

Schema coverage is 100%, baseline 3. The description adds value by giving conversion examples for 'direction' and explaining 'compact' and 'strip_local_ids' with usage warnings, beyond the schema's descriptions.

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

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

The description states 'Convert between JFM and ADF JSON' with a specific verb and resource. It distinguishes from sibling tools by emphasizing offline, credential-free conversion, which no other tool offers.

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 advises using the tool to 'preview or inspect the ADF a JIRA/Confluence write tool would send' and highlights offline operation, giving clear context. It does not explicitly state when not to use or name alternatives, but the context is sufficient.

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 provided, so the description carries full burden. It clearly states the tool is NOT read-only and that requests run with the tab's session, potentially mutating remote state. It also mentions that streaming responses are not supported. This provides essential behavioral context beyond the basic purpose. However, it does not disclose rate limits or detailed auth requirements beyond the token, but the mutation warning is prominent.

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

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

The description is concise, with two well-structured paragraphs. The first sentence front-loads the action and output. Subsequent sentences cover prerequisites, behavioral warnings, URL behavior, and limitations. Every sentence adds value with no redundancy. It is appropriately sized for the tool's complexity.

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

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

The description covers the key aspects: what the tool does, prerequisites, behavioral warnings, URL constraints, credential modes, and limitation (no streaming). Given the lack of output schema and annotations, it provides sufficient context. It could mention error handling or return format details more explicitly, but the mention of 'response envelope (status, headers, body) as YAML' is adequate. Score 4 for good completeness relative to complexity.

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%, meaning every parameter is described in the JSON Schema. The tool description adds some context (e.g., referencing the CLI, explaining relative URL, credential modes) but does not significantly expand on what is already in the schema. Baseline 3 is appropriate; the description does not greatly improve parameter understanding 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?

Description clearly states the action: sending an HTTP request through a browser-bridge tab and returning the response. It specifies the resource (running browser-bridge tab) and the output format (YAML envelope). Distinguishes itself from sibling tools which are unrelated (e.g., Jira, Confluence tools) by referencing the specific browser bridge context and CLI command.

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?

Description explains prerequisites: requires a running bridge and a session token from environment variable or file. It explicitly warns that the tool is not read-only and can mutate remote state with non-GET methods. It clarifies URL behavior (relative to origin unless allow_origin set). However, it does not explicitly state when NOT to use this tool or mention alternative tools, but the context is clear enough.

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

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly warns 'MUTATES THE FILESYSTEM', states that real files are never deleted ('Real files (non-symlinks) are preserved, never deleted'), and clarifies scope ('Operates relative to the server process's cwd'). This is exemplary transparency for a destructive tool.

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

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

The description is four sentences, each serving a distinct purpose: state the action, warn about mutation, assure safety, and reference related tools. It is front-loaded with the verb 'Remove' and contains zero fluff.

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

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

Given the tool's complexity (2 optional params, no output schema), the description is complete: it explains what is removed, side effects, safety behavior, cwd scope, and how to preview. No essential information is missing for an agent to select and invoke it safely.

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 parameters (`format` and `worktrees`) already explained in the input schema. The tool description adds no additional parameter semantics, so the baseline 3 applies per the rubric.

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

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

The description clearly states the tool's function: 'Remove the skill symlinks under `.claude/skills/` and the managed exclude block created by a prior `claude_skills_sync`'. It uses a specific verb ('Remove'), identifies the exact resources, and explicitly notes it is the inverse of `claude_skills_sync`, distinguishing it from 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?

Provides explicit usage guidance: 'Use `claude_skills_status` first if you want to see what would be removed.' It also frames the tool as the inverse of `claude_skills_sync`, clarifying when it should be used (to undo a sync) and when to use an alternative (status for preview).

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 well: it declares 'READ-ONLY — changes nothing', explains the cwd-relative behavior, and mentions mirroring the `omni-dev` CLI. It doesn't detail output structure or edge cases, but for a read-only status tool this is strong 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?

Three succinct sentences: the first front-loads the primary outputs, the second adds safety/use-case, and the third covers operating scope and CLI parity. No redundancy or filler.

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

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

For a read-only status tool, the description covers purpose, usage context, safety profile, and operating scope. The schema fully documents parameters. While no output schema exists, the description's statement of what is reported (symlinks, exclude-block entries) conveys the return content adequately.

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 (`format`, `worktrees`) are fully described in the input schema. The description adds no additional parameter-level meaning or hints, 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 uses a specific verb and resource: 'Report the skill symlinks under `.claude/skills/` and the managed exclude-block entries'. It explicitly distinguishes itself from sibling tools by referencing `claude_skills_sync` and `claude_skills_clean`, making its unique purpose 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?

It explicitly provides usage guidance: 'the safe way to preview before calling `claude_skills_sync` or `claude_skills_clean`', naming the relevant alternatives and stating when to use this tool. It also adds the cwd-relative operating scope, giving concrete context.

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

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

With no annotations, the description fully carries the transparency burden. It explicitly states 'MUTATES THE FILESYSTEM', details the creation of symlinks and updates to `.git/info/exclude`, and notes the operation is relative to the server cwd and not cross-project. This is comprehensive for a mutation tool.

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

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

The description is extremely concise: two sentences plus a short reference to a mirror command. Every sentence adds unique value—main action, behavioral details with all-caps warning, and alternatives with tool names. No wasted words.

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

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

Given the tool has 2 optional parameters, schema coverage 100%, no output schema, and the description details side effects, scope, and reversible alternatives, the description is complete. The output format is already described in the schema. There is no missing critical information.

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 baseline is 3. The description does not add significant parameter-specific meaning beyond the schema; it mentions 'target worktrees' related to the `worktrees` parameter but does not elaborate on `format`. The schema already adequately describes both parameters.

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

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

The description clearly states the verb 'Sync' and the specific resource: 'Claude Code skills from the current repository into target worktrees.' It distinguishes from siblings by explicitly mentioning `claude_skills_clean` and `claude_skills_status` and noting that `claude_skills_status` inspects without changing anything.

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

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

The description provides clear context on when to use this tool: to sync skills from the current repo into worktrees. It explicitly names `claude_skills_clean` as the reverse operation and `claude_skills_status` for inspection. It does not include an explicit 'when not to use' section, but the alternatives are well-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 were provided, but the description fully discloses behavior: 'Takes no arguments. Read-only. Output is YAML.' It also clarifies that this tool returns only the embedded catalog, while the plain `show` merges overrides, providing important edge-case context.

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 compact and front-loaded, delivering all key information in three sentences. It covers purpose, usage, output format, read-only nature, and the differentiation from the override-merging variant without unnecessary detail.

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

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

For a simple read-only tool with no parameters and no output schema, the description is complete: it specifies what is returned, the format (YAML), the exact data fields, and how it relates to other tools. It also preempts confusion about overrides by mentioning the embedded-only distinction.

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

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

The tool has 0 parameters and the input schema (empty object) already confirms this. The description redundantly states 'Takes no arguments,' which is harmless. Per the zero-parameter rule, a baseline of 4 is appropriate.

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

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

The description uses a specific verb ('Return') and identifies the exact resource ('embedded `models.yaml`') and its contents. It clearly distinguishes this tool from siblings by noting it discovers valid `model` values for `ai_chat` and git tools, and further differentiates it from the plain `show` command.

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 states 'Use this to discover the valid `model` values accepted by `ai_chat` and the git tools,' giving a clear purpose. It also contrasts with the non-embedded variant, which merges user/project overrides, providing when-to-use/not-use 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 transparency burden. It discloses key destructive behaviors: default is moving to trash, and setting purge to true permanently removes (requiring admin rights). This exceeds the minimal expectation and contextualizes the delete operation's consequences.

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

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

The description is two sentences, front-loaded with the primary action, and includes the critical purge nuance. Every sentence contributes value; the CLI mirror reference is a compact way to signal parity with an existing command. No wasted words.

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

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

Given the 100% schema coverage, the tool's purpose, and the crucial purge behavior, the description is sufficient for correct invocation. It lacks an explicit note about return values, but no output schema exists, and for a delete operation this is not an obvious gap. It could arguably mention irreversibility beyond trash, but that is already inferred from 'purge'.

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 (attachment_id, purge) are already documented. The description adds no extra meaning beyond echoing the purge parameter's behavior; it restates what the schema already says. Thus, a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Delete a Confluence attachment') and specifies the identifier ('by ID'). This resolves ambiguity with sibling tools like confluence_attachment_download or confluence_attachment_update, and the verb 'Delete' is unambiguous.

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

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

The description provides guidance on the purge behavior (e.g., 'permanently purge instead of moving to trash' and 'requires space admin'), which helps decide when to set purge. However, it does not explicitly mention alternatives or when-not-to-use, so the guidance is present but not comprehensive.

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 exist, so the description carries the burden. It discloses disk write behavior, temp directory fallback, and return metadata. However, it omits overwrite behavior for existing files, error handling, and permission requirements.

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

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

Three sentences, front-loaded with the main action, no superfluous words. Every sentence adds essential 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?

No output schema, but description explains return metadata (id, title, media_type, bytes, path). Covers temp directory behavior well. Minor gaps: no mention of error conditions or file overwrite policy.

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%, baseline is 3. The description adds value for output_path by explaining temp directory behavior, but attachment_id is simply restated from schema. Overall marginal addition.

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

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

The description clearly states 'Download a Confluence attachment by ID to disk' with a specific verb and resource. It distinguishes from sibling tools like confluence_attachment_list and confluence_attachment_delete by focusing on the download action.

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 context on when to omit output_path (file goes to temp dir) and suggests reading the file via the filesystem tool. It references a CLI mirror for familiarity, but lacks explicit when-not-to-use or alternatives.

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

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

No annotations are provided, so the description must carry full transparency burden. It explains pagination behavior but does not explicitly state that this tool is read-only or has no side effects. The default limit and cursor usage are disclosed, but additional behavioral traits (e.g., authentication needs, rate limits) are absent.

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, each with a distinct purpose: purpose, pagination usage, default and mirror. No wasted words, front-loaded with core functionality.

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

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

The description covers pagination and defaults but lacks details on return format (e.g., what fields are in each attachment). Given no output schema, mentioning that it returns attachment metadata would improve completeness. For a simple list tool, it is adequate but has 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 baseline is 3. The description reinforces parameter usage (limit defaults to 25, cursor pagination) but does not add new meaning beyond the schema. The mirroring note is not param-related.

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 it lists attachments on a Confluence page, with the specificity 'one page per call'. The verb 'List' and resource 'attachments on a Confluence page' are precise. Among siblings, there is no other attachment listing tool, so it is well-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?

The description explicitly explains how to use pagination ('Pass the returned next_cursor back as cursor') and notes the default limit. However, it does not specify when to use this tool versus alternatives (e.g., for non-attachment content, use other reading tools). The guidance for pagination is clear.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it bumps the version rather than creating a duplicate, file_path is streamed from disk (never fully buffered), and it returns YAML describing the updated attachment. It references optional parameters 'as with upload' to inherit behavior. It does not cover permissions or error cases, but the available information is meaningful and non-obvious.

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

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

The description is two sentences, front-loaded with the primary purpose. It covers the key differentiator (update vs create), input requirements, file handling, optional params, return format, and a reference to the CLI mirror. No wasteful words.

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

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

Given the tool has 6 parameters, no output schema, and no annotations, the description is reasonably complete. It explains the main behavior, how to identify the attachment, the file path semantics, return type, and optional params. It omits error handling, authentication prerequisites, and whether previous versions are preserved, but those are secondary for successful invocation. The sibling tool references fill additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful context beyond the schema: it explains that page_id and attachment_id come from confluence_attachment_list, that file_path is a server-side path, and that optional params behave 'as with upload'. However, it does not add deep semantic detail for each parameter beyond what the schema already provides.

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

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

The description clearly states the tool updates an existing Confluence attachment by uploading a new binary version, with the specific behavior of 'bumping its version instead of creating a second attachment.' It distinguishes itself from the sibling confluence_attachment_upload by explicitly focusing on EXISTING attachments and referencing the source of IDs.

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 usage context: use this tool when you need to update an existing attachment identified by page_id and attachment_id from confluence_attachment_list, contrasting it with 'creating a second attachment' (implying the alternative of upload). It does not provide an explicit 'when not to use' but the contrast with upload is sufficiently clear. The 'as with upload' reference also guides on optional parameters.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly notes that file_path is on the MCP server's filesystem and streamed from disk (never fully buffered), which is critical technical context. It also explains the effect of comment, filename, and minor_edit parameters and states the return format (YAML). This is rich, transparent behavior disclosure.

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

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

The description is three sentences, front-loads the primary purpose, and every sentence adds value. It efficiently covers the main action, file handling behavior, optional parameters, and return format with no fluff or redundancy.

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

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

Given the tool's complexity (5 parameters, no output schema, no annotations), the description is remarkably complete. It explains all optional parameters, the return format, and the streaming behavior. The only minor gap is no mention of error conditions (e.g., missing file), but this is not essential for a task-completion-focused agent, and the schema covers required parameters. The description fully equips an agent to use the tool 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 100%, so the baseline is 3, but the description adds significant meaning beyond the schema. It clarifies that file_path is server-side and streamed, explains filename overrides the stored name, comment becomes a version note, and minor_edit defaults to false. This adds value beyond the schema's descriptions.

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

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

The description opens with a specific verb and resource: 'Upload a local file as an attachment to a Confluence page.' This clearly distinguishes it from sibling tools like confluence_attachment_download, confluence_attachment_delete, and confluence_attachment_list. The scope is precise and immediately understandable.

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

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

The description clearly implies use for uploading files as page attachments, and the verb 'Upload' differentiates it from alternative operations. However, it lacks explicit guidance on when not to use this tool or mention of alternatives like confluence_attachment_update, so it earns a 4 rather than a 5.

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

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

With no annotations, the description carries the full burden. It discloses mutual exclusivity of id and space, optional recursion, and max depth semantics, but does not mention pagination, sort order, or error behavior. These are relevant for a listing tool, so the transparency is decent but not rich.

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

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

The description is three sentences, each with a distinct purpose: core usage, ideal use case, and alternative. Examples are inline and the text is front-loaded with the main action. There is no fluff.

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

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

The tool has no output schema and no annotations, so the description is critical. It covers both input modes, recursion, and sibling differentiation. The only gap is the absence of return shape or pagination details, but a simple list tool can be considered adequately specified.

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 baseline is 3. The description goes beyond the schema by providing example values for id and space and explicitly linking max_depth to recursion ('Maximum tree depth when recursive is set'). This adds meaningful usage context.

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

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

The description clearly states the action ('List children') and the two invocation modes (page ID or space key), with concrete examples. It also distinguishes itself from confluence_space_pages, making its role as a hierarchical traversal tool 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?

Explicit guidance is given: 'so this is the tool for walking a page hierarchy' and a direct alternative is named: 'To enumerate EVERY page in a space (flat, with status/sort filters and cursor pagination) use confluence_space_pages instead.' This fully satisfies when-to-use vs 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?

Discloses that content is converted to ADF before posting, which is a key transformation. In absence of annotations, the description adds this behavioral detail. Does not cover error handling or return values, but sufficiently describes core behavior.

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

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

Three sentences, each essential: defines action, clarifies input options, and directs to alternative tool. No redundancy or unnecessary 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 is adequate for the tool's simplicity but lacks information on return values (e.g., comment ID) since no output schema exists. Also omits prerequisites like page existence. Given the absence of annotations, this is a noticeable 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 coverage is 100%, baseline 3. The description adds meaning beyond schema by explaining the mutual exclusivity of 'content' and 'content_path' and that 'content_path' is a filesystem path the server reads. This clarifies usage beyond the schema's property descriptions.

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

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

The description clearly states the tool 'Post a markdown comment to a Confluence page as a page-level footer comment.' It differentiates from the sibling 'confluence_comment_add_inline' by specifying 'page-level footer comment' versus inline, and mentions the conversion to ADF.

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

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

Provides explicit guidance: 'For inline (anchored) comments, use confluence_comment_add_inline' gives a clear alternative. Also explains the mutually exclusive parameters 'content' and 'content_path' with 'not both'. References the CLI mirror for cross-tool consistency.

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

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

With no annotations provided, the description carries full burden. It discloses error conditions ('Errors if the anchor does not match or `match_index` is out of range'), exact-match requirement for `anchor_text`, and mutual exclusivity of `content`/`content_path`. This goes beyond the bare operation, though it does not describe return values or permissions.

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 sentences with no filler. First sentence defines purpose, second gives sibling differentiation, third covers parameter constraints, fourth states error behavior. Each sentence 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 tool with 5 params, no output schema, and no annotations, the description covers purpose, when-to-use, parameter relationships, and error behavior. It is sufficiently complete for an agent to select and invoke correctly, though it omits explicit return-value details.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the `content` vs `content_path` mutual exclusion and the 1-based `match_index` disambiguation rule, which are not fully captured in the schema's property descriptions.

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

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

The description clearly states 'Post a markdown comment anchored to a text selection on a Confluence page' — a specific verb and resource. It explicitly contrasts with sibling `confluence_comment_add` for page-level comments, making differentiation 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?

Explicitly directs when to choose the alternative: 'For a page-level comment not tied to any text, use `confluence_comment_add` instead.' It also explains parameter selection trade-offs between `content` and `content_path`, and when `match_index` is needed.

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

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

With no annotations, the description fully discloses behavior: it explains that anchors do NOT follow text edits, describes failure modes (torn, drifted, mark_lost), confirms the tool is read-only, and details the YAML output including statuses and suggested_new_anchor. This goes beyond simple operation to explain the underlying mechanism.

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 moderately long but every sentence is information-dense: problem statement, mechanism, output format, status values, and alternative tool. It is front-loaded with the main purpose and ends with a mirror reference, with no filler.

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

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

Given no output schema, the description compensates by explicitly listing the YAML contents (status, original/current anchored text, suggested_new_anchor). It also covers the conceptual context (why drift happens) and references a sibling tool, making it complete for a single-parameter audit tool.

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

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

The only parameter 'id' is described in the schema as 'Confluence page ID.' The description adds no new parameter-specific details beyond already using 'page' in the text, so it does not exceed the schema's coverage. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Audit every inline comment on a Confluence page for anchor drift.' It clearly distinguishes this tool from siblings by describing its diagnostic role and explicitly naming the pairing tool 'confluence_comment_reanchor' for fixes.

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

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

The description provides explicit usage context: it diagnoses anchor drift issues. It also states 'Read-only — fix drift with `confluence_comment_reanchor`,' directly telling the agent when to use this tool versus the alternative.

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 provided, so description transparently states irreversibility, destructive guard (confirm: true), return format (YAML), and prevents accidental API calls. Lacks rate limit or auth details.

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 action, no fluff. Every sentence adds critical information: action, constraints, behavior, return format, and CLI mirror.

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 deletion tool with 3 parameters, no output schema, and no annotations, the description covers purpose, usage constraints, behavioral implications, and return type completely.

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

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

Schema covers 100% of parameters; description adds value by linking comment_id to the list tool and emphasizing the confirm parameter as a destructive guard, providing context beyond the schema.

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

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

The description clearly states the tool deletes a Confluence comment, specifies the required comment_id from the list tool, and distinguishes between footer and inline kinds, differentiating it from sibling tools.

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 context on when to use (after listing comments) and constraints (kind values, confirm guard), but does not explicitly contrast with alternatives like editing or resolving comments.

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?

Describes that the new body replaces current text, returns YAML, and mentions API endpoint differences for kind. No annotations exist, so description carries the burden; it would benefit from disclosing side effects (e.g., irreversible replacement) or auth needs. Adequate but not exhaustive.

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?

Concise at 5 sentences, each providing essential information without redundancy. Information is front-loaded with action and key constraints.

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?

Covers key operational aspects: required parameters, constraint on kind, mutual exclusivity, return format (YAML). Missing details on return value structure and error scenarios, but given simplicity of tool, it is mostly 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%, baseline 3. Description adds valuable context: origin of comment_id, enumeration of kind values, mutual exclusivity detail, and markdown-to-ADF conversion. This extra semantics justifies a 4.

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

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

The description clearly states the action (edit), resource (existing Confluence comment body), and identifier (by comment_id from confluence_comment_list). It distinguishes from siblings by specifying it edits rather than adds, deletes, or lists.

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

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

Provides clear guidance on parameter constraints (kind must be footer or inline, mutual exclusivity of content and content_path). Mentions CLI mirror for familiarity. However, does not include prerequisites like edit permissions or conditions for use vs 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 fully discloses behavior: auto-pagination, `kind` parameter options and default behavior, `limit=0` returns all, inline comment fields and the caveat that anchors do not follow text edits, and author IDs format. This is comprehensive and transparent.

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

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

The description is a concise paragraph, front-loaded with primary purpose, followed by parameter behavior, inline specifics, and author ID resolution. Every sentence adds value; no redundancy or fluff.

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

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

Given no output schema, the description covers key aspects: auto-pagination, inline comment details, author IDs. However, it does not specify the complete structure of a comment object (e.g., fields like body, created date) or pagination mechanics, leaving some gaps for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some detail about inline comment fields (inline_marker_ref, durable inline_original_selection) which relates to the output rather than input parameters. For `kind` and `limit`, the description largely repeats schema descriptions.

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

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

The description clearly states 'List comments on a Confluence page (auto-paginated)', specifying verb and resource. It distinguishes from sibling tools like `confluence_comment_add` and `confluence_comment_audit` by focusing on listing, and mentions auto-pagination as a feature.

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

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

The description does not explicitly state when to use this tool vs alternatives. It provides tips on using `confluence_user_get` for author IDs and `confluence_comment_audit` for drift, but lacks a clear 'when to use this' statement. The sibling list is given, but the description itself offers no direct guidance on selection.

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

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

No annotations provided, so description carries the burden. It mentions key behavioral traits: operates entirely on ADF without round-tripping through JFM (preserving marks), and supports dry_run for validation. But does not disclose if the operation is reversible, what happens to the old anchor, or required permissions.

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

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

Single paragraph, front-loaded with purpose. Sentences are informative but not excessively verbose. Some technical details (JFM, ADF) could be in a separate note, but overall concise and well-structured.

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

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

Given no output schema, the description does not explain return format or error handling. It covers usage context, parameter details, and dry_run behavior. Lacks information on what is returned on success/failure, making it slightly incomplete for an agent to fully assess the tool's output.

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 has 100% coverage, so baseline is 3. Description adds value by explaining that match_index disambiguates occurrences, anchor_text must be exact and can span multiple runs but not block boundaries, and dry_run is for validation. This nuance goes beyond the schema descriptions.

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

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

Clearly states the action: 'Move an inline comment's anchor to a new run of text'. Identifies the specific resource (Confluence page ADF) and distinguishes from sibling tools by mentioning it is the fix for 'drifted'/'mark_lost' comments flagged by confluence_comment_audit.

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 states the precise scenario for use: fixing comments flagged by confluence_comment_audit. Implicitly implies not to use for other comment operations. Does not explicitly list when not to use or alternative tools, but the context is clear.

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 provided. Description discloses return format (YAML) and that it mirrors a CLI command, but lacks details on side effects, permissions, or idempotency. Adequate for a simple reopen action.

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, each earning its place: action, scope, return format, and reference. Front-loaded with verb and resource. No unnecessary words.

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

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

Given the simple tool (single param, no output schema), the description is largely complete. It mentions return format, source of ID, and inline-only constraint. Could mention error cases or required permissions for full completeness, but not critically 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 covers 100% of the one parameter. Description adds value by noting comment_id comes from confluence_comment_list and that the tool is for inline comments only, providing context 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?

Clearly states the verb 'reopen', resource 'resolved inline Confluence comment', and specifies it's for inline comments only using comment_id from confluence_comment_list. Distinguishes from sibling tools like confluence_comment_resolve.

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 says 'Reopen a resolved inline Confluence comment' and 'Inline comments only', giving clear context for when to use. Does not explicitly list alternatives or when not to use, but purpose is sufficiently specific.

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 full behavioral disclosure. It correctly notes that Confluence requires committing to a kind-specific endpoint, a key behavioral trait. It does not mention pagination beyond limit=0, but is otherwise transparent.

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

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

The description is two sentences with clear front-loading and no fluff. The mention of mirroring a command adds minor redundancy but does not harm 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?

There is no output schema, and the description does not explain what fields or structure the reply list returns. It also lacks details on pagination behavior beyond limit=0. This leaves a significant gap in understanding the tool's output.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for kind (reason for requirement) and provides a concise note on limit=0 meaning unlimited. This adds slight value beyond the schema but does not substantially deepen understanding.

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 it lists replies (child comments) of a Confluence comment, using specific verb and resource. It distinguishes from siblings like confluence_comment_list by specifying that it targets replies to a specific comment and requires a kind parameter.

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

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

The description explains that kind must be 'footer' or 'inline' due to API constraints and that limit=0 returns all replies. However, it does not explicitly contrast with sibling tools or provide when-not to use, leaving usage guidance 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 provided. Description mentions 'Returns YAML' but does not disclose destructive nature, permissions, rate limits, or other behavioral traits. Missing important context for a mutation tool.

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

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

Two sentences: first defines purpose and parameter source, second adds return format and CLI reference. No fluff, front-loaded with key info.

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 single param and no output schema, description covers purpose, parameter origin, and return format. Lacks behavioral completeness (permissions, side effects) but adequate for a simple tool.

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

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

Only one parameter with schema coverage 100%. Description adds context that comment_id comes from `confluence_comment_list`, which is helpful but baseline is met. No additional semantic detail beyond 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?

Clearly states the action (resolve) and resource (inline Confluence comment). Distinguishes from siblings like edit, delete, reopen. Specific about inline only.

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?

Specifies 'Inline comments only' and references the list tool for obtaining comment_id, implying use after listing. Mentions CLI mirror for familiarity. No explicit when-not-to-use, but context is clear.

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 full burden. It details the diff approach, version reference formats, detail levels, and budget truncation. Some behavioral aspects like error handling are missing, but overall transparency is good.

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 well-structured with key points front-loaded. It is slightly verbose but every sentence adds value. Could be more concise without losing 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 no output schema, the description covers return types and detail levels appropriately. It explains version references and budget truncation. Missing some edge cases, but overall complete enough for a complex tool.

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

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

Schema coverage is 100% with descriptive parameter descriptions. The description adds context on version refs and detail levels, but does not significantly enhance understanding beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool compares two versions of a Confluence page using a structurally-aware diff. It distinguishes from character-level diffs and mentions a sibling command, making the purpose unambiguous.

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

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

The description explains what the tool does but does not explicitly state when to use it over alternatives like confluence_compare_section or confluence_read. The context is clear but lacks exclusion criteria.

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

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

Without annotations, the description carries the full burden. It mentions statelessness and output formats, implying a read-only inspection, but does not explicitly declare safety profile, rate limits, or permissions.

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 (3 sentences) and front-loaded with the core purpose. Every sentence adds value, with no extraneous information.

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

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

For a simple follow-up tool with 2 parameters fully described, the description is largely complete. It explains the cursor source and output formats, but omits details on error handling or return value structure.

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 tool description repeats parameter info from the schema and adds context about the cursor's role, but does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool drills into a section diff using a cursor from confluence_compare, lists output formats, and distinguishes itself from the parent comparison tool by specifying the cursor source and outline mode.

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 indicates when to use this tool (after a cursor from confluence_compare outline mode) but does not explicitly state when not to use it or provide alternatives beyond the single parent tool.

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

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

Despite no annotations, description fully discloses behavior: carries attachments/labels/properties, excludes restrictions, returns YAML with new page id, and is single-page only. No contradictions.

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 concise sentences with no wasted words. Front-loaded with main action, efficiently covers key points.

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?

Even without output schema, description explains return value (YAML with id). Covers all relevant behavioral aspects for a copy tool, making it 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 already covers all three parameters with clear descriptions (100% coverage). Description adds minimal extra context beyond schema; mentions return format but that is not parameter-related.

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

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

Clearly states the tool copies a single Confluence page under a destination parent page, with explicit mention of what is carried (attachments, labels, properties) and what is not (restrictions). Distinguishes from siblings like 'confluence_move' and 'confluence_create'.

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?

Specifies single-page copy only and mentions what content is carried, helping decide appropriateness. Lacks explicit when-not-to-use or alternative tools but provides sufficient context.

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

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

No annotations provided, but description fully covers behavioral aspects: creates a page (write operation), returns new page ID, explains override warnings, describes dry_run validation, and notes JFM format constraints.

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?

Well-structured with purpose first, then input modes, format details, file paths, dry_run, return value. Every sentence adds value; no repetition.

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

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

Covers all necessary aspects: purpose, inputs, format, behavior, return value. References external resource for JFM specs. Mirrors CLI command. Complete for a create tool.

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

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

Schema description coverage is 100%, but description adds significant meaning: explains parameter dependencies (title required unless document provides), mutual exclusivity (document vs content), and recommends file path parameters over inline.

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 explicitly states 'Create a NEW Confluence page' and distinguishes from 'confluence_write' which overwrites existing pages. It clearly identifies the tool's purpose and scope.

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

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

Provides explicit guidance: use for new pages vs write for updates, explains two input modes (fields vs document), recommends dry_run for validation, advises using file paths when content is on disk, and warns about JFM format.

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 provided, so description carries full burden. It discloses that the operation is irreversible, requires confirmation, and offers optional permanent purge. All critical behavioral traits are communicated clearly.

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 plus a note, highly concise. Front-loaded with purpose and key details. No unnecessary 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?

Covers purpose, usage, parameter behavior, and output effect (trash vs purge). Lacks explicit mention of return value or side effects, but the tool is a delete operation and no output schema exists, so this is a minor 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% for all three parameters. The description adds context: `confirm` must be true to prevent accidents, `purge` requires space admin, and the overall destructive nature. Enriches the schema descriptions.

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

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

Clearly states 'Delete a Confluence page', which is a specific verb and resource. Distinguishes from sibling tools like `confluence_attachment_delete` and `confluence_create` by focusing on page deletion and emphasizing irreversibility.

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

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

Provides explicit guidance on using `confirm` to prevent accidental deletions and `purge` for permanent deletion with space admin requirement. Mentions CLI mirror for familiarity, but does not explicitly state when not to use the tool.

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

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

Discloses the core behavior (recursive download, YAML manifest, attachment handling) but lacks deeper context such as side effects (filesystem writes), error handling, or rate limits. Since no annotations are provided, the description carries full burden, and it covers only the basic behavioral traits.

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

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

The description is a concise paragraph of five sentences, each adding new information. It is front-loaded with the primary purpose and efficiently conveys key usage details 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?

Given the tool's complexity (8 parameters, no output schema, no annotations), the description adequately covers the main use case, alternative tool, and key parameters. It mentions the return format (YAML manifest) and attachment subdirectory, providing sufficient context for an agent to invoke the tool 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 100%, so the schema already documents all parameters. The description adds value by clarifying the id/space mutual exclusivity and the `include_attachments` behavior, but does not significantly extend parameter understanding beyond the schema.

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

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

The description clearly states 'Recursively download a Confluence page or an entire space into a directory' using specific verbs and distinct resources. It differentiates from the sibling tool `confluence_read` by noting that tool reads a single page's body without file writes.

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 states the alternative `confluence_read` for single-page reading, and outlines key usage requirements like providing either `id` or `space`. However, it does not explicitly mention when not to use this tool beyond the alternative.

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?

Description fully discloses behavior: metadata-only, newest-first ordering, filtering capability for since parameter (numeric version or ISO date), limit defaults (20, with 0 meaning unlimited). It also references a known command for consistency. No annotations are provided, so the description carries full burden and does so completely.

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?

Description is compact and efficient. Every sentence adds value, no wasted words. It is front-loaded with the purpose and then details parameters and behavioral notes. The structure is logical and easy to parse.

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

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

For a tool with no output schema, the description adequately describes the returned fields (version number, timestamp, author account ID, edit message, minor-edit flag). It also references necessary sibling tools for post-processing. The tool is straightforward, and the description covers all necessary context.

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

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

Schema description coverage is 100%, so baseline is 3. But the description adds significant value: explains the since parameter accepts two formats with examples, clarifies limit default and that 0 means unlimited, and explains the id parameter. This goes beyond the schema's short descriptions.

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

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

Description clearly states the tool lists version history metadata for a Confluence page. It specifies the returned fields (version number, timestamp, author account ID, etc.) and distinguishes itself from siblings like confluence_read and confluence_user_get.

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?

Description provides explicit when-to-use guidance: it notes that content bodies are not fetched and directs to confluence_read for that. It also suggests using confluence_user_get for resolving author IDs. The since and limit parameters are explained with usage details.

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 should disclose behavioral traits. It only states the action without mentioning behavioral aspects such as idempotency, authorization needs, or effects (e.g., whether labels are appended or replaced). Minimal transparency.

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

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

The description is extremely concise and front-loaded: two sentences with no extraneous information. Every word is necessary.

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 fully described parameters, the description covers the basic purpose. However, it lacks important context such as whether labels are appended or overwritten, and error scenarios. It is minimally adequate but not comprehensive.

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

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

Schema description coverage is 100%, with clear parameter descriptions for 'id' and 'labels'. The tool description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action (add) and resource (labels to a Confluence page). It distinguishes from sibling tools like confluence_label_list and confluence_label_remove by specifying addition. However, it does not explicitly differentiate from them, missing a chance to clarify when to use each.

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 vs alternatives like confluence_label_list or confluence_label_remove. No prerequisites or context provided.

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

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

No annotations are provided, so the description must carry the burden. It mentions auto-pagination and the limit behavior but does not explicitly state that it is a read-only operation or disclose any other behavioral traits.

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

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

Two sentences with no redundancy. The first sentence gives the core purpose and auto-pagination, the second adds a key detail and a reference command. 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?

With no output schema, the description does not explain what the tool returns (e.g., label names, IDs) or error conditions. However, for a simple list tool with two parameters, the information is mostly adequate but leaves some gaps.

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

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

Schema coverage is 100%, describing both parameters. The description adds context beyond the schema by explaining auto-pagination and that limit=0 returns all labels, which enhances understanding.

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 'List labels on a Confluence page' with a specific verb and resource. It includes auto-pagination and the notable limit=0 behavior, and distinguishes from sibling tools like add/remove.

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

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

No explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it or provide comparisons to other listing tools, leaving the agent without decision support.

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

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

With no annotations provided, the description bears full burden for behavioral disclosure. It marks the operation as destructive and explains the confirm guard, but does not mention other behaviors such as idempotency, error handling, or what happens if labels do not exist.

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 convey purpose, destruction, the critical confirm requirement, and a reference to the CLI command. No wasted words; efficiently 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 simple 3-parameter tool with no output schema, the description covers the core purpose and the essential guardrail. It is mostly complete, though it could mention return values or behavior on missing labels.

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

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

The input schema already describes all three parameters with 100% coverage. The description adds value by explicitly noting that 'confirm' must be 'true' and acts as a destructive guard, enhancing understanding beyond the schema.

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

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

The description clearly states 'Remove one or more labels from a Confluence page' with a specific verb and resource. It distinguishes from sibling tools like confluence_label_add and confluence_label_list.

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

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

The description explicitly requires 'confirm: true' for the operation to proceed, serving as a usage guideline. However, it does not elaborate on when to use this tool versus alternatives like confluence_label_add.

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 full burden. It discloses the returned YAML metadata (id, title, parent_id, ancestors), the three position behaviors, and the same-space limitation. Does not mention permission requirements or side effects on page content/attachments, but covers key behavioral aspects.

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, no wasted words. Front-loaded with action, followed by position semantics, constraint, and return format. Every sentence 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?

Given no output schema, description adequately specifies return format. Parameters are fully described with added context. Constraints are clear. The tool is well-situated among sibling tools with a distinct identity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying position defaults ('append'), explaining each position meaning in context, and elaborating target_id's role relative to position. This exceeds schema descriptions.

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

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

Clearly states 'Move or reparent a Confluence page within its current space.' Uses specific verb and resource. Distinguishes from sibling tools like confluence_create, confluence_delete, etc., by focusing solely on moving/reparenting.

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

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

Provides explicit constraint 'Same-space only — cross-space moves are not supported,' helping the agent avoid misuse. Explains position options. Lacks explicit comparison to alternative tools for cross-space scenarios, but the constraint effectively guides when not to use.

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 fully discloses behavior: default output is JFM markdown, `output_file` returns YAML summary, `version` reads immutable snapshots, inline-comment anchors do not follow edits, author IDs are returned as Atlassian account IDs. No contradictions.

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 thorough but slightly verbose; however, every sentence adds value and the structure is logical. It could be trimmed marginally without losing content.

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

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

Covers all 4 parameters, return formats, common pitfalls, and links to related tools. Without an output schema, the description adequately explains what the tool returns in different scenarios.

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?

Despite 100% schema coverage, the description adds significant context: explains default format, version as immutable snapshot, output_file behavior (YAML summary, useful for large pages), and gives examples for `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?

The description explicitly states 'Fetch a Confluence page by numeric ID' and distinguishes itself from sibling tools like `confluence_download` for page trees. It clearly identifies the resource and action.

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

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

Provides explicit guidance on when to use different formats (`jfm` vs `adf`), when to use `version`, when to use `output_file`, and when to use alternative tools (`confluence_download`, `confluence_comment_audit`, `confluence_user_get`). Also warns about preserving `localId` attributes for editing.

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 discloses the output format (YAML), notes the nested structure, and implies read-only behavior via 'Show'. It does not discuss auth or rate limits but is transparent about output complexity.

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: first states purpose and output, second adds CLI mirroring. No wasted words, front-loaded with key information.

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

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

For a simple read tool with one parameter and no output schema, the description covers purpose and output format. It mentions per-operation arrays. It could elaborate on potential errors or empty results, but overall adequate.

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 single parameter content_id is described in the schema as 'Confluence page (content) ID.' The description adds no further meaning beyond the schema, and schema coverage is 100%, so baseline score 3 applies.

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

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

The description clearly states the tool shows read/update restrictions on a Confluence page, and specifies the output format (raw JSON as YAML). It distinguishes from sibling tools like grant/revoke by focusing on viewing.

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

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

The description implies usage for viewing restrictions but does not explicitly state when to use this tool versus alternatives like grant/revoke. No when-not guidance is provided.

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

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

No annotations are provided, so the description must disclose behavioral traits. It mentions that the tool grants restrictions and returns a YAML status, but does not address side effects (e.g., overwriting existing restrictions), authentication requirements, rate limits, or error states. This is a significant gap for a mutation tool.

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

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

Three short, front-loaded sentences: purpose, parameter guidance, and return format/CLI mirror. 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?

With full schema coverage and no output schema, the description provides the return format and a key constraint (mutual exclusivity). It could mention error handling or idempotency, but is largely adequate for a simple grant tool.

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

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

Schema description coverage is 100%, but the description adds value by explaining the operation values and the mutual exclusivity of account_id/group. This goes beyond the schema's parameter descriptions.

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

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

The description clearly states the verb 'grant' and the resource 'restriction on a Confluence page', specifies operations 'read'/'update', and distinguishes from sibling tools like get/revoke. 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?

The description explains that exactly one of account_id or group must be supplied, providing guidance for parameter selection. However, it does not explicitly state when to use this tool versus alternatives like get or revoke, though the name and context imply grant-only 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 must carry the burden. It discloses the return format (YAML with 'status: ok') and parameter constraints. However, it does not mention potential side effects, permissions required, or behavior when no restriction exists for the given user/group. This leaves gaps for an agent.

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

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

The description is three sentences: first states purpose, second gives parameter constraints, third provides return format and CLI reference. It is front-loaded, concise, and contains no filler. 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 the tool's moderate complexity (4 parameters, 2 required, no output schema), the description covers purpose, parameter constraints, and return format. It lacks details on error handling or prerequisites (e.g., page existence), but for a simple revocation tool, it is largely sufficient. Minor gap in not addressing edge cases.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by reinforcing the mutual exclusivity of account_id/group and clarifying the operation values. It also introduces the return format, which is not in the schema. This enhances understanding beyond the schema 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 ('revoke'), resource ('restriction on a Confluence page'), and target ('user or group'). It specifies the operation parameter as 'read' or 'update' and the mutual exclusivity of account_id and group. This distinguishes it from sibling tools like 'confluence_restriction_grant' and 'confluence_restriction_get'.

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

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

The description provides clear constraints (operation values, mutual exclusivity) and implies usage for revocation. It mentions mirroring a CLI command, giving additional context. However, it doesn't explicitly state when not to use this tool or list alternatives, though sibling names strongly indicate complementary tools.

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 provided, so description carries full burden. It mentions output format (YAML) and mirrors a CLI command, but does not disclose potential rate limits, auth requirements, or other behavioral traits. Adequate but not rich.

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

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

Two sentences with no filler. Includes example, usage guidance, and CLI mirror reference. 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 the tool's simplicity (2 params, no output schema), the description covers the query language, example, output, and post-search actions. Leaves no significant gaps for an agent to use 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 covers 100% of parameters with descriptions. Description adds an example CQL query, mentions default limit of 20, and explains output structure, providing additional context beyond the schema.

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

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

The description clearly states it searches Confluence pages using CQL, specifies the resources (page IDs, titles, space keys), and distinguishes from sibling tools like confluence_children and confluence_space_pages for enumeration vs text query.

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 tells when to use alternatives (confluence_children/confluence_space_pages for enumeration) and how to use results (feed ID into confluence_read). Provides clear context for selection.

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

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

With no annotations, the description fully covers pagination (one page per call, cursor flow), default limit of 25, filter combination (AND), and verbatim pass-through of type/status. It does not mention permissions or side effects, but as a list operation, these are minimal and behavior is well-documented.

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 highly concise with two sentences, front-loading the main purpose. Each sentence serves a clear function (action statement then filter/pagination details), with no wasted words.

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

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

The tool has no output schema, and the description does not detail the structure of returned items (e.g., space keys, names). It adequately covers pagination and filter semantics, but missing return format details make it slightly incomplete for a list tool.

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

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

Schema coverage is 100%, so the schema documents parameters. The description adds value by listing common values for type/status, explaining AND combination, default limit, and cursor usage, providing operational context beyond the schema.

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

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

The description clearly states 'List Confluence spaces (one page per call)' with a specific verb and resource. It distinguishes from sibling tools like confluence_space_pages by focusing on spaces themselves, but does not explicitly differentiate from all 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 lists optional filters (keys, type, status) and explains pagination (cursor usage) and filter combination (AND). It provides implicit usage context but does not explicitly guide when to use this tool versus alternatives like confluence_search or confluence_space_pages.

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 provided, so description carries full burden. It accurately describes return fields (no page bodies), filter behavior (passed through verbatim), pagination mechanism, and default limit. No contradictions.

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 well-structured and informative, but slightly verbose with the mirror command at the end. Still, every sentence contributes 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 output schema, the description fully explains return fields, pagination, filters, defaults, and sibling alternative. No gaps for this complexity level.

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

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

Input schema has 100% description coverage, but the description adds significant value by listing common sort and status values, explaining they are passed verbatim, detailing cursor for pagination, and stating default limit.

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

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

The description clearly states the tool enumerates all pages in a Confluence space as a flat list, with an example space key. It explicitly differentiates from sibling `confluence_children` for hierarchical navigation.

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 tells when to use this tool vs the alternative `confluence_children`. Also explains pagination with cursor and default limit, guiding iterative calls.

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 provided, so the description carries full burden. It discloses error handling (stub record with error field, batch never fails), permission sensitivity (email when accessible), and output format. No contradictions.

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?

Concise yet comprehensive: each sentence adds value, purpose is front-loaded, and structure is clear. No redundant information.

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

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

With a single simple parameter and no output schema, the description fully covers input, output, error behavior, and relationship to other tools. No gaps identified.

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

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

Schema coverage is 100% for the single parameter, and the description adds a usage optimization (batch all IDs) but does not provide additional semantic detail beyond what the schema already offers.

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

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

The description clearly states the tool resolves account IDs to user records, specifies the return fields (account_id, display_name, email, account_type), and distinguishes it from the sibling tool confluence_user_search by calling itself the reverse.

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?

Implies usage via reverse relationship with confluence_user_search and suggests batching IDs in one call, but does not explicitly state when to use versus alternatives or provide exclusion criteria.

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 cover behavioral traits. It states the search criteria and limit behavior, but does not disclose return format, pagination details beyond limit, authentication requirements, or potential rate limits. For a simple search tool, this is adequate but minimal.

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

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

The description consists of two short sentences, front-loading the purpose and then providing additional parameter detail. There is no redundant or extraneous information. Every sentence serves a clear purpose.

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

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

Given the tool has only two parameters, no output schema, and no nested objects, the description provides the essential purpose and parameter behavior. However, it lacks information about the return value structure (e.g., list of user objects, fields included), which would be helpful for an agent invoking the tool.

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

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

The input schema already describes both parameters with 100% coverage. The description adds value by clarifying the special behavior of 'limit=0' (unlimited results) and the default value of 25, which goes beyond the schema's description.

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

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

The description clearly states the tool searches Confluence users by display name or email, which matches the tool name. However, it does not explicitly differentiate from the sibling tool confluence_user_get, which might retrieve a single user by ID. The verb 'search' and the resource 'Confluence users' are 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?

The description includes parameter behavior (limit of 0 returns all matches, default 25) and a reference to a CLI command, but it does not provide guidance on when to use this tool versus alternatives like confluence_user_get or jira_user_search. No 'when to use' or 'when not to use' context is given.

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

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

With no annotations provided, the description carries the full burden. It does disclose the return format ('Returns YAML {watching: true}') and the default behavior for account_id. However, it omits any mention of side effects (e.g., idempotency, permission requirements, or potential errors) that could be relevant for a mutation operation.

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

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

The description is two sentences, front-loaded with the action. It includes the key usage detail (default account), the return value, and a CLI equivalence. Every sentence adds value without waste.

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

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

For a simple 2-parameter tool with full schema coverage, the description is largely complete. It states the purpose, default behavior, and return format. It lacks edge-case behavior (e.g., error handling, idempotency) but these are not critical for the core use case, and the CLI mirror provides a reference point.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal new parameter meaning beyond the schema: it reiterates the account_id default (already in schema) and refers to content_id as a page ID (already in schema). No additional syntax or format details are provided.

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 a watcher to a Confluence page'. This is a specific verb+resource, and the mention of 'Confluence page' distinguishes it from Jira watcher tools like jira_watcher_add. The scope is unambiguous.

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

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

The description implies when to use the tool (when you need to add a watcher to a Confluence page) but does not explicitly discuss alternatives or exclusions. Sibling tools like confluence_watcher_remove and confluence_watcher_status are not referenced, so the agent must infer usage from the name and context.

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

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

No annotations provided, so description must disclose behavior. Mentions return value and default but does not elaborate on permissions, irreversibility, or side effects of removal beyond being a mutation.

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?

Extremely concise: two sentences with no fluff. Front-loaded with action and resource. Every sentence adds necessary information.

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

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

Given no annotations or output schema, description covers purpose, default, and return. Could be enhanced with permission requirements or confirmation of action, but adequate for a simple removal tool.

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

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

Schema covers 100% of parameters. Description adds value by stating default for account_id and the return format, which clarifies the effect.

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 'Remove a watcher from a Confluence page' clearly. Specifies default for account_id and return value. Distinguishes from sibling tools 'confluence_watcher_add' and 'confluence_watcher_status' by naming the action.

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?

Indicates default behavior for account_id (authenticated user). Mentions CLI mirror for familiarity. Lacks explicit when-to-use vs alternatives or when-not-to-use 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?

Discloses return format YAML {watching: bool} and default behavior for account_id. No annotations, but description is transparent for a simple read check.

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

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

Two concise sentences with no unnecessary words. Front-loaded with purpose.

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?

Complete for a simple status check: covers purpose, output format, default parameter value. No output schema needed.

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 has 100% coverage for both parameters. Description adds only default info already in schema; no extra semantic value.

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?

Clear verb 'report' and specific resource 'whether a user watches a Confluence page'. Distinguishes from sibling watcher add/remove tools.

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

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

No explicit when-to-use or when-not-to-use guidance. Implicit from name and siblings, but not stated.

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

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

With no annotations, the description fully covers behavioral aspects: it warns about data loss of inline comments if 'localId's are omitted, clarifies that JFM is markdown (not wiki markup), and explains the dry_run behavior. These are critical details beyond the basic write operation.

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

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

The description is relatively long but well-structured, starting with the main action and then adding important caveats. Each sentence provides useful information, though some redundancy could be trimmed. Overall, it is front-loaded and clear.

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