source_add_drive_file

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

With no annotations, the description carries the behavioral disclosure burden. It discloses async processing, the wait flag, server-side fetch, pointer-error routing, and remote-connector compatibility. It doesn't detail permissions or side effects beyond 'add', but the most critical non-obvious behaviors are clearly stated.

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 dense paragraphs each serve a distinct purpose: definition, routing/alternatives, and input formats plus async behavior. Every sentence adds useful information without redundancy or fluff.

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?

Given the output schema exists, return-value documentation is unnecessary. The description covers tool-specific routing, supported formats, async semantics, wait behavior, and error-confirmation via source_wait/source_list. This is complete for a tool with this complexity.

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 0%, so the description must compensate. It clearly explains that notebook accepts a name or ID, document_id accepts a Drive file ID or share URL in multiple formats, and wait controls blocking behavior. The optional title parameter is not explicitly described, but its purpose is inferable from context.

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 opens with a specific verb and resource: 'Add a Google Drive file by downloading it server-side and uploading it.' It clearly distinguishes this tool from siblings by naming source_add(source_type='drive', mime_type=…) and source_add(source_type='file') as alternatives for different cases.

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 provides explicit when-to-use and when-not-to-use guidance: Google-native Docs/Slides/Sheet should use source_add(source_type='drive', mime_type=…), and local bytes should use source_add(source_type='file'). It also explains when to pass wait=true and how to verify async completion.

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