upload_work_item_attachment

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

With no annotations, the description carries the burden, and it does disclose the meaningful two-phase behavior (preview by default, actual write only with confirm=true). It stays silent on what preview returns as confirmation, what happens when a file exceeds max_size_mb (default 25), and permission/error behavior for a mutation.

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?

Two sentences, no filler, and the operational instruction (confirm=true to actually upload) is front-loaded right after the purpose statement.

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?

Six parameters with almost no documentation, no annotations, and a mutation path means the definition is under-specified despite the output schema handling return values. An agent can guess at confirm but cannot confidently populate the project/work-item/size parameters from this text.

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 only 17%, so the description must compensate and largely doesn't. Only confirm is explained; file_path, work_item_id, project_id and max_size_mb carry no meaning beyond their names, and work_item_id/file_path defaulting to empty strings is unexplained.

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?

Concrete verb and resource: 'Preview or upload one local file as a Plane attachment' tells the agent exactly what happens and to what. It also distinguishes the two operating modes. It does not differentiate from siblings, but no sibling in the list touches attachments, so confusion risk is low.

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?

'Set confirm=true to upload the file' implies the default call is a dry-run preview, which is usable guidance. However, nothing says when to use project_id versus the active project, or how confirm_project_identifier is meant to interplay with it beyond the schema note.

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