Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
This server exhibits significant definition quality gaps. While all 7 tools are explicitly registered with the @mcp.tool() decorator in src/confluence/tools.py, the implementations lack critical schema documentation, parameter descriptions are minimal or missing, and error handling is incomplete. Tool names follow verb_noun convention (positive), but parameter schemas are not visible in the provided source code, and descriptions are generic. The server does not implement input validation, output schema documentation, or structured error guidance. These deficiencies force LLMs to guess parameter meanings and recovery paths.
No visible JSON Schema input parameter definitions. Tools are registered with @mcp.tool() decorator but parameter schemas are not explicitly documented in the visible source. Function signatures show Python type hints but not structured JSON Schema with constraints, descriptions, or enumeration values.
Parameter descriptions are missing. Function signatures include type hints but no descriptions of what each parameter controls, expected format, or constraints. For example, 'page_id' appears in multiple tools but is never explained as a Confluence page ID string, UUID, or integer.
Write comprehensive parameter descriptions for all tools. Each parameter should include: (1) what it controls, (2) expected format (string, UUID, date, enum values), (3) constraints (length, regex pattern, allowed values), (4) whether it is required or optional, (5) default value if applicable. Example: 'space_key (optional): The Confluence space key to limit search scope. Format: 2-10 uppercase letters (e.g., MYSPACE). Defaults to server-configured space.'
Expand tool descriptions to 50-200 characters and include: (1) what the tool does, (2) when to use it instead of related tools, (3) what it returns (with field names if structured), (4) any side effects or prerequisites. Example for confluence_get_page_info: 'Retrieve metadata and content for a specific Confluence page. Use this to get page title, author, creation date, and body content before downloading attachments. Returns a page object with id, title, version, body.storage, and created/updated timestamps.'
Document output schemas explicitly. For each tool, add a structured definition of the return type, including field names, types, and what each field represents. Example: 'Returns: {"page_id": string, "title": string, "space_key": string, "created": ISO 8601 date, "author": {"username": string, "email": string}, "attachments": [{"id": string, "title": string, "size": integer}]}'
Add input validation and error messages. Before calling the Confluence API, validate parameters (e.g., page_id format, space_key uppercase). Return clear, actionable error messages with the invalid value and valid constraints. Example: 'Invalid space_key: "myspace". Must be 2-10 uppercase letters. Available spaces: PROJ, MYSPACE, DOCS.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Tool descriptions are too brief and generic. Most are under 50 characters and lack actionable guidance. For example, 'Get information about a specific Confluence page' (37 chars) does not explain what information is returned, when to use it vs. confluence_get_page_attachments, or what preprocessing occurs (e.g., expand='body.storage').
Output schemas are not documented. Return types in code are Dict[str, Any] or List[Dict[str, Any]], but the structure of these dictionaries is not documented. LLMs cannot infer what fields are present, which ones are IDs for chaining to other tools, or how to parse success vs. error responses.
Error handling is minimal and non-actionable. Error responses return dicts like {'error': str(e)} or {'error': 'Confluence client not configured'} with no guidance on recovery. Errors should include specific, actionable next steps (e.g., 'Client not configured. Provide CONFLUENCE_URL, CONFLUENCE_USERNAME, CONFLUENCE_API_TOKEN in environment.').
No input validation or constraint documentation. Parameters like 'space_key' and 'page_id' have no documented format, length limits, or allowed values. LLMs have no way to know if they should pass 'MYSPACE' vs 'myspace' vs 'My Space', or what length is valid.
Destructive operations lack confirmation or dry-run capability. confluence_download_attachment and confluence_download_all_attachments write files to disk with potential for overwrite or data loss, but there is no dry-run or confirmation step to prevent accidental execution.
Tool composition issue: confluence_download_attachment requires 'attachment_title' as a parameter, but there is no indication of how an LLM discovers available attachment titles without first calling confluence_get_page_attachments. Tool descriptions do not guide this multi-step planning.
Missing pagination and result limits. confluence_search_pages_by_title uses limit=10 in code but this is not documented in the tool description or exposed as a configurable parameter. confluence_get_page_attachments and confluence_list_downloaded_files have no documented limits, risking context window exhaustion.
No tool annotations. Tools lack readOnlyHint, destructiveHint, and idempotentHint annotations. confluence_download_attachment and confluence_download_all_attachments are clearly destructive (write to disk) but are not marked as such. This information is critical for agent planning.
Implement tool annotations: Add destructiveHint: true to confluence_download_attachment and confluence_download_all_attachments; add readOnlyHint: true to all GET/search tools; add idempotentHint: true where applicable (e.g., confluence_get_page_info is idempotent).
Add recovery guidance to all error paths. Instead of 'Confluence client not configured', return: 'Confluence client not configured. Ensure environment variables are set: CONFLUENCE_URL (e.g., https://your-domain.atlassian.net), CONFLUENCE_USERNAME (your email), CONFLUENCE_API_TOKEN (generated from Account Settings > Security > API tokens). For details, see https://confluence.atlassian.com/cloud/api-tokens-938839638.html'
Document parameter dependencies and mutual exclusivity. Example: 'filename is optional. If omitted, the attachment's original title is used. If provided, it must include a file extension (e.g., report.pdf).'
Add pagination parameters to tools that return lists. confluence_search_pages_by_title should expose limit (default 10, max 100) and offset/start parameters. confluence_get_page_attachments should also support pagination. Include total_count and next_offset in responses.
Provide discovery guidance in tool descriptions. For confluence_download_attachment, add: 'To find available attachments, first call confluence_get_page_attachments(page_id) to see titles, then pass the desired title to this tool.'
Add a confirm/dry-run parameter to destructive tools. confluence_download_attachment and confluence_download_all_attachments should support dry_run: bool parameter that returns what would be downloaded without actually writing files.
Include chaining IDs in responses. If confluence_search_pages_by_title returns search results, ensure each result includes page_id so it can be immediately passed to confluence_get_page_attachments without a separate lookup.
Document file storage and retrieval semantics. Clarify where confluence_download_attachment and confluence_download_all_attachments write files (local filesystem, temp directory?), how confluence_read_attachment_content locates those files, and how confluence_list_downloaded_files enumerates them.