get_page_tree

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

With no annotations provided, the description carries the full transparency burden. It discloses local file system writes when output_dir is set, image downloads and URL rewriting when include_images is true, and performance implications of include_body. It does not explicitly state that Confluence is never modified, but the verb 'get' plus the local-only side effects imply a read-only operation on the server.

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 a one-sentence summary followed by an Args block. Every sentence earns its place—no fluff, while the cross-reference to the fetch-confluence skill adds useful context. It is compact given 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?

Given the tool's complexity (recursive tree, optional file system writes, image downloads), the description covers all key behaviors and parameter interactions. An output schema exists, so return-value details are not needed. Minor edge cases like missing directories or error handling are absent, but the core usage and effects are thoroughly described.

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

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

Schema description coverage is 0%, yet the description gives meaningful semantics for all five parameters: page_id identifies the root, include_body controls markdown body fetching, output_dir triggers file exports and explains naming by depth and title, include_images requires output_dir and rewrites URLs, and images_dir defaults to pictures/ inside output_dir. This far exceeds the bare 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 states 'Get a page and all its descendants as a flat list,' which is a specific verb+resource+scope. It clearly distinguishes the tree-fetch behavior from siblings like get_page and get_section by emphasizing descendants and optional file export.

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 opening sentence implies when to use: when you need a page plus its entire subtree. The Args section adds context for when output_dir triggers file writing and when include_images takes effect, and it references the fetch-confluence skill as an equivalent. However, it does not explicitly state alternatives or when not to use, though the sibling context makes this reasonably clear.

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