Phase 4: Add include_cold param to list_notes tool

forgejo_admin commented

2026-03-17 03:26:02 +00:00

Owner

Lineage

plan-2026-03-16-knowledge-architecture → Phase 4 (Knowledge Tiering) → MCP tool passthrough

Repo

forgejo_admin/pal-e-docs-mcp

User Story

As a Claude agent calling the list_notes MCP tool,
I want an include_cold parameter with a clear description,
so that I can opt into seeing completed/historical notes when researching provenance.

Context

PR #191 on pal-e-docs added include_cold boolean query param to GET /notes (default false). The SDK (separate PR on pal-e-docs-sdk) exposes it as include_cold: bool = False. The MCP tool needs to add the param with a descriptive Field so agents understand what cold notes are and when to include them.

File Targets

Files to modify:

src/pal_e_docs_mcp/tools/notes.py line 14-48 (list_notes tool) — add include_cold: Annotated[bool, Field(...)] param with description explaining cold exclusion. Pass it to get_sdk().list_notes(include_cold=include_cold).
Update the tool docstring to mention that cold notes are excluded by default.

Files NOT to touch:

Everything else — this is a passthrough param addition only

Acceptance Criteria

list_notes MCP tool has an include_cold param with default False
Field description explains: "Include cold (completed/done/deprecated/deferred/archived) notes. Default false — cold notes are excluded to reduce token cost. Use true when researching historical decisions or provenance."
Tool docstring mentions cold exclusion behavior
include_cold is passed through to get_sdk().list_notes()
All existing tests pass
ruff format and ruff check clean

Test Expectations

Param alignment test passes (if one exists for list_notes params)
Existing tests pass
Run command: pytest tests/ -x -q

Constraints

Match existing Annotated[..., Field(...)] pattern used by other params
Place include_cold param after parent_slug (before any future params)
Do not change any other tools or files

Checklist

PR opened
Tests pass
No unrelated changes

project-pal-e-docs — project this affects
plan-2026-03-16-knowledge-architecture — parent plan
pal-e-docs PR #191 — backend that added the include_cold API param

### Lineage `plan-2026-03-16-knowledge-architecture` → Phase 4 (Knowledge Tiering) → MCP tool passthrough ### Repo `forgejo_admin/pal-e-docs-mcp` ### User Story As a Claude agent calling the `list_notes` MCP tool, I want an `include_cold` parameter with a clear description, so that I can opt into seeing completed/historical notes when researching provenance. ### Context PR #191 on pal-e-docs added `include_cold` boolean query param to `GET /notes` (default false). The SDK (separate PR on pal-e-docs-sdk) exposes it as `include_cold: bool = False`. The MCP tool needs to add the param with a descriptive Field so agents understand what cold notes are and when to include them. ### File Targets Files to modify: - `src/pal_e_docs_mcp/tools/notes.py` line 14-48 (`list_notes` tool) — add `include_cold: Annotated[bool, Field(...)]` param with description explaining cold exclusion. Pass it to `get_sdk().list_notes(include_cold=include_cold)`. - Update the tool docstring to mention that cold notes are excluded by default. Files NOT to touch: - Everything else — this is a passthrough param addition only ### Acceptance Criteria - [ ] `list_notes` MCP tool has an `include_cold` param with default `False` - [ ] Field description explains: "Include cold (completed/done/deprecated/deferred/archived) notes. Default false — cold notes are excluded to reduce token cost. Use true when researching historical decisions or provenance." - [ ] Tool docstring mentions cold exclusion behavior - [ ] `include_cold` is passed through to `get_sdk().list_notes()` - [ ] All existing tests pass - [ ] `ruff format` and `ruff check` clean ### Test Expectations - [ ] Param alignment test passes (if one exists for list_notes params) - [ ] Existing tests pass - Run command: `pytest tests/ -x -q` ### Constraints - Match existing Annotated[..., Field(...)] pattern used by other params - Place `include_cold` param after `parent_slug` (before any future params) - Do not change any other tools or files ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-pal-e-docs` — project this affects - `plan-2026-03-16-knowledge-architecture` — parent plan - pal-e-docs PR #191 — backend that added the `include_cold` API param