upload_media

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the write-locality profile is covered. The description adds genuinely non-obvious behavior: a 20 GiB ceiling, a closed set of accepted formats, and content-addressed dedupe where re-uploading identical media returns the existing path (idempotency semantics). It does not say what happens on format/size rejection or whether uploads can be undone, which keeps it from a 5.

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?

Three short sentences, front-loaded with what the tool does and its return value, then the acceptance constraints, then dedupe semantics. No sentence is redundant and constraints are grouped where an agent would look for them.

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?

With one parameter, an output schema present, and annotations covering safety, the remaining burden is behavioral, and the description covers formats, size limit, dedupe, and downstream use. The only material omission is the failure path for oversize or unsupported files, which is a minor gap given the output 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 description coverage is 0% for the single required parameter local_path, so the description must carry the meaning. It partially compensates by implying the file lives on the Mac and constraining the media types that the pointed-to file may be, but never clarifies whether the path must be absolute, supports ~ expansion, or may point to a non-media file.

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?

"Stream a Mac image/video to private workstation storage and return its remote path" gives a concrete verb (stream/upload), a concrete resource (image/video media), a destination (private workstation storage), and a result (remote path). This is easily separable from siblings such as inspect_media, normalize_media, and download_artifact, which operate on already-stored media rather than ingesting it.

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?

"Use this path in other tools" states the downstream purpose clearly, telling the agent this is the ingestion step that produces a handle for later calls. It stops short of explicit routing guidance — it does not say when NOT to use it (e.g., for already-remote URLs) or name a specific alternative sibling.

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