Upload Attachment

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

Annotations only provide destructiveHint=true, and the description adds meaningful behavioral detail: existing attachments with the same filename get a new version, and base64 mode is for servers that cannot read host paths. This goes beyond the annotation without contradicting it. It does not discuss side effects like permission requirements or output details, but the output schema and schema parameter descriptions cover some of that.

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-organized, front-loaded with the core statement, and uses a short list for use cases. It is a bit longer than strictly necessary because some use cases restate the obvious purpose, but the length is justified by the two different upload modes and the versioning behavior.

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 moderate complexity, six parameters, and full schema coverage, the description covers the essential decision points: which input form to use, when each is appropriate, and what happens on duplicate filenames. The output schema handles return value clarity. It is complete enough for an agent to invoke the tool correctly.

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 is 3. The description adds value on top by clarifying the mutually exclusive relationship between file_path and content_base64, explaining when each parameter is required, and describing the practical remote-server scenario for base64 use.

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 opens with a specific verb and resource: 'Upload an attachment to Confluence content (page or blog post).' This clearly identifies the action and target, and it is distinct from sibling tools like confluence_upload_attachments by focusing on a single attachment to a single content item.

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 strong usage context: it explains the file_path vs content_base64 distinction, says exactly one must be supplied, and advises base64 for remote or containerized servers. It also notes the useful case of updating existing attachments by creating a new version. It does not explicitly call out alternatives like confluence_upload_attachments for batch operations, so it stops short of full alternative routing.

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