fix+docs(git): consistent error idiom for git_branch + expanded tool descriptions

[yakuphanycl]

Summary

External MCP audit of src/git/ (using the mcp-audit skill) surfaced one Low and one Info finding. Batched into a single PR per the audit's disclosure SOP §2.

No behavioural change to any tool dispatch path, no schema change, no new dependencies. The mutation tool gating (--repository + validate_repo_path), flag-injection guards, and security tests are untouched.

Findings addressed

F-001 — git_branch error idiom inconsistent with peers (Low)

Severity rubric: ERR-002 — mixed raise vs in-band string across surface.

git_branch returned f\"Invalid branch type: {branch_type}\" (a normal-looking string) on invalid input, while every other helper in the module raises (git_diff, git_checkout, git_show, git_create_branch, git_log all use raise BadName/ValueError). The string return reaches the MCP client masquerading as a successful tool result.

Fix: change to raise ValueError(...) with a message that names the valid options ('local', 'remote', 'all'). Added test_git_branch_rejects_invalid_branch_type in the same style as the existing flag-injection guard tests.

F-003 — In-code Tool() descriptions lack when-to-use + return-shape (Info, surface-wide)

Severity rubric: DISC-002 + DISC-004 — discoverability axis, applied surface-wide.

All 12 in-code descriptions in @server.list_tools() were concise WHAT-statements (e.g., "Shows the working tree status", "Switches branches"). The README has more detail, but agents reading the MCP tool surface only see the in-code description.

Fix: rewrote all 12 descriptions to follow a consistent shape:

• WHAT (preserved from the existing description)
• when-to-use (one short clause)
• return-shape hint (text / list of commit entries / unified diff / etc.)

For tools with flag-injection guards (git_diff, git_checkout, git_show), the description now mentions that refs starting with - are rejected — the existing safety guarantee is now discoverable from the tool surface, not only from reading the source.

Findings deferred

F-002 — No MCP-layer dispatch test (Low, deferred)

The existing tests exercise the helper functions (git_status, git_commit, …) directly. None round-trip through the @server.call_tool() dispatcher with (name, arguments) to verify the match cases and the TextContent wrapping. This is a real coverage gap, but adding async dispatch fixtures is a separate scope worth its own PR — flagged in the audit's next-session backlog rather than batched here.

Test plan

• All 12 helper tests still pass after description rewrites (descriptions are not asserted in tests, but ran the full suite locally).
• New test test_git_branch_rejects_invalid_branch_type passes.
• On Windows the existing test_repository fixture has a pre-existing shutil.rmtree flake (PermissionError: WinError 32); test bodies pass, only fixture teardown errors. Unrelated to this PR — Linux CI will be clean.
• Maintainer review of description wording — open to tightening if too verbose.

Audit reference

• Severity rubric and disclosure SOP applied: yakuphanycl/wrg-skills
• Audit case-study (pending publication on the auditor's side): wrg-skills/docs/case-studies/git-mcp-2026-04-26.md

🤖 Generated with Claude Code