mcp-convention-gate

Overview Schema Source Related Servers Discussions Admin

guarded_commit

Record an already-performed git commit against a gate session, marking it committed and updating the audit log. Use after a successful commit to complete the gate-controlled workflow.

Instructions

AUDIT RECORD ONLY — call this AFTER git commit has already succeeded, never before. It does not perform or authorize the commit: on success it marks the session "committed" in the store, and the git pre-commit hook treats a committed session as used up. Calling this BEFORE running git commit will cause that following commit to be BLOCKED (the hook will see no eligible session). Correct flow: register_gate for every required role -> gate_status to confirm commit_allowed:true -> run the real git commit yourself -> optionally call guarded_commit afterward to log it.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "session_id": "<session_id>",
      "commit_message": "<commit_message>"
    },
    "name": "guarded_commit"
  }
}

Input Schema

Name	Required	Description
`override`	No	Force-record commit even with missing gates (records override in audit log, self-attested — not independently verified). Does NOT bypass the git hook itself — see GATE_BYPASS for that.
`session_id`	Yes	The gate session ID to check
`commit_message`	Yes	The commit message of the commit that was ALREADY made (this call records it, it does not create it)
`override_reason`	No	Reason for override (required if override=true)

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and succeeds fully. It states that the tool does not perform or authorize the commit, that it marks the session as used up in the store, and that the pre-commit hook will block a commit if this is called too early. It also clarifies that the override option is self-attested and does not bypass the git hook, pointing to a separate GATE_BYPASS mechanism. This is excellent behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than usual but every sentence contributes crucial ordering information and behavioral warnings. It is front-loaded with the most important constraint (AUDIT RECORD ONLY, call AFTER commit) and then elaborates logically into the correct flow. No filler words or repetition seen.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a complex tool with subtle misuse consequences, and despite having no output schema and no annotations, the description fully covers purpose, ordering, failure conditions, parameter meanings, and the expected caller behavior. It leaves nothing an agent needs to know to invoke it safely and correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema descriptions already explain each parameter fully (100% coverage), so the baseline is 3. The description adds meaningful context beyond the schema: it emphasizes that commit_message is for the already-made commit, explains the audit/logging semantics of override, and clarifies that override does not bypass the git hook. This adds genuine value to two parameters, so 4 is warranted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states that this tool is for AUDIT RECORD ONLY and describes its exact role: marking a session committed in the store after git commit has succeeded. It distinguishes itself clearly from sibling tools (e.g., it is not gate_status or commit; it logs a completed commit). This leaves no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit precondition ('call this AFTER `git commit` has already succeeded, never before') and explains the exact failure mode if misused (calling before leads to the following commit being BLOCKED). It also provides the correct sequence with sibling tools (register_gate -> gate_status -> actual commit -> guarded_commit). This is precise and actionable.

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

Deploy Server