Skip to content

✨ feat: rich MCP tool metadata — annotations, param descriptions, usage guidance (WP13) - #11

Merged
Wuesteon merged 3 commits into
mainfrom
worktree-wp12-mcp-tool-metadata
Jul 29, 2026
Merged

Wuesteon merged 3 commits into
mainfrom
worktree-wp12-mcp-tool-metadata

Conversation

@Wuesteon

Copy link
Copy Markdown
Owner

Why

The Glama directory audit scores each MCP tool on exactly what tools/list ships, and graded us down hard: memory_search 3.2/5, memory_add 3.3/5 — Behavior 2/5 ("No annotations are present"), Parameters 2/5 ("Schema coverage is 0%"), Usage Guidelines 2/5 (no when-to-use-vs-alternatives). The cause: one-line docstrings and bare type hints, so FastMCP shipped schemas with zero parameter descriptions and no annotations. Notably, memory_clear — the tool with a rich docstring — scored highest (3.6, "A"), confirming the diagnosis.

What

All seven tools in src/lean_memory/mcp_server.py now ship:

  • ToolAnnotations, honest per tool: readOnlyHint=True for search/status; destructiveHint=True, idempotentHint=True for clear; readOnlyHint=False on memory_review_queue because listing lazily expires overdue proposals (a write); openWorldHint=False everywhere (local SQLite, closed world).
  • A description on every inputSchema parameter via Annotated[..., Field(description=...)], including a shared definition of what a namespace is (isolation key → one local SQLite file).
  • Usage guidance + side-effect disclosure in the tool descriptions: add distills facts rather than storing raw text; the one-time first-call model download with the [models]/[extract] extras; search's empty-store-file side effect on a missing namespace; sibling cross-references (search ↔ add ↔ clear, queue → decide).

No call-behavior change except memory_search.k and memory_review_queue.limit now declare a schema minimum of 1.

Contract test

tests/test_mcp_tool_metadata.py (18 tests, TDD — watched red then green) pins the whole surface: annotation correctness per tool, 100% parameter-description coverage, namespace semantics everywhere, cross-references, and side-effect disclosure. The set-equality pin goes red if a tool is added or dropped without metadata.

Verification

  • Core: 319 passed (was 301 baseline)
  • Console: 153 passed (parity tests pin names + param sets only; both unchanged)
  • Manually dumped the tools/list wire payload via an in-memory client session to confirm descriptions, param descriptions, and minimum land as served

Out of scope

The console stdio wrapper (observe_mcp.py, routes/mcp.py, lane D) defines its own tool metadata; if lean-memory-console is also directory-graded it deserves the same treatment as a follow-up. Glama re-scans on release, so the score improves when this ships in the next tag.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VgxNBms5npMWXD2krUofs3

Wuesteon and others added 3 commits July 29, 2026 14:48
…ge guidance (WP12)

Directory graders (Glama audit: memory_search 3.2/5, memory_add 3.3/5) and
agent clients judge tools on exactly what tools/list ships. All seven server
tools now declare honest ToolAnnotations (readOnly/destructive/idempotent,
openWorldHint=False), describe every inputSchema parameter (was 0% coverage),
cross-reference sibling tools for when-to-use guidance, and disclose side
effects: extraction on add, first-call model download, the empty-store file a
search can create, and review_queue's lazy proposal expiry.

No call-behavior change except memory_search.k and memory_review_queue.limit
now carry a schema minimum of 1. Contract pinned in
tests/test_mcp_tool_metadata.py (18 tests; core 319 + console 153 green).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VgxNBms5npMWXD2krUofs3
Resolves the import-block conflict in mcp_server.py: keep the compat
factory (make_stdio_server) AND the metadata imports (ToolAnnotations,
Field). Renumbers this packet WP12 → WP13 — the mcp 2.0 migration claimed
WP12 concurrently and merged first (PR #10).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VgxNBms5npMWXD2krUofs3
…p majors

mcp 2.0 renamed ToolAnnotations fields to snake_case with camelCase
serialization aliases; attribute reads like .readOnlyHint only exist on
1.x. model_dump(by_alias=True) yields the camelCase wire names on both
majors. Full core suite verified green under mcp 1.28.0 and 2.0.0
(scratch venv), with the served tools/list payload spot-checked on 2.0.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VgxNBms5npMWXD2krUofs3
@Wuesteon Wuesteon changed the title ✨ feat: rich MCP tool metadata — annotations, param descriptions, usage guidance (WP12) ✨ feat: rich MCP tool metadata — annotations, param descriptions, usage guidance (WP13) Jul 29, 2026
@Wuesteon

Copy link
Copy Markdown
Owner Author

Renumbered WP12 → WP13: the mcp 2.0 dual-path migration (PR #10) claimed WP12 concurrently and merged first. main is merged into this branch (one import-block conflict resolved: compat factory + metadata imports coexist). Verified on both SDK majors: core 319 passed on mcp 1.28.0, 318 passed + 1 skipped on mcp 2.0.0 (scratch venv), console 153 passed; tools/list payload spot-checked on 2.0 — camelCase annotation hints and 100% param descriptions serialize correctly (the annotation test asserts via model_dump(by_alias=True), valid on both majors).

@Wuesteon
Wuesteon merged commit 342461e into main Jul 29, 2026
6 checks passed
@Wuesteon
Wuesteon deleted the worktree-wp12-mcp-tool-metadata branch July 29, 2026 07:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant