Skip to main content
Glama
jgravelle

jdocmunch-mcp

by jgravelle
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

check_section_delete_safe

Read-only

Check if a documentation section is safe to delete before removal. It returns a read-only verdict with ranked blockers and a recommended action.

Instructions

Composite preflight: is this section safe to delete? Fuses tutorial-path membership, anchor-specific backlinks, transitive doc-level backlinks, and recent-edit recency into a single verdict (safe_to_delete, tutorial_path_blocking, anchor_referenced, backlinks_blocking, recently_edited_blocking) plus up to 5 ranked blockers and a one-line recommended_action. Read-only — never mutates the index.

Input Schema

NameRequiredDescriptionDefault
repoYes
section_idYesStable section ID, format owner/repo::doc_path::slug#level. v1.147+ — also accepts a `doc.md#anchor` reference to a heading written with an explicit `{#id}`. An ambiguous one is REFUSED (an `error` that sets `anchor_ambiguous`, `anchor_scope`, `anchor_match_count`, `anchor_candidates` (at most 20), `anchor_candidates_truncated` and `warning`), because the answer covers one section: pass a section id.
recent_edit_daysNoDays within which a recent edit becomes a soft blocker. Default 14.
transitive_depthNoBacklink BFS depth. Default 3.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.147.0
    • changedInput schema / properties / section_id / description
      Previous value: -"Stable section ID, format owner/repo::doc_path::slug#level"New value: +"Stable section ID, format owner/repo::doc_path::slug#level. v1.147+ — also accepts a `doc.md#anchor` reference to a heading written with an explicit `{#id}`. An ambiguous one is REFUSED (an `error` that sets `anchor_ambiguous`, `anchor_scope`, `anchor_match_count`, `anchor_candidates` (at most 20), `anchor_candidates_truncated` and `warning`), because the answer covers one section: pass a section id."
  2. Addedv1.121.1
  3. Removedv1.121.0
  4. Addedv1.120.0
  5. Removedv1.99.0
  6. First observedv1.66.3

TDQS

A4/5.0
Behavior4/5

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

With only readOnlyHint in annotations, the description carries the return-contract burden (no output schema exists) and does so well: it names the five verdict fields, the up-to-5 ranked blockers, and recommended_action. It also confirms the read-only guarantee. What is missing is any note on cost/latency of the fused transitive BFS or error/failure behavior.

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?

Two sentences, front-loaded with the purpose question, then the mechanics. The parenthetical field lists are dense but each field earns mention because no output schema documents the return shape. Slightly list-heavy but not padded.

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 four-parameter, read-only aggregate with no output schema, the description covers purpose, return fields and the read-only contract adequately. Gaps are minor: no mention of the ambiguous-anchor refusal path (documented in the schema) and no coverage of the `repo` parameter.

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 75%, just under the high-coverage baseline, so the schema does most of the work on section_id, recent_edit_days and transitive_depth. The description adds real meaning by tying recent_edit_days to recently_edited_blocking and transitive_depth to the doc-level backlink signal, but the bare `repo` parameter gets no semantic help anywhere.

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?

"Composite preflight: is this section safe to delete?" states a specific verb (preflight/check) and resource (section deletion safety), and enumerates the four signals it fuses so the agent understands this is an aggregation tool, not a single-signal lookup. It never names the closest siblings (get_backlinks, get_section_blast_radius), so the differentiation must be inferred from "composite."

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?

"Preflight" establishes the usage context clearly: call this before deleting a section, to obtain a single go/no-go verdict. There are no explicit exclusions or named alternatives (e.g., "use get_backlinks for raw backlink lists"), so the agent must infer when the composite is overkill.

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