media.flow.handoff

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

No annotations are provided, so the description carries the full burden of explaining behavior. It says only that the tool 'prepares' a package, without disclosing side effects, whether files or records are created, whether permissions are needed, or what the caller should expect afterward. This is slightly more than a tautology but still far from transparent.

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 short, but brevity here results from omission rather than efficient writing. The vague qualifier 'optional' and the unexplained term 'handoff package' create ambiguity that more detail would resolve, so the description is under-specified rather than appropriately concise.

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 no annotations and no output schema, the description is the only source of context, and it is not enough. It omits the meaning of projectId, the shape or destination of the handoff package, the expected return value, and the relationship to sibling tools, leaving the agent to guess at nearly every operational detail.

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?

The input schema requires projectId but does not define it under properties, and additionalProperties=true leaves the parameter surface open. The description adds no information about what projectId refers to, why it is required, or what optional parameters might be accepted, so an agent cannot confidently construct a valid invocation.

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 identifies a specific action ('Prepare') and a resource ('Google Flow handoff package'), but it does not explain what a handoff package contains or what 'optional' means. It also does not distinguish this tool from the many media.* siblings, leaving the agent to guess how it fits into 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 no guidance about when to call this tool, when not to call it, or which sibling tool should be used instead. The word 'optional' hints that the step is not always required, but it does not state what conditions make it necessary.

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