apex-memory

batch

Apply several note, section, and status operations in one transaction: if any write is refused, every change is rolled back and the failing op_index is returned.

Instructions

Several writes in one transaction, all or nothing: ops = [{"tool": name, "args": {...}}, ...] with tools create_note, patch_section, patch_header, status_item, set_decision_status, log_append and source. Each op has its own role rules and refusals. The checks (and the pages that log_append names) run once, against the final state, so notes that link to each other can be created together. A refusal rolls back every op and gives op_index. Returns the result of each op.

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": {
      "ops": "<ops>"
    },
    "name": "batch"
  }
}

Input Schema

Name	Required	Description	Default
`ops`	Yes
`task_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.1Nov 3, 2026

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations, the description carries the load and mostly does: atomicity, rollback on refusal, that a refusal returns op_index, that checks are deferred to final state, and that each op keeps its own role rules and refusals. Gaps remain on how task_id interacts with ops and on the exact failure payload, but the transactional contract itself is disclosed clearly.

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?

Dense and front-loaded: the all-or-nothing semantics and the ops shape come first, caveats after. A couple of clauses are run together and the allowed-tool list interrupts the flow, but no sentence is filler.

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

Completeness4/5

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

For a transactional wrapper with no output schema, the description covers semantics an agent needs to call it correctly and states the return shape at a high level ("Returns the result of each op"). Only the role of task_id and the precise refusal payload are left unexplained.

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 description coverage is 0% and the array items are untyped objects, so the description supplies the entire ops contract — the {"tool": name, "args": {...}} object shape and the closed list of permitted tool names — which is large value beyond the schema. The second parameter, task_id, is never mentioned, so it stops short of full coverage.

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 scope — several writes executed as one all-or-nothing transaction — and then enumerates the exact set of tools it can wrap (create_note, patch_section, patch_header, status_item, set_decision_status, log_append, source). An agent can tell immediately that this is the atomic multi-write sibling of those individual tools.

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

Usage Guidelines4/5

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

It gives a concrete selection condition: use it so notes that link to each other can be created together, because the checks run once against the final state. That is a real reason to choose batch over calling siblings individually and implies the inverse (single op needs no batch), but no explicit when-not guidance or named alternatives.

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

Deploy Server