Upload Link Tool

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

With no annotations, the description carries the full burden and does it well: link is one-time, expires in 30 minutes, max 6 files, max 20 MB per file, and returns both a link and a curl command. These are exactly the constraints an agent cannot discover from the empty annotation set.

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 dense sentences that front-load what the tool returns and the curl command before limits. Parenthetical file lists and multiple clauses make it slightly heavy, but every clause carries real information.

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?

Covers return shape, lifecycle, size/file caps and consent, which is enough for a tool with no output schema and all-optional params. It stops short of explaining how repo, session and project interact when several are supplied, which the agent must piece together from the schema.

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 coverage is 100% and each parameter (repo, task, project, session) is already documented in the schema, including the task-vs-project fallback and session precedence. The description adds no parameter-level detail, so the baseline 3 applies.

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?

States a concrete verb and resource: it 'gives a one-time link to upload files straight onto a task or a project', and names the file kinds and the curl alternative. An agent can tell this apart from add_attachment because the upload happens out-of-band rather than in conversation.

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?

Explicit triggers ('any file larger than a few MB, or a file the person has on their device'), an explicit exclusion ('files do not travel through the conversation as base64'), and a consent gate ('Only when the person asks or agrees'). Nothing about when to prefer this over siblings is left to inference.

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