Create or update file

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

The annotations already disclose that this is a non-read-only, open-world, non-destructive operation. The description adds useful behavior beyond that: it creates a commit and requires the current blob SHA for updates. It does not cover branch/new_branch interaction or commit identity details, but it meaningfully extends the safety profile from annotations.

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?

One compact sentence with a focused parenthetical. The create/update distinction is front-loaded and no words are wasted.

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 an 8-parameter write tool with no output schema, the definition covers the core create/update distinction and commit creation. However, it omits important context for branch and new_branch parameters, and does not explain how the commit relates to the target branch. Annotations carry the safety profile, but the tool remains underspecified for branch-related use cases.

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 75%, so most parameters are documented in the schema itself. The description reinforces the SHA requirement for updates, which the schema already explains, but it adds no meaning for the undocumented branch or path parameters. Baseline 3 is appropriate given the mostly covered schema.

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 states a clear verb and resource: create or update a file. It distinguishes the two modes by noting that updating requires the current blob SHA. It stops short of naming sibling alternatives like push_files or delete_file, but the operation itself is unambiguous.

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 the key condition for updating an existing file (SHA required) and implies creation when omitted. However, it gives no guidance on when to prefer this tool over siblings such as push_files, delete_file, or create_branch, leaving alternative selection implicit.

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