Datacron

Overview Schema Source Related Servers Discussions Admin

Delete note section

delete_note_section

Destructive

Removes an obsolete H2-H6 Markdown section and all subordinate headings from a note, using a content hash check for safe, atomic edits.

Instructions

Use this only to remove an explicitly obsolete H2-H6 Markdown section and all of its subordinate headings. Prefer lifecycle invalidation with set_frontmatter when the fact must remain queryable. Pass the note's current content_hash as expected_hash for CAS. The operation stores exact prior history, writes atomically, and refuses every level-1 heading. For duplicate titles, pass 1-based heading_occurrence with heading_level and the exact expected_hash; the ordinal follows document order for those hashed bytes. Do not use chunk_id.

Input Schema

Name	Required	Description	Default
`heading`	Yes
`rel_path`	Yes
`request_id`	No
`expected_hash`	No
`heading_level`	No
`heading_occurrence`	No

Output Schema

Name	Required	Description	Default
`deleted`	No
`indexed`	Yes
`rel_path`	No
`replayed`	No
`committed`	No
`content_hash`	Yes
`operation_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.1.17Oct 17, 2026
- addedOutput schema / description
```
Added value: +"Successful ``delete_note_section`` payload."
```
- removedOutput schema / properties / committed / default
```
Removed value: -null
```
- removedOutput schema / properties / deleted / default
```
Removed value: -null
```
- removedOutput schema / properties / operation_id / default
```
Removed value: -null
```
- removedOutput schema / properties / rel_path / default
```
Removed value: -null
```
- removedOutput schema / properties / replayed / default
```
Removed value: -null
```

Changed9 schema fields changedv0.1.5Sep 5, 2026

addedInput schema / properties / request_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Request Id"
+}

addedOutput schema / properties / committed

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Committed"
+}

removedOutput schema / properties / deleted / $ref
```
Removed value: -"#/$defs/DeletedSectionOutput"
```

addedOutput schema / properties / deleted / anyOf

Added value: +[
+  {
+    "$ref": "#/$defs/DeletedSectionOutput"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / deleted / default
```
Added value: +null
```

addedOutput schema / properties / operation_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Operation Id"
+}

addedOutput schema / properties / rel_path

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Rel Path"
+}

addedOutput schema / properties / replayed

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Replayed"
+}

changedOutput schema / required

Previous value: -[
-  "deleted",
-  "content_hash",
-  "indexed"
-]New value: +[
+  "content_hash",
+  "indexed"
+]

Addedv0.1.3Aug 29, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations declare destructive/non-idempotent, but the description adds real behavioral context beyond them: CAS via expected_hash, atomic write, exact prior history retained, and the refusal of all level-1 headings. These are non-obvious safety semantics an agent must know before calling.

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 with the when-to-use rule and otherwise dense with no filler; each sentence adds a distinct fact. It is slightly cramped, packing CAS, refusal, and duplicate-title rules into one block, but nothing is redundant.

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 destructive, six-parameter tool with 0% schema coverage the description covers the risky, ambiguous parameters and the refusal semantics. Return values are handled by the existing output schema, so not explaining them is acceptable; only the trivial params are left implicit.

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 0%, so the description carries the full burden and does well on the hard cases: expected_hash as CAS, 1-based heading_occurrence combined with heading_level, and its document-order semantics for the hashed bytes. rel_path, heading, and request_id remain unexplained, but the two required params are self-evident by name.

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 ('remove') plus the exact resource ('H2-H6 Markdown section and all of its subordinate headings'), with scope that separates it from patch_note_section and rename_note_section. An agent can identify the operation and its blast radius without opening the schema.

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?

Explicitly says when to use ('only to remove an explicitly obsolete section') and names the alternative with its condition ('Prefer lifecycle invalidation with set_frontmatter when the fact must remain queryable'). It also gives a negative instruction ('Do not use chunk_id').

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