upload_attachment

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

The description adds valuable behavior beyond annotations, including the server-side two-step orchestration (bytes upload → token → note creation) and the default note body. But it also makes a false behavioral claim about existing-entry attachment being unsupported, and the sparse annotations leave the description with the burden of accurately describing mutation behavior. This undermines trust despite the useful detail.

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 short, front-loaded, and generally efficient, with no redundant background or fluff. It does contain one misleading sentence about existing-entry attachment, which does not earn its place, but the overall structure is clear and scannable.

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 an 8-parameter tool with no output schema, the description covers the new-note mode in reasonable detail but omits the entire existing-entry attachment mode documented in the schema. It also does not describe what the tool returns after the two-step orchestration. The contradiction with entryId is a significant completeness gap for agent invocation.

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 75%, so the schema already explains most parameters, and the description repeats dataBase64, filename, contentType, and content without adding much new meaning. Worse, it asserts a mutually exclusive constraint ('exactly one of partyId / opportunityId / projectId') that ignores the schema's entryId option, and it omits entryId entirely. This is a negative contribution rather than a compensating one.

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 opening sentence clearly states a specific action: uploading a file as a new note attachment linked to a party, opportunity, or project, which helps distinguish it from add_note and get_attachment. However, the description then claims 'Adding to an existing entry is not supported,' directly contradicting the schema's entryId parameter, which explicitly supports attaching to an existing entry. This makes the stated purpose incomplete and partly misleading.

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 explicit invocation steps: pass dataBase64, filename, contentType, exactly one of partyId/opportunityId/projectId, and optionally content. It does not discuss when to prefer upload_attachment over sibling tools like add_note or update_entry, and the 'exactly one' and 'not supported' statements conflict with the schema's entryId path. The guidance is useful for the main mode but incorrect for a supported alternative.

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