• The beans_query tool is intentionally broad: prefer it for listing, searching, filtering or sorting beans, and for generating Copilot instructions (operation: 'llm_context').
• All file and log operations validate paths to keep them within the workspace or the VS Code log directory. The .beans/ prefix is automatically stripped from paths — you can pass either some-bean.md or .beans/some-bean.md and the result is the same.
• beans_update replaces many fine-grained update tools; callers should use it to keep the public tool surface small and predictable.
• beans_archive provides CLI parity for archiving completed/scrapped beans.
• Closing a parent bean via beans_update (status: completed or status: scrapped) cascades the same status to all descendants.
• Reopening a parent bean via beans_reopen cascades the target status to closed descendants (completed / scrapped).
• beans_bulk_create and beans_bulk_update are best-effort: they process each item sequentially and return a per-item result array with success/error entries rather than failing atomically.
• Frontmatter title: values are automatically double-quoted on write. Pass raw titles — quoting and escaping is handled for you.
• beans_bean_file supports update_frontmatter for atomic frontmatter-only writes; supported fields include pr and branch.
• Unfiltered list results are cached with a short burst TTL and a timestamp-probe refresh strategy. Mutation tools (beans_create, beans_update, beans_delete, etc.) invalidate the cache immediately.
• Version mismatches between beans-mcp and the Beans CLI are warning-only and non-blocking by design.
• When beanId is missing in tool input, validation errors include a hint: Did you mean \beanId`?`.

Request:

{ "prefix": "project" }

Response (structuredContent):

{ "initialized": true }

Request:

{ "beanId": "bean-abc" }

Request (multiple beans):

{ "beanIds": ["bean-abc", "bean-def"] }

Response (structuredContent):

{
  "bean": {
    "id": "bean-abc",
    "title": "Fix login timeout",
    "status": "todo",
    "type": "bug",
    "priority": "critical",
    "body": "...markdown...",
    "createdAt": "2025-12-01T12:00:00Z",
    "updatedAt": "2025-12-02T08:00:00Z"
  }
}

Request:

{}

Response (example):

{ "archived": true, "archivedCount": 3 }

Request:

{
  "title": "Add dark mode",
  "type": "feature",
  "status": "todo",
  "priority": "normal",
  "body": "Implement theme toggle and styles",
  "parent": "epic-123"
}

description is accepted as a deprecated alias for body.

Response (structuredContent):

{
  "bean": {
    "id": "new-1",
    "title": "Add dark mode",
    "status": "todo",
    "type": "feature"
  }
}

Request:

{
  "parent": "epic-123",
  "beans": [
    { "title": "Design mockups", "type": "task" },
    { "title": "Implement API", "type": "task", "priority": "high" },
    { "title": "Write tests", "type": "task", "parent": "epic-456" }
  ]
}

The top-level parent is applied as a default to any bean that does not specify its own parent. Here Design mockups and Implement API are assigned to epic-123; Write tests overrides with epic-456.

Response (structuredContent):

{
  "requestedCount": 3,
  "successCount": 3,
  "failedCount": 0,
  "results": [
    { "bean": { "id": "task-1", "title": "Design mockups" } },
    { "bean": { "id": "task-2", "title": "Implement API" } },
    { "bean": { "id": "task-3", "title": "Write tests" } }
  ]
}

Request (move a batch of tasks to in-progress and assign them to a parent):

{
  "parent": "epic-123",
  "beans": [
    { "beanId": "task-1", "status": "in-progress" },
    { "beanId": "task-2", "status": "in-progress" },
    { "beanId": "task-3", "status": "in-progress", "parent": "epic-456" }
  ]
}

Response (structuredContent):

{
  "requestedCount": 3,
  "successCount": 3,
  "failedCount": 0,
  "results": [
    { "beanId": "task-1", "bean": { "id": "task-1", "status": "in-progress" } },
    { "beanId": "task-2", "bean": { "id": "task-2", "status": "in-progress" } },
    { "beanId": "task-3", "bean": { "id": "task-3", "status": "in-progress" } }
  ]
}

Both bulk tools are best-effort: partial failures are reported per-item rather than aborting the whole batch.

Request (change status and add blocking):

{
  "beanId": "bean-abc",
  "status": "in-progress",
  "blocking": ["bean-def"],
  "ifMatch": "etag-value"
}

Request (atomic body modifications):