guarded_commit

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.

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.

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.

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.

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.

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.