Team drive: refresh

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

Annotations declare it is not read-only, not idempotent and not destructive; the description adds real context beyond that by saying it queues an asynchronous job, that source files remain read-only, and that completion must be polled via job_status. It does not say what happens if called repeatedly on the same drive (relevant given idempotentHint=false), so it falls short of a 5.

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, then the parameter caveat, then the safety and follow-up note. No sentence is redundant.

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?

An output schema exists, so return values need not be explained, and the async job/polling model is covered. The remaining gap is what a reindex job actually affects locally and what the caller should do with the job handle besides polling, but nothing critical to invoking it correctly is missing.

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 carries the burden for the single `force` parameter, and it does explain the specific conditions under which force should be set. It stops short of describing the default incremental behavior in mechanical terms (skipping unchanged files), so the semantics are clear but not complete.

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 ('Queue a local inventory and incremental reindex job') and explicitly routes the agent to the sibling team_drive_job_status for polling, which is the most likely confusion point among the read-only siblings.

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 gives explicit conditions for the only parameter ('Use force only to retry unchanged failures or deliberately rebuild the index'), which is genuine when-to-use guidance. It does not state when to prefer this over sibling operations like team_drive_inspect or team_drive_list, leaving that to inference.

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