confluence_get_page_context

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals a non-obvious behavior: 'optional section failures are returned with partial status.' This tells the agent that individual sections may fail without aborting the whole call. The verb 'Gather' implies a read-only operation, which is appropriate. It does not discuss rate limits or auth, but these are not critical for a read operation. The partial-failure disclosure adds meaningful 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 two sentences, front-loaded with 'HIGH-LEVEL:' to signal its purpose, and states the key benefit first. It avoids redundancy and wastes no words. The structural choice to lead with the aggregation intent and then mention the partial-failure behavior is efficient.

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?

Without an output schema, the description should give a clear sense of the return structure. It does: 'body/current version plus optional ancestors, attachments, and comments.' It also mentions partial failures. However, it does not detail the format of the body, how sections are organized, or any pagination behavior (though max_items_per_section hints at it). For a tool with 8 parameters and no output schema, this is adequate but not exhaustive.

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 has 0% description coverage, so the description must compensate for all 8 parameters. It only indirectly addresses the include_* booleans ('optional ancestors, attachments, comments') and the body/version, but does not explain body_format, max_chars, comment_types, or max_items_per_section. The schema itself provides enums and defaults, but the description adds no meaning beyond that. The high-level mapping is insufficient for an agent to understand parameter behavior without inspecting 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's purpose: to gather page context (body/current version plus optional ancestors, attachments, comments) in one call. It uses a specific verb ('Gather') and resource ('one page'), and distinguishes itself from sibling primitives by framing it as a high-level aggregation. The phrase 'Prefer this over calling several page context primitives separately' explicitly positions it against the family of simpler 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 gives explicit guidance: prefer this tool when you need multiple page context sections, and implies that for single pieces you might use the primitives. However, it does not name specific sibling tools or give clear exclusions (e.g., 'if you only need the body, use confluence_get_page'). The guidance is useful but could be more precise about when not to use it.

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