Skip to main content
Glama
Sign In
gograph

gograph

by ozgurcd
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

gograph_session_cleanup

DestructiveIdempotent

Archive stale sessions and logs without deleting files. Ends idle or exited sessions, preserves the active log, and refuses while another caller is still live.

Instructions

Archive stale and inactive session telemetry without following linked repository paths; never deletes. Each pass moves files into .gograph/to_delete//. First ends other callers' CLI-owned sessions idle past the idle limit (GOGRAPH_SESSION_IDLE_LIMIT, default 2h) or MCP-owned sessions whose server process exited on this host (owners without metadata or on another host are kept), listing each, and archives an unselected legacy active_session.json; then archives logs with end records; preserves the selected active log and refuses while any other caller is still live. MCP annotations mark this operation mutating and destructive. No prerequisites. WHEN TO USE: Call after auditing to keep the repository clean. RETURNS: Each ended session, any archived legacy pointer, and the number of session logs moved with the archive folder, or Nothing to archive.

Input Schema

NameRequiredDescriptionDefault
rootNoAbsolute path of the checkout you are working in (your cwd or git worktree). Must be this server's repository or one of its git worktrees; the answer then comes from that checkout's own graph. A path elsewhere is refused. Alias: cwd. Omit only when the configured checkout is the one you mean.
intentionNoTechnical rationale, required for analytical calls selecting an active session.
session_idNoCaller selector returned by session_create. Omission means an independent caller; never inherits server environment or another caller's session.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.7.18
    • addedInput schema / properties / intention
      Added value: +{
+  "description": "Technical rationale, required for analytical calls selecting an active session.",
+  "type": "string"
+}
    • addedInput schema / properties / root
      Added value: +{
+  "description": "Absolute path of the checkout you are working in (your cwd or git worktree). Must be this server's repository or one of its git worktrees; the answer then comes from that checkout's own graph. A path elsewhere is refused. Alias: cwd. Omit only when the configured checkout is the one you mean.",
+  "type": "string"
+}
    • addedInput schema / properties / session_id
      Added value: +{
+  "description": "Caller selector returned by session_create. Omission means an independent caller; never inherits server environment or another caller's session.",
+  "type": "string"
+}
  2. Added

TDQS

A4/5.0
Behavior4/5

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

Goes well past the annotations by disclosing that files move to .gograph/_to_delete/<UTC time>_<suffix>/ rather than being deleted, the idle-limit env var and default, exactly which sessions are ended versus kept, the legacy active_session.json handling, and the refusal when another caller is live. The explicit note that 'MCP annotations mark this operation mutating and destructive' reconciles the destructiveHint with the 'never deletes' guarantee instead of contradicting it.

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?

The core guarantee is front-loaded, which is good, but the central sentence is a long run-on stacking multiple phases and parentheticals that is hard to parse in one pass. 'MCP annotations mark this operation mutating and destructive' largely restates the annotations and costs space.

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?

With three optional parameters, no output schema, and no enum constraints, the definition covers what an agent needs: preconditions, the two-phase behavior, safety guarantees, and a RETURNS section listing ended sessions, archived legacy pointer, log count and folder, or 'Nothing to archive'. Minor ambiguity remains about how root interacts with a caller's session selection, but the schema covers that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so root, intention, and session_id are already fully documented in the schema, including the cwd alias and the meaning of omission. The description only obliquely touches selection semantics ('an unselected legacy active_session.json', 'preserves the selected active log') without adding format or constraint detail beyond the schema.

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 resource ('Archive stale and inactive session telemetry') plus the defining scope constraint ('without following linked repository paths; never deletes'), which separates it cleanly from siblings like gograph_session_end and gograph_session_audit. The archive destination path makes the operation concrete rather than abstract.

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?

'WHEN TO USE: Call after auditing to keep the repository clean' gives a clear trigger and implicitly routes from gograph_session_audit, and 'refuses while any other caller is still live' supplies a precondition. It stops short of naming the sibling to use instead when the caller is not ready to archive, so it is clear context without explicit exclusions.

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