confluence_comment_add_inline

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

No annotations are provided, but the description discloses that the tool posts a comment, requires exact anchor text, and errors if anchor not found or match_index out of range. It also mentions the CLI equivalent. While it doesn't explicitly state permissions or rate limits, the behavior is sufficiently clear for a 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?

Four sentences, each earning its place. The first sentence states the core purpose, the second provides the alternative, the third explains anchor behavior, and the fourth mentions the CLI mirror. 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 tool's complexity (5 parameters, 2 required, no output schema), the description covers usage guidelines, parameter semantics, error conditions, and sibling relationship. It also notes conversion to ADF and the CLI mirror, making it complete for an agent to use correctly.

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

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

Schema description coverage is 100%, but the description adds value by clarifying that `content_path` is a filesystem path the server reads, that `anchor_text` must match exactly, and that `match_index` is 1-based. This goes beyond the schema descriptions, which only state type and constraints.

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 (an inline comment).' It specifies the verb (post), resource (markdown comment), and scope (anchored to text), and distinguishes itself from the sibling 'confluence_comment_add' which is for page-level comments.

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 when not to use this tool: 'For a page-level comment not tied to any text, use `confluence_comment_add` instead.' Also provides guidance on using `content` vs `content_path`, the need for exact `anchor_text`, and the use of `match_index` for multiple occurrences.

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