upload_video

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

Adds real behavioral detail beyond annotations: automatic downstream processing (transcript, summary, key moments), consumption of the user's recording allowance, and the ingest key requirement. Annotations only cover the generic mutation/openWorld profile, so this is valuable. It does not describe failure modes or size limits.

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?

Four short sentences, zero waste, with the action, return values, and next-step routing front-loaded.

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 what the tool does, what it returns, the side effect (allowance consumption), the auth requirement, and the follow-up tool. No output schema exists, and while the return values are named rather than fully specified, the description is otherwise complete for a 5-param upload tool.

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 80%, so the schema already documents name, path, type, and access. The description adds only that the upload requires a machine-local file path, which the schema already implies. Baseline 3 is appropriate.

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?

Specific verb (upload) + resource (video file) + destination (user's Clipy library) + accepted formats, and states it returns the share link and agent-context link. Easily distinguished from siblings like record or start_recording.

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?

Says processing starts automatically and explicitly routes the agent to wait_for_artifacts as the next call if artifacts are needed. It does not contrast with the alternative of recording directly via start_recording, but the file-source vs live-capture distinction is clear.

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