Skip to main content
Glama
naw103

Foremerge

by naw103
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Publish a provisional ChangeSet

publish_changeset

Record a finished unit of implementation for an intent so it can be verified and accepted. Use after committing changes and before running verification.

Instructions

Record a finished unit of implementation for your intent so it can be verified and accepted. Use it once the change is committed in your worktree, after check_conflicts and before run_verification. Foremerge snapshots the worktree (defaulting to your registered one), resolves the candidate commit and its diff base, and stores a fingerprint that verification and acceptance are later checked against. files and symbols are inferred only from uncommitted changes, so list them yourself for committed work. The ChangeSet starts PROVISIONAL and the intent becomes PROVISIONAL. Publishing again while the previous ChangeSet is PROVISIONAL or VALIDATED creates a new one, marks the old one SUPERSEDED, and resets verification. Only the intent's owner may publish, while the intent is CLAIMED, IN_PROGRESS, PROVISIONAL or VALIDATED. Git itself is not modified. Returns the ChangeSet, including its chg_ id, fingerprint, and open_conflicts on the intent at that moment.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
filesNoChanged file paths. Left empty, they are inferred from uncommitted changes only, so list them for committed work.
testsNoTests you ran yourself. Recorded as history only; acceptance relies on run_verification, not on this list.
git_refNoCandidate commit. Omit it: it defaults to the worktree's HEAD, and acceptance rejects any other commit with STALE_CHANGESET.
summaryYesWhat the change does, in one or two sentences.
symbolsNoCode symbols added or changed. Left empty, they are inferred from uncommitted changes only, so list them for committed work.
agent_idYesYour agent id (agt_...). Must own the intent.
base_refNoTrue diff base when known (for example the fork point of this agent branch); defaults to the candidate commit's first parent.
worktreeNoPath of the Git worktree holding the change. Defaults to your registered worktree, then the server's working directory. Must belong to your registered repository.
contractsNoNamed interfaces or agreements this change affects, for example payment-provider.
decisionsNoDesign decisions a reviewer or later agent should know about.
intent_idYesThe intent (int_...) this implementation fulfils.
provenanceNoOptional JSON object of your own context, such as a prompt or task reference. Foremerge adds Git provenance under provenance.git.
dependenciesNoIntent ids (int_...) this change builds on, and the dependency list acceptance enforces. accept_changeset refuses with UNSATISFIED_DEPENDENCY unless each is ACCEPTED or COMMITTED and its accepted commit is in this change's Git history. Intent ids only: not package or library names.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed18 schema fields changedv0.4.3
    • addedInput schema / properties / agent_id / description
      Added value: +"Your agent id (agt_...). Must own the intent."
    • addedInput schema / properties / contracts / description
      Added value: +"Named interfaces or agreements this change affects, for example payment-provider."
    • addedInput schema / properties / decisions / description
      Added value: +"Design decisions a reviewer or later agent should know about."
    • addedInput schema / properties / decisions / items / properties / alternatives / description
      Added value: +"Options you considered and rejected."
    • addedInput schema / properties / decisions / items / properties / rationale / description
      Added value: +"Why you chose it."
    • addedInput schema / properties / decisions / items / properties / title / description
      Added value: +"The decision, for example Use a provider trait."
    • addedInput schema / properties / dependencies / description
      Added value: +"Intent ids (int_...) this change builds on, and the dependency list acceptance enforces. accept_changeset refuses with UNSATISFIED_DEPENDENCY unless each is ACCEPTED or COMMITTED and its accepted commit is in this change's Git history. Intent ids only: not package or library names."
    • addedInput schema / properties / files / description
      Added value: +"Changed file paths. Left empty, they are inferred from uncommitted changes only, so list them for committed work."
    • addedInput schema / properties / git_ref / description
      Added value: +"Candidate commit. Omit it: it defaults to the worktree's HEAD, and acceptance rejects any other commit with STALE_CHANGESET."
    • addedInput schema / properties / intent_id / description
      Added value: +"The intent (int_...) this implementation fulfils."
    • addedInput schema / properties / provenance / description
      Added value: +"Optional JSON object of your own context, such as a prompt or task reference. Foremerge adds Git provenance under provenance.git."
    • addedInput schema / properties / summary / description
      Added value: +"What the change does, in one or two sentences."
    • addedInput schema / properties / symbols / description
      Added value: +"Code symbols added or changed. Left empty, they are inferred from uncommitted changes only, so list them for committed work."
    • addedInput schema / properties / tests / description
      Added value: +"Tests you ran yourself. Recorded as history only; acceptance relies on run_verification, not on this list."
    • addedInput schema / properties / tests / items / properties / command / description
      Added value: +"The command you ran, for example cargo test."
    • addedInput schema / properties / tests / items / properties / status / description
      Added value: +"Its outcome as you observed it, for example passed or failed."
    • addedInput schema / properties / tests / items / properties / summary / description
      Added value: +"Optional short note on what ran or failed."
    • addedInput schema / properties / worktree / description
      Added value: +"Path of the Git worktree holding the change. Defaults to your registered worktree, then the server's working directory. Must belong to your registered repository."
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

The description discloses significant side effects beyond the annotations: it snapshots the worktree, stores a fingerprint, starts the ChangeSet as PROVISIONAL, marks old ChangeSets SUPERSEDED, resets verification, and explicitly notes 'Git itself is not modified.' It also explains the return value, which is important because there is no output schema.

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?

Every sentence carries distinct information: purpose, placement in workflow, snapshot/fingerprint behavior, file/symbol inference, state transitions, republish semantics, authorization constraints, Git safety, and return value. Despite its length, it is front-loaded with the most decision-relevant facts and contains no 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?

The tool has 13 parameters, nested objects, and no output schema, yet the description covers return values, state transitions, side effects, ownership rules, and workflow ordering. Combined with the fully documented input schema, an agent has everything it needs to decide when to call and what to expect.

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%, so the schema already documents all 13 parameters thoroughly. The description adds workflow context around files/symbols inference and defaults, but most of that is also present in the parameter descriptions. This meets the high-coverage baseline without adding substantial new per-parameter meaning.

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 opens with a specific verb and resource: 'Record a finished unit of implementation for your intent so it can be verified and accepted.' It clearly positions the tool in the workflow relative to siblings by saying 'after check_conflicts and before run_verification', leaving no ambiguity about what this tool does or how it differs from adjacent tools.

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 explicit when-to-use guidance: 'once the change is committed in your worktree, after check_conflicts and before run_verification.' It also states preconditions and restrictions: only the intent's owner may publish, and only while the intent is in specific states. This is strong, actionable routing information.

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