Agentpack is a repo-native task continuity server for AI coding agents, enabling durable state recording and retrieval across sessions, clients, and context resets.
Context & Resumption
load_context — Load compact task context (Task Passport, decisions, sources, checkpoints) at session start
resume — Generate a budgeted markdown resume of task state
replay — Replay the full task timeline
diff — Compare two checkpoints to see what changed
Recording Durable State
record_decision — Record a decision made during the task, with optional file references and evidence
record_dead_end — Record a failed approach so future agents avoid repeating it
attach_evidence — Attach evidence such as test output, command output, notes, or links
record_source — Cache a reviewed source file with its hash and conclusion to avoid re-reading unchanged files
checkpoint — Create a named checkpoint with status, summary, and next actions
Task Passport Lifecycle
task_start — Create a new Task Passport with title, objective, constraints, scope, risk, and next actions
task_status — Print a quick summary of the current Task Passport
task_update — Update objective, constraints, scope, next actions, tags, or risk
task_update_verification — Update verification status, summary, and evidence references
task_finalize — Close the current task with a final verification status
task_park / task_switch — Park the active task and switch between open tasks
task_list — List all Task Passports with statuses and branches
task_handoff — Generate a compact handoff summary for switching chats, clients, or agents
task_role — Read or update guidance for a specific role lane (scout, builder, reviewer, archivist)
Auditing & Health Checks
task_audit — Audit the current Task Passport for continuity risks (stale sources, drift, missing next actions)
source_status — Check whether recorded source file conclusions are still valid, changed, or missing
release_preflight — Run a read-only release preflight report
Bundle Import/Export (Portable Handoffs)
bundle_export — Export a redacted, structured task bundle JSON
bundle_inspect — Validate and summarize a bundle without writing state
bundle_import_plan — Preview what a bundle import would do without applying changes
bundle_import — Import a task bundle (applied only when write: true is set)
Repo-native task continuity for AI coding agents.
Coding agents forget. Agentpack gives them the task state they need to continue.
Here it is live. Session 1: Claude Code investigates a flaky test and records what it learns through the Agentpack MCP tools. Session 2, next day, empty context: the agent loads the task state and picks up exactly where the first session stopped — no re-investigation:
Prefer to poke at it by hand? The same flow driven from the CLI is in docs/DEMOS.md.
Every session ends the same way: the context window gets compacted, the chat closes, the task waits until tomorrow. The next session starts from zero — re-reading files, rediscovering decisions, retrying approaches that already failed.
Agentpack keeps a small, reviewable task ledger in .agentpack/ inside your repo. Connected agents record durable state as they work — the goal, decisions, dead ends, verification evidence, checkpoints — and the next session loads it back and continues. That next session can be the same agent after compaction, a different client, or you returning next week.
Local-first. Plain files in your repo. No cloud, no telemetry, no network calls.
Agent-oriented. A local MCP server plus generated project instructions (AGENTS.md, CLAUDE.md, Cursor rules) tell agents when to load and record state.
Human-friendly. The same state is available through the CLI for inspection, debugging, and manual handoff.
Requires Node.js >= 20.
npm install -g agentpack-cli
cd path/to/your/repo
agentpack init # once per repo
agentpack install claude --write # per client: codex | claude | cursor | claude-desktopRestart or reconnect the coding-agent client. From then on the agent loads Agentpack context at session start, records durable decisions, sources, and evidence while working, and checkpoints meaningful progress.
Run agentpack doctor to verify the setup, and agentpack resume --preset agent --query "<topic>" to inspect the task state yourself.
See docs/INTEGRATIONS.md for client-by-client setup, including what each installer writes and why.
Related MCP server: MCP Starter
At session start, the agent loads compact Agentpack context: the current Task Passport, recent checkpoints, decisions, and reviewed source conclusions.
While working, it records durable state — decisions worth keeping, approaches that failed, verification evidence — and caches reviewed source conclusions with file hashes so unchanged files don't need re-reading.
At a coherent boundary, it creates a checkpoint with status, next actions, and git state.
The next session — any MCP-connected agent — continues from that state instead of rebuilding it from chat history.
The ledger is task-scoped: a Task Passport carries the goal, status, constraints, write scope, next actions, and verification for the current task, with an explicit lifecycle (start, park, switch, finalize) for handoffs. An optional task gate (native Claude Code, Codex, and Cursor hooks plus a client-neutral pre-commit hook) warns — or in block mode, stops — when edits bypass the active task. The gate warns by default; opt into enforcement with "gateMode": "block" in .agentpack/config.json (modes and exit codes in docs/CLI.md).
Context is budgeted: resume output is compressed under a rough token estimate, so agents get the useful state back, not a pile of history.
The context window is compacted mid-task and the next turn needs the state back.
You start a fresh chat or session on an ongoing task.
You switch between Claude Code, Cursor, Codex, or another MCP client.
You return to a refactor or bugfix days later.
Another agent — or a teammate's agent — continues from your checkpoint.
You split one session across parts of a monorepo (api/, frontend/, cron/) with short scoped tasks, and the task gate keeps the agent from drifting outside the folder the current task owns.
A side effect: agents spend fewer tokens re-reading unchanged files and re-explaining old decisions.
Zero runtime dependencies, exact dev dependencies, committed lockfile, ignore-scripts=true.
No telemetry and no network calls during normal CLI or MCP operation.
Best-effort redaction of secret-looking values in stored context and handoff output.
Releases are published from GitHub Actions with npm provenance (Trusted Publisher, no long-lived tokens); verify with npm audit signatures.
See SECURITY.md for the full policy.
docs/INTEGRATIONS.md — safe setup for Codex, Claude Code, Cursor, Claude Desktop, and git hooks
docs/CLI.md — full CLI reference, budgets, and manual fallback workflows
docs/MCP.md — the MCP server contract and tool list
docs/TASK-PASSPORT.md — task lifecycle, handoffs, and portable bundles
docs/DEMOS.md — compact continuity demos you can run yourself
docs/VISION.md — the strategic north star
Clone the repo and use Node 20+:
npm ci --ignore-scripts
npm test
npm run mcp:smoke
node dist/src/agentpack.js --helpThis repo uses Agentpack on itself through MCP — docs/DOGFOOD.md describes the working protocol, docs/SETUP.md the full setup, and docs/RELEASING.md the release process.
Mirror: Codeberg. Issues, releases, and npm provenance stay on GitHub.
Store verification output (test results, command output, review findings, notes, or links) as a file under .agentpack/evidence/ plus a ledger event, returning an evidence id to reference from task_update_verification, task_finalize, or record_decision. Call for meaningful verification worth preserving; for small tasks prefer one aggregated evidence item over many per-command items. Provide the body inline via content or from a file via path.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Free-form label such as test, command, note, link, or json. Defaults to note; kind json stores the file with a .json extension. | |
| path | No | Repo-relative path to an existing file whose contents become the evidence body (alternative to content). | |
| command | No | Command that produced the output, stored as metadata. | |
| content | No | Inline evidence body. Ignored when path is set. | |
| exitCode | No | Exit code of that command, stored as metadata. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it writes a file under .agentpack/evidence/ and adds a ledger event, which is useful context beyond the annotations' readOnlyHint=false. However, it does not mention overwrite behavior, whether directories are created, or failure modes. Annotations already cover core traits, so the description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences pack purpose, usage guidance, and parameter interplay without unnecessary detail. It is front-loaded with the primary function and returns an id. Slightly long but every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, when to use it, how to provide evidence (inline or file), and what the id is used for. With no output schema, it doesn't over-explain return values. It could mention that the ledger event is also a record, but overall it is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds key semantics: 'content is ignored when path is set' and 'kind json stores the file with a .json extension' and that command/exitCode are stored as metadata. This goes beyond the schema descriptions and clarifies parameter relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Store') and resource ('verification output as a file under .agentpack/evidence/ plus a ledger event'), and it explains the returned evidence id's purpose for reference from other tools. This clearly distinguishes attach_evidence from siblings like record_decision and task_update_verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to call for meaningful verification worth preserving and provides aggregation guidance ('for small tasks prefer one aggregated evidence item over many per-command items'). It also explains the two input modes (inline content vs. path). It does not name alternative tools when not to use, but the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export one Task Passport with its decisions, dead ends, source conclusions, and optionally evidence to a redacted agentpack.task-bundle JSON file, for sharing tasks across repos, machines, or agents. Writes only the new bundle file at outputPath; pack state is unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | No | Task Passport id to export. Defaults to the current task. | |
| sources | No | Repo-relative source paths whose Source Cache records to include. | |
| outputPath | Yes | Destination bundle file: must be a new repo-relative path outside .agentpack/ and .git/; existing files and symlink escapes are rejected. | |
| includeEvidence | No | Include referenced evidence file contents. Defaults to true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool writes only a new bundle file and leaves pack state unchanged, which is critical side-effect information given all annotation hints are false. It also mentions the output is 'redacted,' adding behavioral nuance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences. The first establishes purpose and scope; the second clarifies the side-effect boundary. No redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 params, full schema coverage, and no output schema, the description adequately covers purpose, output, and side effects. It's sufficient for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters with descriptions (100% coverage). The tool description itself doesn't add parameter details beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports one Task Passport with decisions, dead ends, source conclusions, and optionally evidence to a redacted agentpack.task-bundle JSON file. It distinguishes from siblings like bundle_inspect (inspect) and bundle_import (import) by specifying the export action and sharing purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'for sharing tasks across repos, machines, or agents.' It doesn't explicitly name alternatives or exclusions, but the context is sufficient to infer when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import a task bundle into this pack. By default it only returns the read-only import plan; nothing is written unless write is true. A write import runs under a pack lock, creates a parked task with local verification reset to unknown, retains the bundle and an import manifest, and never changes the current-task pointer. Inspect or plan untrusted bundles first.
| Name | Required | Description | Default |
|---|---|---|---|
| json | No | Return structured JSON instead of formatted text. | |
| path | Yes | Path to the bundle JSON file to import. | |
| asNew | No | Resolve a task-id collision by importing under a deterministic new id. | |
| write | No | Apply the import. When false or omitted, only the read-only plan is returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by detailing that the default is a read-only plan, a write import runs under pack lock, creates a parked task, resets verification to unknown, retains bundle and manifest, and never changes the current-task pointer. This is rich behavioral context not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four well-structured sentences, front-loaded with the purpose, followed by default behavior, write side effects, and a safety note. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description adequately explains the return (read-only plan) and fully discloses the side-effect profile of write mode. It also includes safety guidance, making it complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all four parameters with clear descriptions, including the write param. The description reinforces the write behavior but does not add new parameter-level meaning beyond what the schema provides, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Import a task bundle into this pack' with a specific verb and resource, and distinguishes itself from siblings by explaining the default read-only plan mode and the write behavior, making it distinct from bundle_inspect and bundle_import_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to 'Inspect or plan untrusted bundles first', pointing to alternatives for inspection/planning. It also clarifies when to use write=true for actual import, providing clear context on usage, though it does not name sibling tools directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plan a task bundle import against this pack without writing anything: returns create, idempotent, or conflict actions with an explicit read-only guarantee. Call to preview exactly what bundle_import with write: true would do.
| Name | Required | Description | Default |
|---|---|---|---|
| json | No | Return structured JSON instead of formatted text. | |
| path | Yes | Path to the bundle JSON file to plan against this pack. | |
| asNew | No | Preview importing under a deterministic new task id instead of the bundle's original id (resolves id collisions). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, and the description reinforces with 'without writing anything' and 'explicit read-only guarantee.' It adds behavioral detail about the return: 'create, idempotent, or conflict actions,' which is not in annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. The first sentence states the core function and guarantee; the second gives a direct call-to-action tying to bundle_import.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it's a preview tool with no output schema, the description adequately describes return categories (create/idempotent/conflict) and the read-only nature. It also clarifies the relationship to bundle_import. Minor gaps like error handling are acceptable for this scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (json, path, asNew) is already well-documented. The description adds no additional parameter semantics beyond what the schema provides, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Plan' and identifies the resource 'task bundle import against this pack' with the scope 'without writing anything.' It clearly differentiates from bundle_import by stating it previews what the write would do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call to preview exactly what bundle_import with write: true would do' provides explicit guidance on when to use this tool (as a pre-flight to bundle_import). It implies the alternative is bundle_import for actual execution, though it doesn't explicitly name it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate and summarize an untrusted task bundle file: schema and digest status, origin, included records, and warnings. Read-only — never writes pack state. Call before planning or applying an import of a bundle you did not produce.
| Name | Required | Description | Default |
|---|---|---|---|
| json | No | Return structured JSON instead of formatted text. | |
| path | Yes | Path to the bundle JSON file to inspect. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reinforces the readOnlyHint annotation with the explicit statement 'Read-only — never writes pack state,' adding a concrete behavioral guarantee beyond the annotation. It also signals safety for untrusted files, which is valuable context. The openWorldHint is not contradicted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each packing distinct value: the first describes what the tool does and its output categories, the second provides safety and usage timing. No redundant words; information is front-loaded and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description enumerates the key output categories (schema/digest status, origin, records, warnings) and gives safety guarantees and usage timing. For a read-only inspection tool with full annotations and schema, this is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (path and json) already described clearly in the input schema. The description does not add additional parameter-level meaning—it only mentions 'task bundle file' without elaborating on the path or json flag. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates and summarizes task bundle files, listing specific output aspects (schema and digest status, origin, included records, warnings). The verb 'validate and summarize' plus the resource 'task bundle file' precisely defines the action, and the mention of 'untrusted' and 'before planning or applying an import' distinguishes it from sibling tools like bundle_import_plan and bundle_import.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool: 'Call before planning or applying an import of a bundle you did not produce.' This gives clear contextual guidance. However, it does not explicitly name alternatives or when-not-to-use conditions, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a durable progress checkpoint under .agentpack/checkpoints, capturing summary and git state (branch, commit, diff) and updating the pack-level status and next actions that seed the next session's load_context. Call after meaningful progress, before ending a session, or before risky changes — not after every small step.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Current overall status line, replacing the previous one. | |
| summary | No | What was accomplished and decided since the last checkpoint. | |
| nextActions | No | Concrete next steps, replacing the previous list when non-empty. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds useful context: the checkpoint is durable, captures git state, updates pack-level status/next actions, and seeds the next session's load_context. It does not contradict annotations and provides behavioral detail beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the action and resource, then provides usage timing. Every phrase adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and three well-documented parameters, the description covers purpose, side effects, and usage timing. It could mention what the return value is or explicitly state that previous checkpoints are overwritten, but the schema hints at 'replacing' and the overall context is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters, so the schema already explains them thoroughly. The description reinforces that status and nextActions get updated, but does not add meaning beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Save') and resource ('.agentpack/checkpoints'), and details what is captured (summary and git state) and updated (pack-level status and next actions). This distinguishes it from sibling tools like load_context by explicitly noting it seeds the next session's load_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('after meaningful progress, before ending a session, or before risky changes') and when not to use it ('not after every small step'). This provides strong usage guidance, even though it does not name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two checkpoints, showing their summaries, status lines, and git refs side by side. Defaults to comparing the previous checkpoint against the latest. Call to see what changed between sessions. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Checkpoint id to compare to. Defaults to the latest checkpoint. | |
| from | No | Checkpoint id to compare from. Defaults to the second-most-recent checkpoint. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only, and the description reinforces this with 'Read-only.' It adds behavioral context beyond annotations by describing the default comparison (previous vs latest) and the exact data presented (summaries, status lines, git refs), which is valuable for callers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences. Each sentence contributes either functionality, defaults, or usage guidance. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with full parameter schema coverage and no output schema, the description effectively conveys purpose, usage scenario, default behavior, and output content. It is sufficiently complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully documented in the schema. The description's mention of defaults aligns with the schema but does not add new semantic meaning beyond what schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Compare two checkpoints' with specific output details ('summaries, status lines, and git refs side by side'). This distinct verb+resource combination differentiates it from sibling tools like checkpoint or bundle_inspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: 'Call to see what changed between sessions' and explains default behavior. However, it does not explicitly mention alternatives or when not to use, so it stops 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.
Load a token-budgeted markdown resume of Agentpack state for the current task: Task Passport status and next actions, git state, query-relevant decisions, dead ends, and source conclusions, plus gate warnings when the task lifecycle needs attention. Call once at the start of a session or task, before reading code; re-call only for a different query or budget. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Focused free-text query for the current task. Matching source records keep full summaries; unrelated records collapse to compact stubs to save tokens. | |
| budget | No | Approximate token budget for the resume. Takes precedence over preset. Default 4000. | |
| preset | No | Named token budget: quick (1200), chat (4000), agent (8000), or deep (16000). Use quick for task-start orientation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds 'Read-only' while also revealing token-budgeting behavior and the presence of gate warnings. This goes beyond the annotation by explaining what the resume includes and how the tool handles queries, though the exact output format is not specified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet information-dense, using three sentences to convey the core function, usage frequency, and safety note. Each clause contributes value, and key facts are front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With read-only annotations and a fully described schema, the description explains what the resume contains (status, git, decisions, dead ends, conclusions) and when to call/re-call. Although there is no output schema, the content outline is sufficient for an agent to understand the tool's behavior and expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed param descriptions for query, budget, and preset. The description only references 'query or budget' in usage guidance without adding new semantic detail, so the baseline score of 3 applies as the schema carries the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool loads a token-budgeted markdown resume of Agentpack state, enumerating specific content like Task Passport status, git state, decisions, and gate warnings. This distinguishes it from sibling tools by its start-of-session context-loading purpose and explicit resource scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Call once at the start of a session or task, before reading code; re-call only for a different query or budget.' This establishes when to use the tool, when not to re-call, and the rationale for doing so, though no alternative tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record an approach that failed so future agents do not repeat it. Call when an attempted direction is abandoned for a durable reason, not for ordinary debugging iterations. Writes one event under .agentpack/; secret-like values are redacted.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The approach that was tried and abandoned. | |
| files | No | Repo-relative paths involved in the failed approach. | |
| reason | No | Why it failed or must not be retried. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description carries the burden. It discloses the write side effect ('Writes one event under .agentpack/') and redaction behavior ('secret-like values are redacted'), which goes beyond the minimal annotation information. However, it doesn't mention idempotency explicitly, though annotations already say idempotentHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action. Every word earns its place; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter logging tool with no output schema, the description covers purpose, usage, side effect location, and security behavior. It's fully sufficient for an agent to decide when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds the general context of redaction but doesn't add specific parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb and resource: 'Record an approach that failed.' It also distinguishes from siblings by noting it's for durable abandonments, not debugging iterations, which separates it from record_decision and other logging tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use: 'Call when an attempted direction is abandoned for a durable reason' and when-not-to-use: 'not for ordinary debugging iterations.' This provides clear context without needing to name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a durable technical or product decision to the Agentpack ledger so future sessions inherit it. Call for decisions that matter beyond this session (architecture, contracts, tradeoffs), not for routine preferences or per-edit narration. Writes one event under .agentpack/; secret-like values are redacted.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The decision and its rationale, in one or two sentences. | |
| files | No | Repo-relative paths the decision applies to. | |
| evidence | No | Evidence ids (from attach_evidence) supporting the decision. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotated readOnlyHint=false already indicates a write, but the description adds location ('writes one event under .agentpack/') and a security behavior ('secret-like values are redacted'), which are not present in structured annotations. This provides valuable behavioral context without contradicting any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: the first states the purpose and persistence, the second gives usage boundaries, and the third discloses location and redaction behavior. Every sentence earns its place and is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write tool with no output schema, the description covers purpose, when to use (and not use), the write location, and redaction behavior. This is complete enough for an agent to select and invoke the tool correctly, especially given the high schema coverage and distinction from siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes all three parameters (text, files, evidence) with 100% coverage, so the baseline is 3. The description does not add parameter-specific detail (e.g., format of files or evidence), but the schema is sufficient; the redaction note is general rather than parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses the specific verb 'Append' and names the resource 'technical or product decision to the Agentpack ledger', clearly stating the persistence goal so future sessions inherit it. This distinguishes it from sibling tools like record_dead_end or record_source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call: 'decisions that matter beyond this session (architecture, contracts, tradeoffs)' and when not to: 'not for routine preferences or per-edit narration'. This provides clear usage criteria and exclusions without needing to reference siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a durable conclusion about a source file in the Source Cache: stores the file's current content hash with your summary so future sessions can reuse the conclusion until the file changes. Call after inspecting an important file when the conclusion is reusable; do not record every file read, and re-record only when the conclusion itself changed. Writes under .agentpack/.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Repo-relative path of the inspected file. | |
| snippet | No | Optional short excerpt worth keeping with the conclusion. | |
| summary | No | Durable conclusion about the file. Always provide one; the fallback is a generic 'Reviewed source.' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the write behavior ('Writes under .agentpack/'), the caching mechanism (stores content hash with summary, reusable until file changes), and the durable conclusion nature. These details add meaningful context beyond the annotations, especially given destructiveHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: a clear purpose statement, followed by usage guidance and a storage side note. Every sentence carries useful information without fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set, absence of output schema, and provided annotations, the description is complete: it states what it does, when to use it, where it writes, and the cache invalidation behavior. There are no significant gaps in understanding how to invoke and use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining that 'summary' is always expected with a fallback to a generic 'Reviewed source.' It also clarifies how the summary is used with the content hash, providing value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Record') and resource ('source file in the Source Cache'), explaining the caching mechanism and reuse. It distinguishes itself from sibling tools like record_decision and record_dead_end by focusing on source files and content hashes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given on when to use ('Call after inspecting an important file when the conclusion is reusable') and when not to ('do not record every file read'), plus when to re-record ('only when the conclusion itself changed'). This provides clear context for selecting this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report local release readiness: release metadata, Trusted Publisher wiring, and the manual release-prep commands. Read-only — never pushes, tags, publishes, or creates GitHub Releases. Call when preparing a release, not during routine work.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces and expands this by asserting 'never pushes, tags, publishes, or creates GitHub Releases,' which adds specific side-effect guarantees beyond the generic annotation. It also clarifies the local scope of the report, providing useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose ('Report local release readiness'), followed by content details, a read-only caveat, and usage context. Every sentence earns its place with no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description enumerates the categories of information reported (release metadata, Trusted Publisher wiring, manual release-prep commands), covers the read-only safety profile, and specifies when to call it. For a parameterless report tool, this provides complete context for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is inherently 100%. The description compensates by outlining the content of the report (metadata, Trusted Publisher wiring, commands), giving the agent meaningful expectations for what the tool returns despite having no parameters to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Report'), the subject ('local release readiness'), and specifies the exact content (release metadata, Trusted Publisher wiring, manual release-prep commands). It distinguishes this tool from routine work by noting it's for release preparation, making it distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Call when preparing a release, not during routine work,' providing both a clear when and when-not. However, it does not name any alternative sibling tools, so it stops short of the full 5 which requires explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Print a chronological timeline of recent Agentpack ledger events (decisions, dead ends, evidence, source records, checkpoints, task events), one line per event with timestamp and type. Call to audit how the task history unfolded when a resume is not enough; not part of the routine load_context/checkpoint loop. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of most recent events to show. Defaults to 30. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces with 'Read-only'. It adds useful behavioral detail beyond annotations: one line per event, timestamp/type, and chronological ordering. This helps the agent understand output expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences effectively cover purpose, usage, output format, and read-only nature. Every phrase earns its place with no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter, the description is fully sufficient. It covers event scope, output shape, usage timing, and exclusion from the routine loop, requiring no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'limit' is fully described in the schema (default 30). The description adds no additional meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool prints a chronological timeline of ledger events, listing specific event types and output format. It also differentiates from siblings like resume by noting 'when a resume is not enough'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('audit how the task history unfolded') and when not ('not part of the routine load_context/checkpoint loop'). References resume as the alternative that falls short, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate the same token-budgeted markdown resume as load_context: Task Passport state, git state, query-relevant records, and gate warnings. Prefer load_context at task start; use resume for ad-hoc re-reads with a different query or budget mid-session. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Focused free-text query. Matching source records keep full summaries; unrelated records collapse to compact stubs. | |
| budget | No | Approximate token budget for the resume. Takes precedence over preset. Default 4000. | |
| preset | No | Named token budget: quick (1200), chat (4000), agent (8000), or deep (16000). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context beyond annotations, including the resume contents and that it behaves identically to load_context but with adjustable query/budget. The read-only statement reinforces the annotation without 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and contents, then gives usage guidance and a read-only note. Every sentence serves a purpose with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, contents, usage timing, and safety for a moderate-complexity tool. While no output schema exists, the description adequately implies the markdown resume output. It could have elaborated on exact return formatting or edge cases, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description references 'query or budget' but does not add meaningful parameter detail beyond what the schema already provides for query, budget, and preset.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as generating a token-budgeted markdown resume with specific contents (Task Passport state, git state, query-relevant records, gate warnings). It also explicitly distinguishes resume from load_context by positioning it as the ad-hoc re-read variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: prefer load_context at task start, use resume for mid-session re-reads with different query or budget. This directly addresses when to use the tool vs. alternatives and provides exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether recorded source conclusions are unchanged, changed, or missing by re-hashing the files; use changed/missing filters for stale source-cache triage. Call when you need a full stale-source check beyond what load_context already showed; do not repeat it when a recent load_context, task_audit, or status check answered the question. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| json | No | Return structured JSON instead of formatted text. | |
| changed | No | Only report sources whose content hash changed since recorded. | |
| missing | No | Only report recorded sources whose files no longer exist. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds 'Read-only,' reinforcing that. Beyond annotations, it discloses the mechanism ('by re-hashing the files') and the purpose of filters ('for stale source-cache triage'). This adds meaningful context about how the tool behaves without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a one-word safety indicator. The main action is front-loaded, usage guidance follows, and every phrase earns its place. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with three optional boolean parameters and no output schema, the description covers purpose, usage context, and parameter rationale. It is self-contained and gives the agent enough to decide when to call and what to expect, especially with annotations supporting the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning by connecting 'changed/missing filters' to the tool's purpose ('for stale source-cache triage'), explaining why you'd use those flags. It does not repeat schema descriptions but adds operational context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Check whether recorded source conclusions are unchanged, changed, or missing by re-hashing the files.' It clearly distinguishes itself from siblings like load_context and task_audit by focusing on stale-source checks via re-hashing. The purpose is unambiguous and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'Call when you need a full stale-source check beyond what load_context already showed; do not repeat it when a recent load_context, task_audit, or status check answered the question.' This states both when to use and when not to use, naming alternative tools and providing a clear decision rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit the current Task Passport for continuity risks and advisory-only risk-proportional adversarial-verification evidence (a concrete self-challenge at low risk; independent read-only review and a named disconfirming check at medium/high risk). It does not judge semantic correctness or block lifecycle actions. Call before finalizing, after a long gap, or when drift is suspected; skip when a recent audit already answered it. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| json | No | Return structured JSON instead of formatted text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that the audit is advisory-only, risk-proportional, and independent, and that it neither judges semantic correctness nor blocks lifecycle actions. This adds meaningful behavioral context beyond the structured annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured, starting with the core purpose and then adding usage and safety context. The opening sentence is somewhat jargon-heavy, but every sentence contributes necessary information and the key points are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, when to use, and safety profile, which is strong for a read-only tool with one optional parameter. However, since there is no output schema, it does not explicitly describe what the audit result contains or how it is structured, which is a minor completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single optional boolean parameter is fully documented in the schema with a clear description of its effect. The tool description adds no parameter-specific meaning, but the schema alone is sufficient, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as auditing the current Task Passport for continuity risks and generating advisory-only verification evidence. It explicitly distinguishes itself from lifecycle-mutation tools by stating it does not judge semantic correctness or block lifecycle actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit conditions for when to call the tool ('before finalizing, after a long gap, or when drift is suspected') and when to skip it ('skip when a recent audit already answered it'). This provides actionable selection guidance without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the current Task Passport. Requires verification to already be passed, failed, or accepted, or that final status passed explicitly via status. Use task_park for deferred work instead of closing it; accepted finalization with remaining next actions requires force. Returns non-blocking hygiene and adversarial-verification advisories only; it never judges semantic correctness or blocks completion.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Allow accepted finalization even though next actions remain. | |
| status | No | Final verification status to set while closing. | |
| summary | No | Closing summary; mention relevant commit hashes here. | |
| evidence | No | Evidence ids from attach_evidence backing the final verdict. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds non-obvious behavioral context beyond annotations: it returns only non-blocking hygiene and adversarial-verification advisories, never judges semantic correctness, and does not block completion. This is valuable and complements the destructiveHint and readOnlyHint annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences pack the core action, preconditions, alternatives, force behavior, and return characteristics with no filler. Every sentence earns its place and critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description sufficiently describes the return behavior (non-blocking advisories only). It covers preconditions, alternatives, force semantics, and limits of the tool. A minor gap is not explicitly stating irreversible/destructive finalization, though the annotation and 'Close' imply it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all four parameters at 100%, but the description adds practical insight by linking status to the verification precondition and clarifying that force is required for accepted finalization with remaining next actions. This goes beyond what the schema alone states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Close the current Task Passport') and the resource being acted upon. It also distinguishes itself from task_park by explicitly naming it as the alternative for deferred work, making the tool's purpose immediately recognizable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states explicit usage conditions: verification must already be passed, failed, or accepted, or status must be passed explicitly. It also directs the agent to task_park for deferred work and explains when force is required, eliminating ambiguity about when this tool should be used over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a compact handoff for the current Task Passport — objective, constraints, write scope, next actions, verification, drift, and audit summary — so another chat, client, worktree, or agent can continue the work. Call before switching contexts. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the readOnlyHint annotation by listing what the generated handoff includes and explaining that its purpose is to let another party continue the work. It also confirms 'Read-only,' matching the annotation. It doesn't discuss side effects or failure modes, but for a zero-parameter read-only tool the disclosure is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loaded with the core action and output structure. The first sentence packs the purpose and content list; the second adds a crisp usage instruction. Every word earns its place, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero-parameter schema, the presence of readOnlyHint, and the absence of an output schema, the description is complete: it names the output sections and the exact timing for use. An agent can confidently select and invoke this tool without needing further clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has zero parameters, so the schema fully covers the input side with 100% coverage. The description appropriately focuses on behavior and output content rather than parameter details, meeting the baseline for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Generate a compact handoff for the current Task Passport' — a specific verb and resource — and enumerates the exact sections the handoff contains (objective, constraints, write scope, next actions, verification, drift, audit summary). This clearly differentiates it from sibling tools by focusing on context transfer to another agent, not just status reporting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage trigger: 'Call before switching contexts.' It also specifies the intended audience ('another chat, client, worktree, or agent'). However, it does not explicitly mention when not to use it or contrast with alternatives like checkpoint or task_park, so it's not a full when/when-not guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Task Passports with id, status, title, and branch; the current task is marked with an asterisk. Call to find a task id for task_switch or to review open work. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| json | No | Return structured JSON instead of formatted text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The read-only behavior is already declared via annotations, but the description adds useful context beyond that: the output includes all Task Passports, and the current task is marked with an asterisk. This discloses behavior not present in the annotations and helps the agent anticipate the output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core function, followed by usage guidance and the read-only note. Every sentence contributes value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter and no output schema, the description is complete. It names the fields returned, explains how to identify the current task, and states when to use it. No important information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single optional 'json' parameter with its own description. The tool description does not add additional parameter semantics beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List all Task Passports with id, status, title, and branch.' It uses a specific verb ('List') and resource ('Task Passports'), and includes the exact output fields. It also distinguishes itself from siblings by noting the current task is marked with an asterisk and by referencing task_switch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Call to find a task id for task_switch or to review open work.' This gives a clear scenario for when to use the tool. It does not explicitly mention when not to use it or compare with alternative list tools like task_status, but the guidance is strong enough for a list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark the current Task Passport parked so unrelated work can start without finalizing it. Use for intentionally deferred work: parking preserves verification state and the task can be resumed later with task_switch. Do not park to skip verification of finished work; use task_finalize to close it instead.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds meaningful context: parking preserves verification state and is resumable, and it does not finalize. This goes beyond the annotation to clarify the exact behavioral semantics, though it doesn't mention any authorization needs or additional side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: first states the action and benefit, second explains the intended use case, third provides a critical exclusion. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description fully covers its purpose, usage context, exclusions, and related tools (task_switch, task_finalize). Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, there is no parameter information to add. The baseline for zero-parameter tools is 4, and no additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Mark the current Task Passport parked') and its purpose ('so unrelated work can start without finalizing it'). It distinguishes this tool from siblings by explicitly contrasting with task_finalize and mentioning task_switch for resumption.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance ('intentionally deferred work'), explains what it preserves, and gives a clear exclusion ('Do not park to skip verification of finished work') with the correct alternative tool named (task_finalize). This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Task Passport and make it current, persisting it under .agentpack/. Call when starting a coherent phase of work and no task is active; it refuses to replace an active, blocked, or verifying current task — park or finalize that task first. Declare writeScope so the task gate can protect the task's boundaries.
| Name | Required | Description | Default |
|---|---|---|---|
| risk | No | Risk level of the task. | |
| tags | No | Free-form labels for grouping tasks. | |
| title | Yes | Short imperative task title. | |
| objective | No | What done looks like for this task. | |
| writeScope | No | Repo-relative prefix paths this task is allowed to modify. A directory path includes its children; globs are not supported. | |
| constraints | No | Rules the work must respect. | |
| nextActions | No | Initial concrete next steps. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
All four annotation hints are false, so the description carries the burden of behavioral disclosure. It reveals persistence behavior ('persisting under .agentpack/'), a conditional refusal to overwrite active tasks, and the writeScope gate requirement. These are genuine behavioral traits beyond what the schema or annotations provide. Lacks mention of return values or side effects on failure, but is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, followed by usage conditions and a critical parameter hint. No filler or repetition of schema details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, no output schema, and uninformative annotations, the description covers the essential behavioral contract: creation, persistence, current-task semantics, refusal conditions, and gate interaction. It does not explain return values or error handling, but for a create tool with this richness, it is largely complete. Minor gap: no mention of what happens to an existing current task besides refusal, but that is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by singling out writeScope: 'Declare writeScope so the task gate can protect the task's boundaries' – explaining why this parameter matters and how it interacts with the system. This extra context goes beyond the schema's basic description of the field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new Task Passport and make it current, persisting it under .agentpack/' – a specific verb (create), resource (Task Passport), and outcome (make current). This clearly differentiates it from sibling tools like task_park or task_finalize, which manage existing tasks rather than creating them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call: 'Call when starting a coherent phase of work and no task is active'. It also provides exclusions and alternatives: 'it refuses to replace an active, blocked, or verifying current task — park or finalize that task first'. This gives clear when/when-not guidance and names alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Print a quick summary of the current Task Passport (status, objective, next actions, verification) plus gate warnings, without scanning the source cache. Call for a fast lifecycle check; use task_audit for the full continuity audit. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a specific behavioral trait beyond the readOnlyHint annotation: it does not scan the source cache, which affects performance and output. It also mentions 'gate warnings' as part of the output. However, since the tool is read-only and no side effects exist, the added context is sufficient but not overly rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first tells what it does and its key behavioral constraint, the second gives usage guidance and a read-only note. Every word earns its place, and it is front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, no output schema, and readOnlyHint annotation, the description provides a complete picture: what it returns, when to use it, and the alternative. For a simple read-only snapshot tool, no further information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing to explain. The baseline for 0 params is 4. The description focuses on the output and usage, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Print') and resource ('current Task Passport'), and specifies the exact contents (status, objective, next actions, verification) plus gate warnings. It also distinguishes the tool from siblings by noting it does not scan the source cache and explicitly points to task_audit for a different use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'Call for a fast lifecycle check; use task_audit for the full continuity audit.' This clearly says when to use this tool and which alternative to choose for a different need. The 'without scanning the source cache' further signals it is a lightweight operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make another open Task Passport current by id. A parked target with pending or unknown verification resumes as active; a parked target with a final verdict resumes as verifying and stays frozen until verification returns to pending. Park or finalize a different active, blocked, or verifying current task first; closed tasks cannot be switched to. Updates the current-task pointer under .agentpack/.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Task Passport id to switch to (see task_list). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as destructive, and the description adds detailed state-transition behavior for parked targets with different verification states, plus the side effect of updating the .agentpack/ pointer. This goes beyond the annotation flags for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each focused: purpose, behavioral nuance, and precondition/side effect. Front-loaded with the core action; no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no output schema, the description covers purpose, state transitions, preconditions, and side effects. All necessary operational context is present, handling the tool's complexity well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the 'id' parameter described as 'Task Passport id to switch to (see task_list).' The description adds no additional parameter semantics beyond confirming the id is used, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Make another open Task Passport current by id'), specifying the resource and operation. It distinguishes from siblings like task_start and task_park by focusing on changing the current-task pointer, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states a prerequisite ('Park or finalize a different active, blocked, or verifying current task first') and an exclusion ('closed tasks cannot be switched to'), giving concrete guidance on when it can be invoked. It does not explicitly name alternative tools, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Patch the current Task Passport without changing lifecycle status. List fields (constraints, writeScope, nextActions, tags) append and deduplicate; omitted fields are preserved; empty or no-op updates fail. Pass clearNextActions to replace the next-actions list instead of appending, e.g. to clear a stale plan before finalizing.
| Name | Required | Description | Default |
|---|---|---|---|
| risk | No | New risk level for the task. | |
| tags | No | Free-form labels to append. | |
| objective | No | Replacement objective text. | |
| writeScope | No | Repo-relative prefix paths to append to the write scope. A directory path includes its children; globs are not supported. | |
| constraints | No | Constraints to append. | |
| nextActions | No | Next steps to append, or the full replacement list when clearNextActions is true. | |
| clearNextActions | No | Replace the next actions with the provided nextActions (or clear them) instead of appending. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing key behaviors: list fields append and deduplicate, omitted fields are preserved, empty/no-op updates fail, and clearNextActions switches append to replace. These semantic details are crucial for safe use and are not present in the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, then packs essential behavioral details into two sentences. There is no filler or repetition of schema information; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no output schema), the description covers all critical usage aspects: the general patch behavior, list update semantics, preservation rule, failure condition, and the special replace flag. It is complete enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Though the schema covers each parameter, the description adds important cross-parameter semantics: append-and-deduplicate for all list fields, preservation of omitted fields, the global failure on no-op updates, and the special replace behavior for nextActions. This meaningfully enriches the parameters beyond their individual schema entries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Patch') and resource ('current Task Passport'), and explicitly distinguishes the tool by noting it does not change lifecycle status. It also enumerates the affected fields, making its purpose unmistakable even among many sibling tools that change status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context that this is for updating passport fields without status changes, and gives a concrete use case for clearNextActions ('to clear a stale plan before finalizing'). However, it does not explicitly name alternatives or state when not to use the tool, so it stops short of full 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.
Update the current Task Passport verification state. A final verdict (passed, failed, or accepted) moves the task lifecycle to verifying; pending or unknown returns it to active. Call after attach_evidence so the verdict is evidence-backed; identical repeated calls are no-ops.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Verification status to set. | |
| summary | No | Short summary of what was verified and how. | |
| evidence | No | Evidence ids from attach_evidence backing this verdict. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'identical repeated calls are no-ops,' which directly contradicts the idempotentHint=false annotation. It also fails to address the destructiveHint=true annotation, leaving potentially destructive behavior undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, lifecycle effects, and sequencing/idempotency. No filler or redundancy, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core purpose, state transitions, and call sequence, but given the no-output-schema and destructiveHint=true annotations, it omits return value, potential destructive side effects, and error/failure handling. This is a significant gap for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers all parameters, but description adds meaningful context: it distinguishes 'passed, failed, or accepted' as final verdicts versus 'pending or unknown' that reset to active, and links evidence to attach_evidence. This enhances understanding beyond the terse schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Update') and resource ('current Task Passport verification state'), clearly distinguishing it from general task tools like task_update. It also defines the scope with lifecycle effects, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context by instructing to call after attach_evidence and explaining lifecycle transitions for final vs non-final statuses. However, it does not mention when not to use the tool or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.5.0task_rolev1.4.0attach_evidence5 fields changedInput schema / properties / command / descriptionAdded value: +"Command that produced the output, stored as metadata."Input schema / properties / content / descriptionAdded value: +"Inline evidence body. Ignored when path is set."Input schema / properties / exitCode / descriptionAdded value: +"Exit code of that command, stored as metadata."Input schema / properties / kind / descriptionAdded value: +"Free-form label such as test, command, note, link, or json. Defaults to note; kind json stores the file with a .json extension."Input schema / properties / path / descriptionAdded value: +"Repo-relative path to an existing file whose contents become the evidence body (alternative to content)."bundle_export4 fields changedInput schema / properties / includeEvidence / descriptionAdded value: +"Include referenced evidence file contents. Defaults to true."Input schema / properties / outputPath / descriptionAdded value: +"Destination bundle file: must be a new repo-relative path outside .agentpack/ and .git/; existing files and symlink escapes are rejected."Input schema / properties / sources / descriptionAdded value: +"Repo-relative source paths whose Source Cache records to include."Input schema / properties / taskId / descriptionAdded value: +"Task Passport id to export. Defaults to the current task."bundle_import4 fields changedInput schema / properties / asNew / descriptionAdded value: +"Resolve a task-id collision by importing under a deterministic new id."Input schema / properties / json / descriptionAdded value: +"Return structured JSON instead of formatted text."Input schema / properties / path / descriptionAdded value: +"Path to the bundle JSON file to import."Input schema / properties / write / descriptionAdded value: +"Apply the import. When false or omitted, only the read-only plan is returned."bundle_import_plan3 fields changedInput schema / properties / asNew / descriptionAdded value: +"Preview importing under a deterministic new task id instead of the bundle's original id (resolves id collisions)."Input schema / properties / json / descriptionAdded value: +"Return structured JSON instead of formatted text."Input schema / properties / path / descriptionAdded value: +"Path to the bundle JSON file to plan against this pack."bundle_inspect2 fields changedInput schema / properties / json / descriptionAdded value: +"Return structured JSON instead of formatted text."Input schema / properties / path / descriptionAdded value: +"Path to the bundle JSON file to inspect."checkpoint3 fields changedInput schema / properties / nextActions / descriptionAdded value: +"Concrete next steps, replacing the previous list when non-empty."Input schema / properties / status / descriptionAdded value: +"Current overall status line, replacing the previous one."Input schema / properties / summary / descriptionAdded value: +"What was accomplished and decided since the last checkpoint."diff2 fields changedInput schema / properties / from / descriptionAdded value: +"Checkpoint id to compare from. Defaults to the second-most-recent checkpoint."Input schema / properties / to / descriptionAdded value: +"Checkpoint id to compare to. Defaults to the latest checkpoint."load_context3 fields changedInput schema / properties / budget / descriptionAdded value: +"Approximate token budget for the resume. Takes precedence over preset. Default 4000."Input schema / properties / preset / descriptionAdded value: +"Named token budget: quick (1200), chat (4000), agent (8000), or deep (16000). Use quick for task-start orientation."Input schema / properties / query / descriptionAdded value: +"Focused free-text query for the current task. Matching source records keep full summaries; unrelated records collapse to compact stubs to save tokens."record_dead_end3 fields changedInput schema / properties / files / descriptionAdded value: +"Repo-relative paths involved in the failed approach."Input schema / properties / reason / descriptionAdded value: +"Why it failed or must not be retried."Input schema / properties / text / descriptionAdded value: +"The approach that was tried and abandoned."record_decision3 fields changedInput schema / properties / evidence / descriptionAdded value: +"Evidence ids (from attach_evidence) supporting the decision."Input schema / properties / files / descriptionAdded value: +"Repo-relative paths the decision applies to."Input schema / properties / text / descriptionAdded value: +"The decision and its rationale, in one or two sentences."record_source3 fields changedInput schema / properties / path / descriptionAdded value: +"Repo-relative path of the inspected file."Input schema / properties / snippet / descriptionAdded value: +"Optional short excerpt worth keeping with the conclusion."Input schema / properties / summary / descriptionAdded value: +"Durable conclusion about the file. Always provide one; the fallback is a generic 'Reviewed source.'"replay1 field changedInput schema / properties / limit / descriptionAdded value: +"Number of most recent events to show. Defaults to 30."resume3 fields changedInput schema / properties / budget / descriptionAdded value: +"Approximate token budget for the resume. Takes precedence over preset. Default 4000."Input schema / properties / preset / descriptionAdded value: +"Named token budget: quick (1200), chat (4000), agent (8000), or deep (16000)."Input schema / properties / query / descriptionAdded value: +"Focused free-text query. Matching source records keep full summaries; unrelated records collapse to compact stubs."source_status3 fields changedInput schema / properties / changed / descriptionAdded value: +"Only report sources whose content hash changed since recorded."Input schema / properties / json / descriptionAdded value: +"Return structured JSON instead of formatted text."Input schema / properties / missing / descriptionAdded value: +"Only report recorded sources whose files no longer exist."task_audit1 field changedInput schema / properties / json / descriptionAdded value: +"Return structured JSON instead of formatted text."task_finalize4 fields changedInput schema / properties / evidence / descriptionAdded value: +"Evidence ids from attach_evidence backing the final verdict."Input schema / properties / force / descriptionAdded value: +"Allow accepted finalization even though next actions remain."Input schema / properties / status / descriptionAdded value: +"Final verification status to set while closing."Input schema / properties / summary / descriptionAdded value: +"Closing summary; mention relevant commit hashes here."task_list1 field changedInput schema / properties / json / descriptionAdded value: +"Return structured JSON instead of formatted text."task_role4 fields changedInput schema / properties / json / descriptionAdded value: +"Return structured JSON instead of formatted text."Input schema / properties / role / descriptionAdded value: +"Role lane to read or update."Input schema / properties / status / descriptionAdded value: +"New lane status; requires summary in the same call."Input schema / properties / summary / descriptionAdded value: +"Durable summary of the lane's state; requires status in the same call."task_start7 fields changedInput schema / properties / constraints / descriptionAdded value: +"Rules the work must respect."Input schema / properties / nextActions / descriptionAdded value: +"Initial concrete next steps."Input schema / properties / objective / descriptionAdded value: +"What done looks like for this task."Input schema / properties / risk / descriptionAdded value: +"Risk level of the task."Input schema / properties / tags / descriptionAdded value: +"Free-form labels for grouping tasks."Input schema / properties / title / descriptionAdded value: +"Short imperative task title."Input schema / properties / writeScope / descriptionAdded value: +"Repo-relative prefix paths this task is allowed to modify. A directory path includes its children; globs are not supported."task_switch1 field changedInput schema / properties / id / descriptionAdded value: +"Task Passport id to switch to (see task_list)."task_update7 fields changedInput schema / properties / clearNextActions / descriptionAdded value: +"Replace the next actions with the provided nextActions (or clear them) instead of appending."Input schema / properties / constraints / descriptionAdded value: +"Constraints to append."Input schema / properties / nextActions / descriptionAdded value: +"Next steps to append, or the full replacement list when clearNextActions is true."Input schema / properties / objective / descriptionAdded value: +"Replacement objective text."Input schema / properties / risk / descriptionAdded value: +"New risk level for the task."Input schema / properties / tags / descriptionAdded value: +"Free-form labels to append."Input schema / properties / writeScope / descriptionAdded value: +"Repo-relative prefix paths to append to the write scope. A directory path includes its children; globs are not supported."task_update_verification3 fields changedInput schema / properties / evidence / descriptionAdded value: +"Evidence ids from attach_evidence backing this verdict."Input schema / properties / status / descriptionAdded value: +"Verification status to set."Input schema / properties / summary / descriptionAdded value: +"Short summary of what was verified and how."v1.3.0attach_evidencebundle_exportbundle_importbundle_import_planbundle_inspectcheckpointdiffload_contextrecord_dead_endrecord_decisionrecord_sourcerelease_preflightreplayresumesource_statustask_audittask_finalizetask_handofftask_listtask_parktask_roletask_starttask_statustask_switchtask_updatetask_update_verificationMost tools have clear distinct purposes. The only potential confusion is between load_context and resume, but descriptions differentiate them (session start vs. ad-hoc re-read). Overall, agents can easily distinguish tools.
All tools follow a consistent verb_noun snake_case pattern (e.g., attach_evidence, task_start, bundle_export). No mixing of conventions.
26 tools is on the higher side but appropriate for the comprehensive workflow management domain. Some tools could be merged (e.g., load_context and resume) but each has a specific use case.
Covers task lifecycle, evidence, checkpoints, source caching, bundles, and release preflight thoroughly. Minor gaps like evidence retrieval or task deletion tools are absent but not critical.
MCP server for agentverse documentation, generated by doc2mcp.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Create guides as MCP servers to instruct coding agents to use your software (library, API, etc).
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ihorponom/agentpack'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
