sync_confluence_docs

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions that it syncs to local markdown files, but it doesn't disclose critical side effects such as whether it overwrites existing files, whether it performs a one-way or two-way sync, or whether it deletes files that are not in Confluence. The word 'sync' is ambiguous and could imply destructive behavior, making this a significant gap.

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 single sentence, 15 words long, that efficiently states the core action, the target, and the primary modes of use. It front-loads the verb 'Sync' and is free of any filler, making it extremely 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 the moderate complexity (6 parameters, no required ones, no output schema), the description provides the essential purpose and input modes but omits details about return values, sync behavior (e.g., overwrite policy), and prerequisites like authentication. The schema partially compensates for parameter details, but the description alone is not fully complete. It's adequate for basic use but leaves significant gaps for an agent trying to predict behavior.

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 schema descriptions are thorough, covering all 6 parameters with meaning and defaults (100% coverage). The description adds only a high-level grouping of parameters (space, search results, pages) without adding new semantic depth to individual parameters. Per the rubric, when schema coverage is high, the baseline is 3, and here the description doesn't provide sufficient additional value to exceed that.

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: syncing Confluence pages to local markdown files. It distinguishes itself from the sibling getter tools and push_md_to_confluence by explicitly mentioning the download direction and the write-to-local-file aspect. The three sync modes (space, search results, pages) further clarify its 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?

The description provides clear context on when to use the tool: when you need to sync a space, search results, or specific pages. It doesn't explicitly exclude alternatives or mention when not to use it (e.g., 'use get_page_by_id for a single page'), so it falls short of a perfect score, but the guidance is clear enough for a basic understanding.

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