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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing application mechanics (git apply --cached against branch head), branch auto-creation from base_branch, blank-context-line repair, compare-and-swap semantics for expected_head_sha, branch protection/ruleset/secret-scan enforcement, CI/webhook firing, a 2 MiB limit, and required 'repo' scope.

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?

Front-loaded with the core purpose and then packed with high-value detail; nearly every clause earns its place. It is a single dense paragraph with layered parentheticals that reward careful reading but make it slightly harder to scan than a structured list would.

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?

Despite no output schema, the description enumerates the return fields ({branch, commit_sha, parent_sha, files_changed, files, commits, created} plus repair counters), and covers auth scope, size limits, enforcement, and format edge cases — everything an agent needs to invoke it 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?

With 71% schema coverage the schema already documents most params, but the description adds real meaning: the mbox-vs-unified-diff distinction and that message is ignored for mbox, and that all-zeros expected_head_sha means the branch must not exist. It does not restate owner/repo, but those need no elaboration.

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 (commit a patch) plus resource (branch) and immediately distinguishes itself from whole-file writes: 'without sending whole files — the way to change a few lines of a large file.' An agent can tell this apart from write_file or atomic_multi_file_commit without opening any 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 clear context for when this is appropriate ('change a few lines of a large file') and explains the two accepted input formats and when message is required vs ignored. It does not explicitly name the alternative sibling tools (write_file, atomic_multi_file_commit) that an agent should consider instead when replacing entire files.

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