推送精确提交

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

Annotations provide readOnlyHint=false (mutation), openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds strong behavioral detail: rejects non-fast-forward, forbids force, verifies remote SHA after push. This goes well beyond annotations, adding safety guarantees (reject unexpected advancement, verify post-push SHA). It could mention side-effects more but the safety semantics are clearly disclosed.

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 a single dense sentence. It's efficient with no wasted words, but it packs a lot of concepts (exact SHA, single branch, reject advancement, non-fast-forward, forbid force, verify remote SHA) into one long run-on-style sentence. The information density is appropriate but readability could be improved with clearer structuring.

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?

With 8 parameters, an output schema, and full schema coverage, this is a complex tool (git manipulation with safety guards). The description covers the core contract: what's pushed, what's rejected, what's forbidden, and what's verified. For a push operation with strong safety semantics, this conveys the essential contract. It doesn't describe error behaviors or return values, but the output schema covers returns.

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 100%, so the schema already documents all 8 parameters thoroughly. The description adds 'reject unexpected remote advancement or non-fast-forward state' context that gives meaning to expected_remote_sha (it's a precondition/guard), and 'verify the remote SHA after push' giving meaning to the verification contract. That adds some value, but the schema does the heavy lifting for most 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?

The description states a specific verb+resource ('push exactly one full commit SHA to one named remote branch') and clearly distinguishes from siblings (git_push_only, git_commit, git_finalize) by specifying exact SHA, single branch, fast-forward rejection, forbidding force, and post-push verification. This is precise and differentiates well.

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?

The description implies it is the strictest push variant, rejecting unexpected remote advancement/non-fast-forward states and forbidding force. However, it does not explicitly name alternatives like git_push_only or explain when to use this vs git_prepare_commit/git_finalize in the workflow sequence. Sibling differentiation is implicit rather than explicit.

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