Upload Multiple Attachments

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

The description discloses important behavioral details beyond the destructiveHint annotation, such as automatic version creation when files with the same names exist and the fact that all files share the same comment/minor_edit settings. This adds useful context for the agent, though it doesn't address potential failures or permission requirements.

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 and efficient: a single sentence states the main action, a second addresses efficiency and versioning behavior, and a concise bulleted list provides use cases. No unnecessary words or repetition.

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?

The description, combined with the rich schema, destructiveHint annotation, and presence of an output schema, gives the agent sufficient context to invoke the tool safely and correctly. It could have included permission requirements or edge-case failure behavior, but for a batch upload tool, the provided context is complete enough.

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 input schema covers all parameters with detailed descriptions, examples, and defaults (100% coverage). The tool description does not add parameter semantics beyond what the schema already provides, so it meets the baseline for schema-covered parameters.

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: 'Upload multiple attachments to Confluence content in a single operation.' It specifies the verb, resource, and scope, and distinguishes itself from the sibling tool 'confluence_upload_attachment' by noting it is more efficient than calling that tool multiple times.

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 explicitly mentions an alternative ('More efficient than calling upload_attachment multiple times') and provides a 'Useful for' list with concrete scenarios. However, it does not explicitly state when to use the singular 'upload_attachment' instead, so it stops short of full when/when-not guidance.

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