Skip to main content
Glama

session_digest

Destructive

Build a session-start resume digest that combines stale threads, due reminders, and wiki context, ranked by query and filtered by energy so you can resume work at your current capacity.

Instructions

Build the session-start resume digest for the current work context.

    Use after resolve_project. It combines relevant stale/open threads, due
    reminders, and the progress wiki snippet; query narrows overlap relevance
    and energy can filter work to the operator's current capacity. Each item
    carries completion readiness and advisory return_cue coaching for its
    resume_step (deterministic, local, never blocking). This is a mutating
    session action: it refreshes nudged threads' reminder cooldowns, marks
    surfaced non-session reminders fired, and builds a missing wiki index.
    Random reminders are sampled, so repeat calls may produce different results.

    clock_off is the global opt-in advisory boundary. During winding_down or
    clocked_off, avoid substantial new work, finish only a small safe step,
    checkpoint with upsert_progress and pause_thread with a concrete resume
    step. Respect explicit temporary overrides; no forced shutdown or strict
    Continuity Guard is required. Disabled Clock-Off adds no work restrictions.

    Includes a `guidance` object (expected versions + last local verification
    status). The Hub cannot inspect the client's checkout — run
    `adhd-hub doctor --project` locally (or call `report_guidance_health`
    after a local check) so this field becomes meaningful.
    

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": "session_digest"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryNoOptional intended outcome or keywords to rank relevant open work; no overlap falls back to the Next-up ranking.
energyNoExact energy filter: low, medium, high or unknown; null includes all levels. An empty project pool falls back to all projects.
workspace_pathNoClient workspace folder path to resolve the current project without creating it; null or unresolved path considers all projects.

Output Schema

