hive

Overview Schema Source Related Servers Discussions Admin

project_prune

DestructiveIdempotent

Delete hive projects safely: sweep empty projects with no rows anywhere, or remove one named project with confirmation, snapshotting first and refusing if live panes own rows.

Instructions

Delete every registered project that owns no rows anywhere in the store (pads, todos, kv, leases, agents, wakes, command_trust, questions), verified individually before each delete. Never prunes the caller's own project. With project_id, removes exactly that one project instead of sweeping, and only if it owns no rows; otherwise refuses and names what it owns. With project_id AND confirm_name (the project's exact name), removes that one project even when it owns rows: it takes a snapshot first, refuses while a running row owns a live pane or its pane ownership cannot be verified (agent_close row_only retires the latter), then deletes the project with everything it owns (todos, comments, pads, kv, leases, agents, wakes, trust, questions, agent messages) in one transaction and reports per-table counts and the snapshot path. queen_audit rows naming it are kept, and so are other projects' lead-idle subscriptions that target it, so a watch on its lead ends with a named reason. confirm_name without project_id is refused, and there is no forced sweep. Refuses under HIVE_PROJECT_LOCK=1: this is a whole-store sweep, and a project-locked session may only touch its own project. Immediate, permanent: no dry-run mode.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`project_id`	No
`confirm_name`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`counts`	No
`errors`	No
`deleted`	Yes
`snapshot`	No
`held_back`	Yes
`hive_notice`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.5.0Oct 1, 2026

addedInput schema / properties / confirm_name
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / counts

Added value: +{
+  "additionalProperties": {
+    "type": "number"
+  },
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

addedOutput schema / properties / snapshot

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

Changed1 schema field changedv1.4.0Sep 30, 2026

addedInput schema / properties / project_id

Added value: +{
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

Changed1 schema field changedv1.2.2Sep 26, 2026
- addedOutput schema / properties / hive_notice
```
Added value: +{
+  "type": "string"
+}
```
First observedv1.0.0Sep 22, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare destructive=true and idempotent=true, and the description adds substantial context beyond them: snapshot-before-delete, single-transaction deletion, per-table count reporting, preservation of queen_audit rows and other projects' lead-idle subscriptions, live-pane refusal, and the lock refusal. Far exceeds the annotation bar.

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 primary sweep behavior and dense with content, but it is a long run-on paragraph with some repetition ('removes exactly that one project') and no structural breaks for the three modes. Every clause is arguably load-bearing, so waste is low.

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

Completeness5/5

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

For a destructive, multi-mode tool with an output schema and 0% param coverage, the description covers the refusal conditions, transaction semantics, side effects on related tables, and the lock constraint. Nothing an agent needs to call it safely is missing.

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%, so the description must carry the semantics. It explains project_id (single-project removal, only if empty) and confirm_name (exact name enabling forced removal), plus the edge case that confirm_name without project_id is refused. Strong coverage, though it does not restate the integer/exclusive-minimum type constraints.

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 (delete/prune), resource (registered projects owning no rows), and scope, then distinguishes three distinct operating modes (bare sweep, project_id, project_id+confirm_name). An agent can tell exactly what this does versus sibling project_list/project_add/project_select.

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 names when each mode applies, when the tool refuses (owns rows, live pane, HIVE_PROJECT_LOCK=1, confirm_name without project_id), and that there is no forced sweep or dry-run. This is detailed when/when-not guidance.

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