create_confluence_page

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose that content accepts Markdown or XHTML, which is useful, but it omits the fact that this is a write/mutation operation with side effects, any permission requirements, behavior on duplicate titles, and whether format is auto-detected. A create tool with zero annotation coverage needs more 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?

Two sentences with zero waste. The first sentence front-loads the core action and resource type, and the second adds non-redundant format information that directly affects how content should be authored. 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?

For a creation tool with no output schema and no annotations, the description should disclose what the tool returns (typically the new page ID, which is essential for follow-up operations like upload_confluence_attachment or add_confluence_page_label). It also omits how the Markdown vs XHTML format is determined and any error behavior. The schema covers parameters fully, but the behavioral and return-value gaps make this incomplete for a mutation tool that starts most Confluence workflows.

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 of 3 applies. The description adds marginal value by noting content accepts Markdown or XHTML, which aligns with the content parameter and an implied auto-detection behavior. It does not add meaning for spaceKey, title, parentId, or type, but those are already well documented in 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?

States a specific verb and resource: 'Creates a new page or blog post in a Confluence space.' The create action is unambiguous and clearly distinguished from siblings like read_confluence_page, update_confluence_page, and search_confluence_pages. It doesn't explicitly name a differentiating sibling, but the 'new' plus 'creates' wording leaves little doubt about its role.

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 is provided on when to use this tool versus alternatives. With 39 siblings including update_confluence_page, add_confluence_comment, and upload_confluence_attachment, the description should state, for example, that this is for creating new content while update_confluence_page handles modifications. The usage context is only implied by the verb 'creates.'

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