Skip to main content
Glama

Update ADR Section

update_section

Replace or delete a whole section in an ADR body field by specifying the record ID, field key, and new value.

Instructions

Whole-section replace/delete of one AdrBody field.

Input Schema

NameRequiredDescriptionDefault
idYes
keyYes
valueYes

Output Schema

NameRequiredDescriptionDefault
bodyYes
frontmatterYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.37.0
    • changedOutput schema / $defs / AdrBody / description
      Previous value: -"The ADR body: whole-section fields (plan §4) plus the dynamic\n``Option`` collection that backs the derived ``## Pros and Cons of the\nOptions`` section (plan §5).\n\nEach whole-section field maps 1:1 to the ``key`` values the future\n``update_section(key, value)`` MCP tool accepts (plan §4's table),\nusing this model's snake_case attribute names rather than the table's\ncamelCase key strings -- the tool layer, not this model, is responsible\nfor translating between the two.\n\nMandatory fields (``title``, ``context_and_problem_statement``,\n``considered_options``, ``decision_outcome``) must be non-blank; this\nmirrors plan §4's rule that ``update_section`` must reject a deletion\nsentinel targeting a mandatory section rather than write it. Optional\nfields (``decision_drivers``, ``consequences``, ``confirmation``,\n``more_information``) normalize a blank/whitespace-only value to\n``None``, i.e. \"absent\", consistent with the render-time rule that an\nabsent optional section omits its heading entirely.\n\nParameters\n----------\ntitle:\n    The ``# {title}`` H1. Mandatory.\ncontext_and_problem_statement:\n    ``## Context and Problem Statement``. Mandatory.\ndecision_drivers:\n    ``## Decision Drivers``. Optional.\nconsidered_options:\n    ``## Considered Options``. Mandatory. Kept fully independent from\n    ``options`` below -- no consistency check is enforced between them\n    (plan §4).\ndecision_outcome:\n    ``## Decision Outcome`` text before any H3. Mandatory.\nconsequences:\n    ``### Consequences`` under Decision Outcome. Optional.\nconfirmation:\n    ``### Confirmation`` under Decision Outcome. Optional.\noptions:\n    The dynamic ``### Option N: {title}`` collection. Backs the derived\n    ``## Pros and Cons of the Options`` section, which is rendered iff\n    this list is non-empty (plan §5). Defaults to an empty list.\nmore_information:\n    ``## More Information``, always last. Optional."New value: +"The ADR body: whole-section fields plus the dynamic\n``Option`` collection that backs the derived ``## Pros and Cons of the\nOptions`` section.\n\nEach whole-section field maps 1:1 to the ``key`` values the\n``update_section(key, value)`` MCP tool accepts,\nusing this model's snake_case attribute names rather than\ncamelCase key strings -- the tool layer, not this model, is responsible\nfor translating between the two.\n\nMandatory fields (``title``, ``context_and_problem_statement``,\n``considered_options``, ``decision_outcome``) must be non-blank; this\nmirrors the rule that ``update_section`` must reject a deletion\nsentinel targeting a mandatory section rather than write it. Optional\nfields (``decision_drivers``, ``consequences``, ``confirmation``,\n``more_information``) normalize a blank/whitespace-only value to\n``None``, i.e. \"absent\", consistent with the render-time rule that an\nabsent optional section omits its heading entirely.\n\nParameters\n----------\ntitle:\n    The ``# {title}`` H1. Mandatory.\ncontext_and_problem_statement:\n    ``## Context and Problem Statement``. Mandatory.\ndecision_drivers:\n    ``## Decision Drivers``. Optional.\nconsidered_options:\n    ``## Considered Options``. Mandatory. Kept fully independent from\n    ``options`` below -- no consistency check is enforced between them.\ndecision_outcome:\n    ``## Decision Outcome`` text before any H3. Mandatory.\nconsequences:\n    ``### Consequences`` under Decision Outcome. Optional.\nconfirmation:\n    ``### Confirmation`` under Decision Outcome. Optional.\noptions:\n    The dynamic ``### Option N: {title}`` collection. Backs the derived\n    ``## Pros and Cons of the Options`` section, which is rendered iff\n    this list is non-empty. Defaults to an empty list.\nmore_information:\n    ``## More Information``, always last. Optional."
    • changedOutput schema / $defs / AdrFrontmatter / description
      Previous value: -"The ADR YAML frontmatter block.\n\nUpdate contract: whole object, full replace only (plan §3) -- there is\nno partial-update or deletion-sentinel mechanism for frontmatter; omit a\nkey from the submitted object to drop it.\n\nParameters\n----------\nid:\n    The specmgr-assigned document identifier (a server-generated UUID\n    string), used to resolve ``id -> file path`` (plan §9a). This is a\n    specmgr-only extension key, not part of the MADR 4.0.0 standard --\n    assigned once by ``create_adr`` and never reassigned. Optional\n    (``str | None = None``, default ``None``), the same non-breaking-\n    addition pattern used for ``version`` below, so existing/hand-\n    authored files without an ``id`` still parse successfully; they are\n    just not addressable via id-based tools until one is assigned.\nversion:\n    The specmgr schema major.minor.patch version this document was\n    written with (plan §6). This is a specmgr-only extension key, not\n    part of the MADR 4.0.0 standard -- it is kept alongside the\n    MADR-defined keys below purely so it round-trips through the\n    parse/render pipeline (plan §7) and lets a future parser dispatch\n    an on-disk file to the ``models/adr/vN`` package that understands\n    it, or recognize a document still on an older major version.\n    Defaults to :data:`CURRENT_SCHEMA_VERSION`. Must share this\n    package's major component -- ``models.adr.v1.AdrFrontmatter`` never\n    accepts a ``\"2.x.x\"`` value.\nstatus:\n    Either one of ``\"draft\"``, ``\"proposed\"``, ``\"rejected\"``,\n    ``\"accepted\"``, ``\"deprecated\"``, ``\"superseded\"``, or a string\n    matching ``^superseded by .+$``. Defaults to ``\"draft\"`` -- both\n    when the key is absent entirely and when it is present but blank\n    (e.g. MADR's bare-bones template ships a placeholder ``status:``\n    with nothing after the colon, which YAML parses as ``None``, not\n    an absent key).\ndate:\n    Free-form date the decision was last updated (MADR uses\n    ``YYYY-MM-DD``, not enforced here since the ``.md`` file is the\n    source of truth). Optional.\ndecision_makers:\n    Free-form list of everyone involved in the decision, as written in\n    the frontmatter (YAML key ``decision-makers``). Optional. Accepts\n    either the literal hyphenated YAML key or the snake_case field name\n    (``validation_alias``, not ``alias``, so static type checkers keep\n    seeing ``decision_makers`` as the constructor parameter name -- see\n    ``tests/models/adr/v1/test_frontmatter.py`` for both call shapes).\nconsulted:\n    Free-form list of subject-matter experts consulted. Optional.\ninformed:\n    Free-form list of people kept up to date on progress. Optional."New value: +"The ADR YAML frontmatter block.\n\nUpdate contract: whole object, full replace only -- there is\nno partial-update or deletion-sentinel mechanism for frontmatter; omit a\nkey from the submitted object to drop it.\n\nParameters\n----------\nid:\n    The specmgr-assigned document identifier (a server-generated UUID\n    string), used to resolve ``id -> file path``. This is a\n    specmgr-only extension key, not part of the MADR 4.0.0 standard --\n    assigned once by ``create_adr`` and never reassigned. Optional\n    (``str | None = None``, default ``None``), the same non-breaking-\n    addition pattern used for ``version`` below, so existing/hand-\n    authored files without an ``id`` still parse successfully; they are\n    just not addressable via id-based tools until one is assigned.\nversion:\n    The specmgr schema major.minor.patch version this document was\n    written with. This is a specmgr-only extension key, not\n    part of the MADR 4.0.0 standard -- it is kept alongside the\n    MADR-defined keys below purely so it round-trips through the\n    parse/render pipeline and lets a future parser dispatch\n    an on-disk file to the ``models/adr/vN`` package that understands\n    it, or recognize a document still on an older major version.\n    Defaults to :data:`CURRENT_SCHEMA_VERSION`. Must share this\n    package's major component -- ``models.adr.v1.AdrFrontmatter`` never\n    accepts a ``\"2.x.x\"`` value.\nstatus:\n    Either one of ``\"draft\"``, ``\"proposed\"``, ``\"rejected\"``,\n    ``\"accepted\"``, ``\"deprecated\"``, ``\"superseded\"``, or a string\n    matching ``^superseded by .+$``. Defaults to ``\"draft\"`` -- both\n    when the key is absent entirely and when it is present but blank\n    (e.g. MADR's bare-bones template ships a placeholder ``status:``\n    with nothing after the colon, which YAML parses as ``None``, not\n    an absent key).\ndate:\n    Free-form date the decision was last updated (MADR uses\n    ``YYYY-MM-DD``, not enforced here since the ``.md`` file is the\n    source of truth). Optional.\ndecision_makers:\n    Free-form list of everyone involved in the decision, as written in\n    the frontmatter (YAML key ``decision-makers``). Optional. Accepts\n    either the literal hyphenated YAML key or the snake_case field name\n    (``validation_alias``, not ``alias``, so static type checkers keep\n    seeing ``decision_makers`` as the constructor parameter name -- see\n    ``tests/models/adr/v1/test_frontmatter.py`` for both call shapes).\nconsulted:\n    Free-form list of subject-matter experts consulted. Optional.\ninformed:\n    Free-form list of people kept up to date on progress. Optional."
    • changedOutput schema / $defs / AdrOption / description
      Previous value: -"One entry of the dynamic ``## Pros and Cons of the Options`` collection.\n\nRendered as ``### Option {number}: {partial_title}``. Options are never\nindividually mandatory -- zero options is a valid ADR state -- and the\nwhole-section deletion sentinel from plan §4 does not apply to them;\nremoval only ever happens through the dedicated ``option_delete`` tool\n(plan §5, §8), not by submitting a blank/``\"REMOVE\"`` value here.\n\nParameters\n----------\nnumber:\n    Monotonically increasing, unpadded, never-reused counter assigned at\n    creation time. Deleting an option leaves a gap; remaining options are\n    neither renumbered nor reordered.\npartial_title:\n    The ``{title}`` portion after ``\"Option {number}: \"``. Must be\n    non-blank and single-line (no embedded line breaks).\ncontent:\n    Opaque markdown blob for the option's body (no enforced\n    Good/Bad/Neutral structure). May be empty -- unlike the mandatory\n    whole-section body fields, an option's content is never required to\n    be non-blank."New value: +"One entry of the dynamic ``## Pros and Cons of the Options`` collection.\n\nRendered as ``### Option {number}: {partial_title}``. Options are never\nindividually mandatory -- zero options is a valid ADR state -- and the\nwhole-section deletion sentinel does not apply to them;\nremoval only ever happens through the dedicated ``option_delete`` tool,\nnot by submitting a blank/``\"REMOVE\"`` value here.\n\nParameters\n----------\nnumber:\n    Monotonically increasing, unpadded, never-reused counter assigned at\n    creation time. Deleting an option leaves a gap; remaining options are\n    neither renumbered nor reordered.\npartial_title:\n    The ``{title}`` portion after ``\"Option {number}: \"``. Must be\n    non-blank and single-line (no embedded line breaks).\ncontent:\n    Opaque markdown blob for the option's body (no enforced\n    Good/Bad/Neutral structure). May be empty -- unlike the mandatory\n    whole-section body fields, an option's content is never required to\n    be non-blank."
    • changedOutput schema / description
      Previous value: -"A full ADR document: YAML frontmatter and body.\n\nThis is the structured object the future parser produces from an\non-disk ``.md`` file and the renderer consumes to produce one, and the\nshape ``get_adr``/``create_adr`` (plan §8) are expected to exchange\nwith the LLM instead of raw markdown text.\n\nThe specmgr schema version lives on ``frontmatter.version`` (plan §3),\nnot here -- it must round-trip through the on-disk file's YAML block,\nwhich only ``frontmatter``/``body`` do (plan §7); a top-level field on\nthis wrapper class would never be persisted.\n\nParameters\n----------\nfrontmatter:\n    The YAML frontmatter block, including the schema version. See\n    :class:`AdrFrontmatter`.\nbody:\n    The parsed body sections and options. See :class:`AdrBody`."New value: +"A full ADR document: YAML frontmatter and body.\n\nThis is the structured object the parser produces from an\non-disk ``.md`` file and the renderer consumes to produce one, and the\nshape ``get_adr``/``create_adr`` exchange with the LLM instead of raw\nmarkdown text.\n\nThe specmgr schema version lives on ``frontmatter.version``,\nnot here -- it must round-trip through the on-disk file's YAML block,\nwhich only ``frontmatter``/``body`` do; a top-level field on\nthis wrapper class would never be persisted.\n\nParameters\n----------\nfrontmatter:\n    The YAML frontmatter block, including the schema version. See\n    :class:`AdrFrontmatter`.\nbody:\n    The parsed body sections and options. See :class:`AdrBody`."
  2. First observedv0.36.0

