Embed any file from My Drive (video, PDF...)

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses the important side effect: Sites prompts about sharing and this tool answers 'No compartir' by default, leaving sharing untouched. It also clarifies that the sharing change is a consequential external action gated on explicit user consent. It does not cover what happens when the name query matches multiple files, or that a site/insert point must already be open.

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 sentences, front-loaded with the action and the picker context, then the sharing rule with the important constraint capitalized. Every clause carries information; only minor tightening is possible around the parenthetical list of typed variants.

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?

The sharing side effect is well covered, but for a mutation tool with no output schema the description never says what success looks like (whether the file is actually embedded, where it lands, or what is returned), nor the prerequisite state such as an open site and a set insert point. An agent can invoke it, but cannot fully predict the result.

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 50% (query documented, share only an enum with a default), and the description compensates well by explaining what each share value means in practice: 'none' leaves sharing unchanged, 'link_viewer' makes the file viewable by anyone with the link. The query parameter is only characterized as a name match via the schema, so the description adds nothing there, but overall it carries the meaningful semantics for the ambiguous parameter.

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 names a specific verb and resource ("Insert any Drive file by name") and locates it precisely in the UI flow ("the generic Insert > Drive picker"), explicitly distinguishing it from the typed variants that only cover Docs/Slides/Sheets/Forms/Charts/Calendar. The one gap is that the near-duplicate sibling gsites_add_drive_item is never mentioned, so an agent cannot tell from the text which of those two to pick.

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?

It states the default behavior (answers 'No compartir', does not change sharing) and gives an explicit gate for the non-default path: pass share='link_viewer' ONLY when the user explicitly agreed to make the file viewable by anyone with the link. That is a clear when-to-use and when-not-to-use rule with the selecting condition spelled out.

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