Github Commit Files

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

Beyond the annotations (which only declare it is a non-readonly, non-idempotent, non-destructive write), the description discloses that GitHub signs the commit, that the signed mutation takes a single parent, and that merge commits are therefore unsigned. The tree-base rule ('starts from the second parent's, so files carries every file the branch changes as it should read after the merge') is genuinely non-obvious behavioral context. It stops short of stating failure modes such as non-fast-forward rejections or required permissions.

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 core behavior is front-loaded in the first sentence and the merge caveat follows logically. The trailing 'See #547' is an unanchored issue reference that adds no usable meaning to an agent and is the main piece of dead weight.

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 7-parameter mutation tool with an output schema (so return values need no explanation), the description covers the operation, the delete semantics, signing behavior, and merge-tree semantics. An agent has what it needs to construct a correct call for both the normal and merge 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 coverage is 71%, and the description adds real meaning for the trickiest parameter: 'parents' is explained as the head the files were read at plus the commit to merge, and the consequence for the 'files' contents under merge is spelled out. repo_owner, repo_name and message get no added meaning, but those are largely self-evident or already documented.

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 opening sentence gives a specific verb and resource ('Commits text files to a branch') plus the exact semantics of the files map, including null-means-delete. It also carves out a boundary against the sibling github_create_empty_commit by explaining that this tool writes file content while that one creates an empty commit.

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 states the conditions that select the merge path ('A second parent makes a merge commit through the Git Database API') and points the agent at github_get_skill('pr-management') for workflow conventions. It does not explicitly say when to prefer this over direct Git Database API writes via github_api_write, which keeps it short of a 5.

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