TDQS

C2.9/5.0
Behavior3/5

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

With no annotations, the description carries the burden, but it does disclose an important behavioral trait: the operation replaces or deletes an entire AdrBody section rather than patching it. It does not explain permissions, reversibility, how deletion is expressed, or what happens to other fields, leaving notable gaps for a mutation tool.

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 single sentence is short and front-loaded, with no obvious filler. However, its terseness contributes to the ambiguity around parameters and deletion behavior rather than resolving it.

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

Completeness2/5

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

The tool has an output schema, so return values need not be described. But as a mutation tool with no annotations and 0% schema description coverage, the description is too thin to fully prepare an agent to call it correctly; key/value semantics and deletion behavior remain unclear.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate. It only hints that 'key' identifies one AdrBody field and 'value' is the replacement, while the required 'id' parameter and the deletion mechanism are unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific operation on a specific object: whole-section replacement or deletion of one AdrBody field. It is clearer than a bare 'update section', though it does not explicitly differentiate itself from sibling tools like update, edit, delete, or update_frontmatter.

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

Usage Guidelines2/5

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

There is no guidance on when to use update_section versus update, edit, delete, or update_frontmatter. The phrase 'whole-section replace/delete' implies a use case, but the agent must infer the boundaries from the many sibling tools.

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