Upload an attachment

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

Beyond the annotations, the description discloses that the upload goes to temporary storage, that file bytes come from the MCP file input rather than a filesystem path, and that the operation may notify recipients or change tenant data. These traits align with destructiveHint=true and add meaningful behavioral context beyond the boolean hints.

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 compact and front-loaded: the action, endpoint, and core usage are stated in the first sentence, followed by the key input detail, required confirmation, and side-effect warning. Every sentence earns its place without unnecessary filler.

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 mutation with no output schema, the description covers the essential invocation details: endpoint, multipart upload, temporary storage, how bytes are supplied, required confirm=true, and the write opt-in. It also explains that the returned path is used for later attachment, which is the main postcondition an agent needs to know.

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 description adds important meaning beyond the schema by explaining that the file is supplied through the MCP file input and that the underlying multipart body uses file and fileName. It does not fully explain how the upload.name/contentBase64 fields map to the request or describe the query/fields objects, but it compensates for the schema's moderate coverage.

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 names the specific verb and resource ('Upload an attachment'), gives the REST endpoint, and clarifies that it uploads to temporary storage for later use with an event or scenario. This distinguishes it from related upload tools like xmatters_upload_attachment_to_a_scenario, which attach directly to a scenario.

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?

It clearly states when to use the tool: to get a returned path for attaching to an event or scenario. It does not explicitly name sibling alternatives or say when not to use them, so it lacks an explicit exclusion, but the context is otherwise clear.

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