Skip to main content
Glama

Vault Commit

vault_commit

Commits all unstaged and untracked vault changes in a single commit, flushing batched writes made with commit disabled and sweeping edits from outside hive.

Instructions

Commit every unstaged and untracked change in the vault, in one commit.

Companion to vault_write(commit=False) and vault_patch(commit=False): callers that opt out of per-write commits batch many writes and then flush with a single vault_commit call.

It also sweeps edits made outside hive. A path that already has a staged change is left out and named in the result: it belongs to whoever staged it, often another session sharing the vault. Commit one deliberately with git commit -- <path>.

Returns the new commit SHA on success, a clean-tree notice when there is nothing to commit, or a human-readable error.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "vault_commit"
  }
}

Input Schema

NameRequiredDescriptionDefault
messageNoCommit message. Empty defaults to "vault: batch update". This is the only parameter — there is no `project` argument; the commit spans the whole vault working tree.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.23.0
    • changedInput schema / properties / message / description
      Previous value: -"Commit message. Empty defaults to \"vault: batch update\"."New value: +"Commit message. Empty defaults to \"vault: batch update\".\nThis is the only parameter — there is no `project` argument;\nthe commit spans the whole vault working tree."
  2. Addedv1.21.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only say readOnly=false, idempotent=false, destructive=false; the description goes well beyond by disclosing that it sweeps external edits, that already-staged paths are skipped and reported because another session owns them, and that the outcome is a new SHA, a clean-tree notice, or a human-readable error. That is exactly the mutation-scope and result-shape context annotations cannot convey.

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 operative statement is front-loaded in sentence one, and the remaining paragraphs each add distinct information (batch-companion role, staged-path exclusion, return values). Slightly long for one parameter, but no sentence is filler.

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?

For a mutation tool with an output schema, the description covers scope, side conditions, ownership conflicts, and outcome shapes. An agent has everything needed to decide to call it and to interpret the result without additional context.

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?

Schema coverage is 100% and the single parameter's default is already documented, so the schema carries the load. The description still adds real semantic value by stressing there is no project argument and that the commit spans the whole vault working tree, which prevents a caller from expecting scoped commits.

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 first sentence gives a specific verb (commit) plus the exact scope (every unstaged and untracked change, in one commit). It immediately distinguishes itself from sibling write tools by framing itself as the batch-flush counterpart to vault_write/vault_patch with commit=False.

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 explicitly names the alternative pattern (per-write commits vs. batching then flushing), states when it applies (callers opting out of per-write commits, edits made outside hive), and gives an exclusion plus remediation for staged paths (use `git commit -- <path>` instead). This is when/when-not/alternatives in full.

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