op_add_document_attachment

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

The description adds meaningful behavioral context beyond the annotations: it discloses the required API permission, the base64 encoding requirement for content, and the instance-level size limit retrieved from /api/v3/configuration. These details help the agent anticipate constraints and failure conditions. It does not contradict the annotations, which already signal a non-read-only, non-idempotent operation.

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 concise and front-loaded with the core action, followed by permission and payload details. Every sentence contributes useful operational information, though the phrase 'content is the file bytes as base64' partially duplicates the schema description. Overall, it is efficient without being bloated.

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 tool with no output schema, the description covers the key prerequisites: required permission, encoding of the file content, and the size limit. The input schema handles parameter requirements and defaults. The main gap is that it does not describe the expected response or error behavior, but this is not critical given the schema and annotations.

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 schema already documents all parameters. The description restates that content is base64 and adds the size cap, but it does not provide substantial new meaning for id, fileName, or contentType beyond what the schema already says. This meets the baseline but does not rise above it.

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 a file to a document.' This clearly identifies the action and target, and it is distinct from sibling tools like op_get_document and op_update_document, which describe different operations on documents. No ambiguity about what this tool does.

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 provides useful operational context, such as requiring the manage_documents permission and the attachment size cap. However, it does not explicitly state when to use this tool versus any alternative, nor does it mention exclusions or fallback options. Usage is implied by the tool's name and purpose rather than explicitly guided.

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