apex-memory

patch_section

Edit one markdown section with replace, append, prepend, or own-text updates, using version checks and all-or-nothing writes to prevent conflicting changes.

Instructions

Edit one section. op: 'replace' (content = what read returned for the section, subsections included, headings relative), 'append' (after the subtree; may add subsections), 'prepend' (before the own text; no headings) or 'replace_own_text' (only the text before the first subsection; subsections kept; no headings). All but append need if_version (the section version read returned). On a page whose only section is the root, append and replace on the root can add headings. Optional summary updates the note's index line (on /index: the domain description). All or nothing, with the checks inside.

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": {
      "op": "<op>",
      "content": "<content>"
    },
    "name": "patch_section"
  }
}

Input Schema

Name	Required	Description	Default
`op`	Yes
`path`	No
`content`	Yes
`heading`	No
`summary`	No
`task_id`	No
`if_version`	No
`section_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.1Nov 3, 2026

TDQS

B3.4/5.0

Behavior3/5

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

With no annotations at all, the description carries the full burden, and it does disclose two non-obvious traits: the write is all-or-nothing with checks performed server-side, and version-guarded operations will presumably fail on stale if_version. It omits permissions/authorization requirements, what an error on version mismatch looks like, and whether the edit is recoverable, which matter for an unannotated 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 text is dense but front-loaded with the operation modes, which is the highest-value information for a caller. The heavy parenthetical asides make it somewhat run-on and harder to scan than a bulleted enumeration would be, but no sentence is filler.

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

Completeness3/5

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

For an eight-parameter mutation tool with no annotations and no output schema, the description covers operations, atomicity, and concurrency control but leaves the section-addressing parameters and the return/error surface entirely unexplained. An agent could not reliably construct a call targeting a specific section from this definition alone.

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 coverage is 0%, so the description must compensate, and it does well for three parameters: it defines the op value set, explains that content means 'what read returned for the section, subsections included, headings relative', and clarifies if_version as the section version from the read. Four of the eight parameters — path, heading, section_id, task_id — receive no explanation whatsoever, leaving the agent without guidance on how a section is actually targeted.

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 opens with a concrete verb and resource ("Edit one section") and immediately enumerates the four operation modes, so an agent knows this is a single-section mutation tool. It does not explicitly contrast itself with the sibling patch_header or log_append, so the boundary between editing a section versus a header or an append log is left to inference.

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

Usage Guidelines3/5

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

Guidance is strong within the op parameter: each mode's placement semantics are spelled out ('append' after the subtree, 'prepend' before own text, 'replace_own_text' only the text before the first subsection) and the version prerequisite is stated for all but append. However, there is no guidance on when to choose this tool over patch_header or log_append, nor any stated preconditions such as needing a prior read.

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

Deploy Server