Skip to main content
Glama

propose_update

Propose a fix, addition, or new knowledge document as a git branch and pull request for human review. Served content stays unchanged until a reviewer merges the change.

Instructions

Propose a change to a knowledge document — fix an outdated rule, add a missing decision, create a document — for humans to review. Commits the complete new file to a git branch briefd/proposal- (and opens a pull request when a forge is configured); returns branch, commit and PR URL. Never changes what briefd serves until a human merges. Use it for knowledge that is wrong, stale ('code changed since' in bundles) or missing, not for scratch notes. To edit an existing document, call get_document, change its source and send the whole result with base_content_hash set to its content_hash; the call is refused if the file changed in the meantime or if the new content drops the front matter. Fails without a writable git source.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "doc_path": "<doc_path>",
      "change_description": "<change_description>",
      "new_content": "<new_content>"
    },
    "name": "propose_update"
  }
}

Input Schema

NameRequiredDescriptionDefault
doc_pathYesRepository-relative path of the document to change or create, inside a scope folder, e.g. domain/rules/refunds.md or projects/ledger-service/notes.md. Must end in .md.
new_contentYesThe complete new content of the file as Markdown, including front matter if the document has any — not a diff or a fragment. When editing, start from the source field of get_document (content lacks the front matter and the title).
base_content_hashNoThe content_hash get_document returned for the version you edited. The proposal is refused if the file has changed since. Send an empty string when creating a new file (refused if it already exists). Omit only if you did not read the document first.
change_descriptionYesWhy this change is needed and what evidence you have, written for the human reviewer (becomes the commit message and pull request description).

Output Schema

NameRequiredDescriptionDefault
branchYes
commitYes
pr_urlNo
pushedYes
proposal_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.9.1
    • addedInput schema / properties / base_content_hash
      Added value: +{
      +  "description": "The content_hash get_document returned for the version you edited. The proposal is refused if the file has changed since. Send an empty string when creating a new file (refused if it already exists). Omit only if you did not read the document first.",
      +  "type": [
      +    "null",
      +    "string"
      +  ]
      +}
    • changedInput schema / properties / new_content / description
      Previous value: -"The complete new content of the file as Markdown, including front matter if the document has any — not a diff or a fragment. Fetch the current content with get_document first when editing."New value: +"The complete new content of the file as Markdown, including front matter if the document has any — not a diff or a fragment. When editing, start from the source field of get_document (content lacks the front matter and the title)."
  2. Changed3 schema fields changedv0.5.0
    • changedInput schema / properties / change_description / description
      Previous value: -"Why this change is needed, for the reviewer (becomes the commit/PR description)"New value: +"Why this change is needed and what evidence you have, written for the human reviewer (becomes the commit message and pull request description)."
    • changedInput schema / properties / doc_path / description
      Previous value: -"Repository-relative path of the document to change or create, e.g. domain/rules/refunds.md"New value: +"Repository-relative path of the document to change or create, inside a scope folder, e.g. domain/rules/refunds.md or projects/ledger-service/notes.md. Must end in .md."
    • changedInput schema / properties / new_content / description
      Previous value: -"The complete new content of the file (Markdown, including front matter if any)"New value: +"The complete new content of the file as Markdown, including front matter if the document has any — not a diff or a fragment. Fetch the current content with get_document first when editing."
  3. First observedv0.4.0

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the thin annotations (readOnlyHint=false, idempotentHint=false), it discloses the hardware-level effects: a branch named briefd/proposal-<id>, a commit, an optional pull request, and the critical safety property that served content never changes until a human merges. It also documents the refusal conditions (file changed since read, front matter dropped, new file already exists), which annotations cannot express.

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?

Well front-loaded: purpose, then side effects, then safety guarantee, then usage rule, then the edit workflow. It is dense but earns most of its length; the long dash-joined sentences and repeated restatement of the content_hash refusal across description and schema cost a bit of readability.

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 spanning git, hashing and optional forge integration, it covers prerequisites, validation failures, reversibility (nothing changes until merge), and the return payload (branch, commit, PR URL) — the latter reinforced by an output schema. An agent has everything needed to call it correctly or to know when it cannot.

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

Parameters5/5

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

Schema coverage is 100%, so the baseline is already met, but the description adds real procedural meaning on top: it explains how base_content_hash must be sourced from get_document's content_hash and why, and clarifies that new_content must be the whole file rather than a diff. That sequencing guidance is not derivable from the per-parameter text alone.

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 ("Propose a change to a knowledge document") with the concrete effects spelled out (git branch commit, optional PR). It also enumerates the change types (fix outdated rule, add missing decision, create document), making it clearly distinct from the read-oriented siblings like get_document and search_context.

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 an explicit inclusion rule ("knowledge that is wrong, stale ... or missing") and an explicit exclusion ("not for scratch notes"). It also names the required alternative workflow — call get_document first, then send the source with base_content_hash — and states a blocking prerequisite ("Fails without a writable git source").

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