Update project files

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

Annotations already indicate destructive and non-read-only behavior, but the description goes much further: it explains the read-modify-write race in merge mode, the total deletion semantics of replace mode, the mandatory appsscript manifest, rejection before API call if missing, and the lack of automatic retries after 5xx/timeout. It also discloses the naming convention and the fact that the manifest cannot be deleted. No contradiction with annotations exists.

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 dense but every sentence adds essential information: the main effect, the two modes, merge semantics, replace semantics, naming/manifest constraints, return value, and retry behavior. It is front-loaded with the primary purpose and avoids filler or repetition.

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 mutating tool with no output schema, this description covers all critical aspects: the operation, mode behavior, preconditions, constraints, return value, and failure handling. Even though the schema documents each parameter well, the description supplies the missing behavioral context needed to call the tool safely and correctly.

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 100%, so the baseline is 3. The description nevertheless adds operational meaning beyond the schema: it clarifies that files are upserted BY NAME, that delete_files only applies to merge mode, that the manifest is required in replace mode, and that names carry no extension. These are useful execution details directly tied to parameters.

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?

States a specific verb and resource: 'Writes code files to the project's HEAD.' It also clearly differentiates from deployment-related siblings by noting deployed versions remain untouched until a version and deployment are created. The two modes are named and their effects are distinguishable, so an agent knows exactly what operation this tool performs.

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?

Provides concrete usage context for both modes: merge is the default and safer option, replace makes the files the entire project. It also references the appropriate sibling tool for recovery ('check with get_project_content before re-sending') and explains when deployed content changes, connecting to create_version/deployment workflow. This gives explicit when-to-use and when-not-to-use guidance.

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