drive_file_update_content

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

With no annotations, the description carries the full behavioral burden and delivers: mutation is implied and its in-place semantics are disclosed (ID/link/sharing preserved), plus revision-history behavior for both Google-native formats and binary files, the 30-day/100-revision drop policy, and the keep_revision_forever pin limit of 200. This is exactly the kind of side-effect context an agent needs for a destructive-looking update.

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?

Four sentences, zero filler, and primary purpose front-loaded in the first clause. Each subsequent sentence earns its place: sibling disambiguation, conversion semantics, and retention-policy caveat. The length is justified by the density of non-obvious behavioral information.

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 a mutation tool with 7 parameters, no annotations, and no output schema, this description covers the highest-value context: in-place semantics, the upload alternative, flag behavior, and data-retention caveats. The only real gaps are the lack of a note about the return value/response shape and error conditions (e.g., what happens if file_id doesn't exist or permissions are insufficient). These are minor against the strong coverage of action, selection criteria, and side effects.

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 0%, so the description must compensate. It richly explains the two most confusing flags — convert_to_google_doc (revises native Google formats from Office files) and keep_revision_forever (pins revisions, capped at 200) — which are the parameters whose titles alone would mislead an agent. The remaining params (account, file_id, local_path, name, mime_type) are left to their schema titles, which are mostly self-evident, though name and mime_type could use a hint about whether they are ignored during content updates.

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+resource pair: 'Replace an existing file's contents in place.' It then states concrete identity guarantees (keeps ID, link, sharing) and explicitly distinguishes itself from the sibling drive_file_upload by explaining the upload-alone behavior (creates a second file, does not version). An agent can tell this tool apart from its closest sibling without opening either schema.

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?

Gives an explicit selection rule: 'Use this rather than drive_file_upload to revise something already in Drive,' backed by the reason why uploading again is wrong for revisions. It also clarifies when convert_to_google_doc=True is appropriate (revising native Docs/Sheets/Slides from local Office files). This is direct, unambiguous routing guidance.

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