Skip to main content
Glama
naw103

Foremerge

by naw103
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Publish intent

publish_intent

Declare upcoming repository work and affected scopes before editing files to detect conflicts and related active intents for coordination.

Instructions

Announce work you are about to do, and the scopes it will change, before creating or editing any file meant for the repository, documents included. It is the first write for a task you are committed to, after register_agent; while only planning, use check_conflicts, which stores nothing. The intent is stored with status INTENT and compared against every other active intent. Returns the intent (with its int_ id), any conflicts detected immediately, and related_work: active intents, your own others included, that may relate to yours. Entries with asserted: true are collisions with both declared operations stated; the rest are candidates, with why_surfaced saying why. Assess each related_work entry and call record_assessment before changing files, then claim_work and start_work. Use check_conflicts instead for a what-if check that stores nothing.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
taskYesShort name of the task this belongs to, for example payments-provider. Intents with the same task text share one task record.
scopesNoEvery scope this work will touch, each with the operation performed on it. Conflict detection relies on these, so declare them all.
summaryYesWhat you are going to change, in one sentence.
agent_idYesYour agent id (agt_...) from register_agent.
metadataNoOptional JSON object of extra context stored with the intent.
rationaleNoOptional reason for the change.
depends_onNoIntent ids (int_...) this work relies on, recorded for the coordination graph and reported as dependents by query_work. Not checked or enforced: to make acceptance require them, also list them in publish_changeset's dependencies.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv0.4.3
    • addedInput schema / properties / agent_id / description
      Added value: +"Your agent id (agt_...) from register_agent."
    • addedInput schema / properties / depends_on / description
      Added value: +"Intent ids (int_...) this work relies on, recorded for the coordination graph and reported as dependents by query_work. Not checked or enforced: to make acceptance require them, also list them in publish_changeset's dependencies."
    • addedInput schema / properties / metadata / description
      Added value: +"Optional JSON object of extra context stored with the intent."
    • addedInput schema / properties / rationale / description
      Added value: +"Optional reason for the change."
    • addedInput schema / properties / scopes / description
      Added value: +"Every scope this work will touch, each with the operation performed on it. Conflict detection relies on these, so declare them all."
    • addedInput schema / properties / scopes / items / properties / key / description
      Added value: +"The name within that kind, for example PaymentService, POST /orders, or src/billing.rs. Comparison is case-insensitive."
    • addedInput schema / properties / scopes / items / properties / kind / description
      Added value: +"What sort of thing the scope names: a code symbol, an API route, a data schema, a config key, infrastructure, a test, a migration, an environment variable, a file path, a component, a contract, or a broader domain."
    • addedInput schema / properties / summary / description
      Added value: +"What you are going to change, in one sentence."
    • addedInput schema / properties / task / description
      Added value: +"Short name of the task this belongs to, for example payments-provider. Intents with the same task text share one task record."
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only flag readOnly=false, idempotent=false, destructive=false; the description adds substantial context beyond that: the intent is persisted with status INTENT, compared against every other active intent, and returns conflicts plus related_work with the asserted/why_surfaced semantics explained. It also front-loads the ordering constraint (before creating or editing any repository file).

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?

Front-loaded and mostly tight, but the check_conflicts/'stores nothing' contrast is stated twice (once mid-paragraph, once in the closing sentence), which is redundant for a description this dense. Otherwise every sentence earns its place.

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?

With no output schema, the description steps up to describe the return shape (int_ id, immediate conflicts, related_work with asserted and why_surfaced) and the full downstream coordination path. For a 7-parameter, nested-scope tool, an agent has everything needed to call it correctly and act on the result.

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%, so the baseline is 3; the description goes slightly beyond by tying 'the scopes it will change' to the conflict-detection mechanism, explaining why every scope must be declared. It does not add per-field syntax, but the schema already carries that, so the marginal semantics are the value-add.

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?

States a specific verb and resource ('Announce work you are about to do, and the scopes it will change') and names its position in the workflow relative to siblings (after register_agent, distinct from check_conflicts). An agent can distinguish it from claim_work/start_work/check_conflicts without opening schemas.

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?

Gives explicit when-to-use ('the first write for a task you are committed to'), when-not ('while only planning, use check_conflicts, which stores nothing'), and the downstream sequence (record_assessment, then claim_work, then start_work). The alternative tool is named with the condition that selects it.

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