NameRequiredDescriptionDefault
itemsYes
guidanceYes
clock_offYesGlobal opt-in advisory boundary and wrap-up guidance.
open_countYesUnfinished threads in the selected pool.
stale_countYesStale threads excluding active triage snoozes.
due_remindersYes
wiki_index_snippetYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv0.22.0
    • addedInput schema / properties / energy / description
      Added value: +"Exact energy filter: low, medium, high or unknown; null includes all levels. An empty project pool falls back to all projects."
    • addedInput schema / properties / query / description
      Added value: +"Optional intended outcome or keywords to rank relevant open work; no overlap falls back to the Next-up ranking."
    • addedInput schema / properties / workspace_path / description
      Added value: +"Client workspace folder path to resolve the current project without creating it; null or unresolved path considers all projects."
    • addedOutput schema / $defs
      Added value: +{
      +  "ClockOffState": {
      +    "properties": {
      +      "clock_off_at": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "title": "Clock Off At"
      +      },
      +      "enabled": {
      +        "default": false,
      +        "title": "Enabled",
      +        "type": "boolean"
      +      },
      +      "guidance": {
      +        "default": [],
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "Guidance",
      +        "type": "array"
      +      },
      +      "minutes_remaining": {
      +        "anyOf": [
      +          {
      +            "type": "integer"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "title": "Minutes Remaining"
      +      },
      +      "override_until": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "title": "Override Until"
      +      },
      +      "resumes_at": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "title": "Resumes At"
      +      },
      +      "state": {
      +        "default": "normal",
      +        "enum": [
      +          "normal",
      +          "winding_down",
      +          "clocked_off",
      +          "overridden"
      +        ],
      +        "title": "State",
      +        "type": "string"
      +      },
      +      "timezone": {
      +        "default": "UTC",
      +        "title": "Timezone",
      +        "type": "string"
      +      },
      +      "wind_down_at": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "title": "Wind Down At"
      +      }
      +    },
      +    "title": "ClockOffState",
      +    "type": "object"
      +  },
      +  "CompletionResult": {
      +    "additionalProperties": true,
      +    "description": "Readiness based on stored thread state, without checking a forge or PR.",
      +    "properties": {
      +      "ready": {
      +        "description": "True when stored state has no completion blockers.",
      +        "title": "Ready",
      +        "type": "boolean"
      +      },
      +      "reasons": {
      +        "description": "Stored blockers; empty when ready is true.",
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "Reasons",
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "ready",
      +      "reasons"
      +    ],
      +    "title": "CompletionResult",
      +    "type": "object"
      +  },
      +  "DigestThreadResult": {
      +    "additionalProperties": true,
      +    "description": "Raw session thread with completion readiness and resume coaching.",
      +    "properties": {
      +      "blocked_reason": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Blocked Reason"
      +      },
      +      "chat_ref": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Chat Ref"
      +      },
      +      "completion": {
      +        "$ref": "#/$defs/CompletionResult"
      +      },
      +      "created_at": {
      +        "format": "date-time",
      +        "title": "Created At",
      +        "type": "string"
      +      },
      +      "energy": {
      +        "$ref": "#/$defs/EnergyLevel"
      +      },
      +      "external_fingerprint": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "External Fingerprint"
      +      },
      +      "external_host": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "External Host"
      +      },
      +      "external_issue_number": {
      +        "anyOf": [
      +          {
      +            "type": "integer"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "External Issue Number"
      +      },
      +      "external_issue_state": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/ExternalIssueState"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "external_labels": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "External Labels",
      +        "type": "array"
      +      },
      +      "external_owner": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "External Owner"
      +      },
      +      "external_provider": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/WorkSource"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "external_repo": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "External Repo"
      +      },
      +      "external_updated_at": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "External Updated At"
      +      },
      +      "focus": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Focus"
      +      },
      +      "goal": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Goal"
      +      },
      +      "id": {
      +        "title": "Id",
      +        "type": "string"
      +      },
      +      "last_reminded_at": {
      +        "anyOf": [
      +          {
      +            "format": "date-time",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Last Reminded At"
      +      },
      +      "merged_into": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Merged Into"
      +      },
      +      "next_steps": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "Next Steps",
      +        "type": "array"
      +      },
      +      "origin": {
      +        "title": "Origin",
      +        "type": "string"
      +      },
      +      "paused_at": {
      +        "anyOf": [
      +          {
      +            "format": "date-time",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Paused At"
      +      },
      +      "project_slug": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Project Slug"
      +      },
      +      "resume_step": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Resume Step"
      +      },
      +      "return_cue": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/ReturnCueResult"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "source_conflicts": {
      +        "additionalProperties": true,
      +        "title": "Source Conflicts",
      +        "type": "object"
      +      },
      +      "source_content_hash": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Source Content Hash"
      +      },
      +      "source_imported_at": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Source Imported At"
      +      },
      +      "source_issue_url": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Source Issue Url"
      +      },
      +      "source_snapshot": {
      +        "additionalProperties": true,
      +        "title": "Source Snapshot",
      +        "type": "object"
      +      },
      +      "source_sync_state": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Source Sync State"
      +      },
      +      "source_title_derived": {
      +        "title": "Source Title Derived",
      +        "type": "boolean"
      +      },
      +      "source_tool": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Source Tool"
      +      },
      +      "status": {
      +        "$ref": "#/$defs/ThreadStatus"
      +      },
      +      "summary": {
      +        "title": "Summary",
      +        "type": "string"
      +      },
      +      "transcript_ref": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Transcript Ref"
      +      },
      +      "triage_snooze_until": {
      +        "anyOf": [
      +          {
      +            "format": "date-time",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Triage Snooze Until"
      +      },
      +      "updated_at": {
      +        "format": "date-time",
      +        "title": "Updated At",
      +        "type": "string"
      +      },
      +      "work_source": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/WorkSource"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "workspace_path": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Workspace Path"
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "summary",
      +      "status",
      +      "energy",
      +      "created_at",
      +      "updated_at",
      +      "next_steps",
      +      "completion",
      +      "return_cue"
      +    ],
      +    "title": "DigestThreadResult",
      +    "type": "object"
      +  },
      +  "EnergyLevel": {
      +    "enum": [
      +      "low",
      +      "medium",
      +      "high",
      +      "unknown"
      +    ],
      +    "title": "EnergyLevel",
      +    "type": "string"
      +  },
      +  "ExternalIssueState": {
      +    "enum": [
      +      "open",
      +      "closed"
      +    ],
      +    "title": "ExternalIssueState",
      +    "type": "string"
      +  },
      +  "GuidanceDigestResult": {
      +    "additionalProperties": true,
      +    "description": "Expected guidance versions and the client's last reported local check.",
      +    "properties": {
      +      "expected_session_skill_version": {
      +        "title": "Expected Session Skill Version",
      +        "type": "integer"
      +      },
      +      "expected_version": {
      +        "title": "Expected Version",
      +        "type": "integer"
      +      },
      +      "hint": {
      +        "title": "Hint",
      +        "type": "string"
      +      },
      +      "last_verified_at": {
      +        "anyOf": [
      +          {
      +            "format": "date-time",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Last Verified At"
      +      },
      +      "last_verified_version": {
      +        "anyOf": [
      +          {
      +            "type": "integer"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Last Verified Version"
      +      },
      +      "status": {
      +        "enum": [
      +          "local_verification_required",
      +          "verification_recommended",
      +          "last_verified_current"
      +        ],
      +        "title": "Status",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "expected_version",
      +      "expected_session_skill_version",
      +      "last_verified_version",
      +      "last_verified_at",
      +      "status",
      +      "hint"
      +    ],
      +    "title": "GuidanceDigestResult",
      +    "type": "object"
      +  },
      +  "ReminderKind": {
      +    "enum": [
      +      "once",
      +      "session",
      +      "daily",
      +      "random"
      +    ],
      +    "title": "ReminderKind",
      +    "type": "string"
      +  },
      +  "ReminderResult": {
      +    "additionalProperties": true,
      +    "properties": {
      +      "created_at": {
      +        "format": "date-time",
      +        "title": "Created At",
      +        "type": "string"
      +      },
      +      "due_at": {
      +        "anyOf": [
      +          {
      +            "format": "date-time",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Due At"
      +      },
      +      "handled": {
      +        "title": "Handled",
      +        "type": "boolean"
      +      },
      +      "id": {
      +        "title": "Id",
      +        "type": "string"
      +      },
      +      "kind": {
      +        "$ref": "#/$defs/ReminderKind"
      +      },
      +      "last_fired_at": {
      +        "anyOf": [
      +          {
      +            "format": "date-time",
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Last Fired At"
      +      },
      +      "message": {
      +        "title": "Message",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "message",
      +      "kind",
      +      "due_at",
      +      "created_at",
      +      "handled",
      +      "last_fired_at"
      +    ],
      +    "title": "ReminderResult",
      +    "type": "object"
      +  },
      +  "ReturnCueResult": {
      +    "additionalProperties": true,
      +    "description": "Advisory resume coaching; never rejects a save, pause or completion.",
      +    "properties": {
      +      "advisory": {
      +        "const": true,
      +        "title": "Advisory",
      +        "type": "boolean"
      +      },
      +      "hint": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "title": "Hint"
      +      },
      +      "quality": {
      +        "enum": [
      +          "missing",
      +          "vague",
      +          "concrete"
      +        ],
      +        "title": "Quality",
      +        "type": "string"
      +      },
      +      "signals": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "title": "Signals",
      +        "type": "array"
      +      },
      +      "suggestion": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/ReturnCueSuggestion"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "version": {
      +        "title": "Version",
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "quality",
      +      "signals",
      +      "hint",
      +      "suggestion",
      +      "advisory",
      +      "version"
      +    ],
      +    "title": "ReturnCueResult",
      +    "type": "object"
      +  },
      +  "ReturnCueSuggestion": {
      +    "additionalProperties": true,
      +    "properties": {
      +      "source": {
      +        "enum": [
      +          "focus",
      +          "next_steps"
      +        ],
      +        "title": "Source",
      +        "type": "string"
      +      },
      +      "text": {
      +        "title": "Text",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "source",
      +      "text"
      +    ],
      +    "title": "ReturnCueSuggestion",
      +    "type": "object"
      +  },
      +  "ThreadStatus": {
      +    "enum": [
      +      "open",
      +      "blocked",
      +      "done",
      +      "dismissed"
      +    ],
      +    "title": "ThreadStatus",
      +    "type": "string"
      +  },
      +  "WorkSource": {
      +    "enum": [
      +      "local",
      +      "github",
      +      "gitea"
      +    ],
      +    "title": "WorkSource",
      +    "type": "string"
      +  }
      +}
    • addedOutput schema / description
      Added value: +"Session summary after reminder cooldown/firing bookkeeping."
    • addedOutput schema / properties
      Added value: +{
      +  "clock_off": {
      +    "$ref": "#/$defs/ClockOffState",
      +    "description": "Global opt-in advisory boundary and wrap-up guidance."
      +  },
      +  "due_reminders": {
      +    "items": {
      +      "$ref": "#/$defs/ReminderResult"
      +    },
      +    "title": "Due Reminders",
      +    "type": "array"
      +  },
      +  "guidance": {
      +    "anyOf": [
      +      {
      +        "$ref": "#/$defs/GuidanceDigestResult"
      +      },
      +      {
      +        "type": "null"
      +      }
      +    ]
      +  },
      +  "items": {
      +    "items": {
      +      "$ref": "#/$defs/DigestThreadResult"
      +    },
      +    "title": "Items",
      +    "type": "array"
      +  },
      +  "open_count": {
      +    "description": "Unfinished threads in the selected pool.",
      +    "title": "Open Count",
      +    "type": "integer"
      +  },
      +  "stale_count": {
      +    "description": "Stale threads excluding active triage snoozes.",
      +    "title": "Stale Count",
      +    "type": "integer"
      +  },
      +  "wiki_index_snippet": {
      +    "anyOf": [
      +      {
      +        "type": "string"
      +      },
      +      {
      +        "type": "null"
      +      }
      +    ],
      +    "title": "Wiki Index Snippet"
      +  }
      +}
    • addedOutput schema / required
      Added value: +[
      +  "open_count",
      +  "stale_count",
      +  "items",
      +  "due_reminders",
      +  "wiki_index_snippet",
      +  "guidance",
      +  "clock_off"
      +]
    • changedOutput schema / title
      Previous value: -"session_digestDictOutput"New value: +"SessionDigestResult"
  2. First observedv0.12.0

TDQS

A3.6/5.0
Behavior3/5

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

The description discloses real side effects beyond the annotations: it refreshes nudged threads' reminder cooldowns, marks surfaced non-session reminders fired, and builds a missing wiki index, plus it explains the non-idempotency ('random reminders are sampled, so repeat calls may produce different results'). That is genuinely useful context. However, with destructiveHint=true already declared, the description does not say whether any of these mutations are reversible or what an operator should do if a call fires reminders unexpectedly, leaving the destructive profile only partially explained.

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?

Purpose is front-loaded in the first sentence, which is good, but the definition runs four paragraphs and drifts into workflow policy (clock-off etiquette, local doctor commands, Continuity Guard) that is only loosely about invoking this tool. The guidance-object paragraph partially duplicates what the output schema can express, so several sentences don't fully earn their place.

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 mutating, non-idempotent session-start tool with an output schema, the definition covers ordering, side effects, sampling variance, and the shape of returned items and the guidance object. The remaining gaps — reversibility of fired reminders and when to prefer sibling tools — are moderate rather than critical, and return values are already handled by the output schema.

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 all three parameters are already documented, including fallback behavior for empty pools and unresolved paths. The description restates the roles of query (narrows overlap relevance) and energy (filters to current capacity) without adding syntax or precedence detail beyond the schema, and it does not mention workspace_path at all. Baseline 3 is appropriate when the schema carries the load.

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?

The opening sentence gives a specific verb and resource: 'Build the session-start resume digest for the current work context,' and the second sentence enumerates the inputs it combines (stale/open threads, due reminders, progress wiki snippet). It is clear what the tool produces, but it never names adjacent siblings such as suggest_next_up or get_overview, so differentiation from those must be inferred.

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?

It gives an explicit sequencing rule ('Use after resolve_project') and conditional usage for capacity filtering via energy and relevance narrowing via query. It also prescribes behavior during winding_down or clocked_off (finish a small safe step, checkpoint with upsert_progress, pause_thread). It stops short of stating when NOT to call it or which sibling to prefer instead.

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