Skip to main content
Glama
Sign In
AIWorkhub

AIWorkhub

by shrec
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

aiworkhub_storage_recover_stranded_worktrees

Reports retained worktrees stranded outside reclamation paths, then re-registers provably owned ones when confirmed with a reason and logs the action.

Instructions

Recover retained worktrees stranded outside every reclamation path.

NF-2026-00279: the storage observability surface recommends this recovery, but it had no tool/MCP/CLI entry point, so an operator was told to run something they could not. This exposes it as a real action.

READ-ONLY first: confirm=False (the default) returns a report of the worktrees that would be re-registered and those that are orphaned-but- reclaimable, mutating nothing. confirm=True requires a non-empty reason, reinstates the provably-owned registrations, and records the reason in the audit log.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "aiworkhub_storage_recover_stranded_worktrees"
  }
}

Input Schema

NameRequiredDescriptionDefault
reasonNoWhy the recovery is being run; required and non-empty when confirm is true, recorded in the audit log. Leave empty for the report.
confirmNofalse (default) only reports what would be recovered and changes nothing; true performs the recovery and requires a non-empty reason.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.12.67
    • addedInput schema / properties / confirm / description
      Added value: +"false (default) only reports what would be recovered and changes nothing; true performs the recovery and requires a non-empty reason."
    • addedInput schema / properties / reason / description
      Added value: +"Why the recovery is being run; required and non-empty when confirm is true, recorded in the audit log. Leave empty for the report."
  2. First observedv0.1.0

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing the dual-mode behavior: the default is a non-mutating report, confirmed execution requires a non-empty reason, and the reason is recorded in the audit log. It also characterizes which worktrees are reinstated (provably-owned registrations) versus orphaned-but-reclaimable, which annotations alone cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly with the action, and the read-only-first paragraph is dense and useful. However, the NF-2026-00279 backstory ('an operator was told to run something they could not') is justification for the tool's existence rather than guidance an agent needs, and could be trimmed without loss.

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?

An output schema exists, so return values need no explanation, and both parameters plus both execution modes are covered. What remains unstated is what 'provably-owned' actually keys off and whether any permission or precondition gates confirmed recovery – minor but real gaps for a mutating path.

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 100%, so baseline is 3; the description still adds value by tying the two parameters together (confirm=True requires non-empty reason; leave reason empty for the report) and explaining that the reason lands in the audit log. It adds little on the report's contents beyond that.

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?

States a specific verb and resource: recovering retained worktrees that are stranded outside every reclamation path. It is clearly distinguishable from sibling storage tools (restore/quarantine/purge) by its 'stranded, outside reclamation paths' framing. Slightly jargon-heavy ('retained worktrees', 're-registered') but the action is identifiable.

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?

Gives a concrete trigger – the storage observability surface recommends this recovery – and prescribes the workflow order (report first via confirm=False, then confirm=True). It does not name an alternative sibling tool or state when NOT to use it, keeping it short of a 5.

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