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

Annotations provide no safety hints (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description must carry behavioral context. It discloses the key side effect for main videos (starts transcript, shots, silences analysis) and suggests polling. However, it omits other behaviors such as idempotency (whether calling twice is safe), failure modes, or behavior for non-main video kinds. This is a partial disclosure, not a full one.

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 two sentences with no filler. The primary condition and action are front-loaded, and the side effect and polling instruction follow naturally. Every clause earns its place.

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 main flow (finish upload, start analysis) but leaves many details unaddressed: multipart upload handling (parts, upload_id), the role parameter for clips, the meaning of kind values beyond 'main video', and what happens for non-video kinds. The reference to index_status is helpful but incomplete overall.

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 50%, with several parameters (kind, filename, project_id, storage_key) lacking descriptions. The tool description adds no parameter-level detail, so it doesn't compensate for the missing schema descriptions. For example, it never clarifies that storage_key is the key returned by upload_start, or how kind affects behavior. This leaves agents guessing on required parameters.

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 description clearly states the tool's purpose: 'Finish an upload once every byte is in storage.' It identifies the specific action (finish) and resource (upload), and distinguishes its side effect (starts analysis) from other upload-related tools like upload_start. It also names the follow-up sibling tool (index_status), which helps an agent understand the workflow.

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 gives a clear precondition ('once every byte is in storage') and directs the agent to poll index_status after completion. It implies the tool is used after upload_start and all bytes are stored, but it doesn't explicitly mention alternatives or when not to use it. The context is sufficient for most cases, though it could be more explicit about ordering relative to upload_start.

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