Skip to main content
Glama
MongLong0214

CommitLore

by MongLong0214
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

commitlore_prepare_capture

Prepares a capture transaction: binds the current repository state and transcript, generates a prompt contract, and persists a pending record for later verification and staging.

Instructions

Prepare a capture transaction: computes binding conditions (HEAD, staged diff, tree, policy hash), generates the prompt contract for the agent to use, and persists a phase:"prepared" pending transaction. Returns the nonce needed for verify and stage. The prompt carries the end of the transcript rather than all of it; transcript_window says which lines, numbered as the whole transcript numbers them. Verification still reads the whole transcript, so quote only what the prompt shows you. The transaction binds to THIS server's checkout, returned as repository; if your working directory is a linked worktree or another clone, pass repository to assert it and this refuses rather than binding to the wrong HEAD.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
repositoryNoyour own working directory, asserted. This server is registered against one checkout and binds every transaction to it; if you are in a linked worktree or another clone, pass this and the call refuses instead of binding to a tree you never touched. It cannot change the binding, only assert it. Omit to accept this server's repository, which is returned as `repository`
transcriptYesthe session transcript to compute source hashes from
unattendedNodeclare this capture unattended: nobody was asked before staging. Refused unless the repository opted in (.commitlore-policy.json: "unattended": true, mode "auto")

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.5.0
    • addedInput schema / properties / repository
      Added value: +{
+  "description": "your own working directory, asserted. This server is registered against one checkout and binds every transaction to it; if you are in a linked worktree or another clone, pass this and the call refuses instead of binding to a tree you never touched. It cannot change the binding, only assert it. Omit to accept this server's repository, which is returned as `repository`",
+  "type": "string"
+}
  2. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the annotations, the description reveals substantial behavior: it persists a phase:'prepared' pending transaction, computes binding conditions, returns only the end of the transcript in the prompt, notes that verification still reads the whole transcript, and refuses to bind when the repository assertion fails. None of this contradicts the annotations, and the readOnlyHint=false is consistent with the described persistence.

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

Conciseness5/5

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

The description is dense but every sentence earns its place: purpose and output are front-loaded, followed by critical quoting guidance and binding behavior. There is no filler or repetition of schema details.

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

Completeness4/5

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

For a complex tool with no output schema, the description covers the essential return values (`nonce`, `repository`, `transcript_window`), the persistence side effect, the transcript quoting rule, and the refusal behavior. It does not enumerate the complete shape of the returned prompt contract or all possible error cases, but it provides enough context to call the tool effectively.

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

Parameters3/5

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

Schema description coverage is 100%, and the schema already explains each parameter meaningfully, especially `repository` and `unattended`. The description adds workflow context around the transcript and repository assertion, but it does not add substantial parameter-level semantics beyond the schema, so the baseline score of 3 is appropriate.

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 names a specific verb and resource: 'Prepare a capture transaction' and details the concrete outputs (binding conditions, prompt contract, pending transaction, nonce). It also distinguishes this step from the sibling tools by explicitly relating the nonce to 'verify and stage', so an agent can tell it apart from commitlore_stage_capture and commitlore_verify_capture.

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

Usage Guidelines4/5

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

The description gives clear workflow context: this prepares the transaction and returns the nonce needed for later verify and stage steps. It also includes a conditional usage rule for passing `repository` when working from a linked worktree or another clone. It does not explicitly enumerate when not to use the tool versus each sibling, but the phase workflow is clear enough.

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

Deploy Server

Other Tools