Cline rules

1---
2paths:
3  - "src/pubmed_search/presentation/mcp_server/**"
4  - "src/pubmed_search/application/**"
5  - "src/pubmed_search/infrastructure/sources/**"
6  - "scripts/count_mcp_tools.py"
7  - ".claude/skills/pubmed-mcp-tools-reference/SKILL.md"
8---
9 
10# PubMed MCP Tool Rules
11 
12## Tool Contract Rules
13 
14- Keep MCP `unified_search` as the primary agent search facade; Python callers should use `pubmed_search.api`.
15- Preserve session-aware flows: cached articles, last PMIDs, search history, and pipeline state.
16- Return source counts and warnings when a source fails or contributes zero results.
17- Keep output formats stable for markdown, JSON, RIS, BibTeX, CSV, and MEDLINE.
18- Do not remove old fields without tolerating them for at least one release cycle.
19 
20## Research Workflow Rules
21 
22- Use `generate_search_queries` and `analyze_search_query` before complex/systematic searches.
23- For clinical comparison questions, extract P/I/C/O in the agent, then use `parse_pico` to validate the structured handoff and obtain a runnable PICO pipeline.
24- `build_research_chronicle` is the single research-evolution entry point; the old timeline tools were folded into it. Read stored chronicles with `read_research_chronicle` (`load` / `list` / `diff` / `narrate` / `milestones` / `compare`) instead of rebuilding.
25- When `unified_search` returns an `artifact_summary`, preserve the user-facing summary and use `read_session(action="artifact", artifact_uri=...)` for deeper audit files.
26- Use `get_fulltext`, `get_article_figures`, and institutional access tools only when full-text retrieval is requested.
27- Export to RIS for Zotero/EndNote and BibTeX for LaTeX workflows.
28 
29## Tenant Isolation Rules
30 
31The server can serve many agents at once, so session state must stay scoped:
32 
33- Resolve session state through `get_session_manager()`. Never capture a `SessionManager` in a closure at registration time; it would pin every caller to the startup tenant.
34- `set_session_manager()` intentionally clears the per-tenant registry (single-caller mode). Anything that installs the registry must run *after* tool registration.
35- `normalize_tenant_id()` must stay idempotent; the registry re-normalizes ids.
36- Keep upstream per-API rate limits global (NCBI meters per API key). Per-caller fairness belongs to `PUBMED_TENANT_MAX_CONCURRENCY`.
37- Any new store that writes under `data_dir` must route through the tenant's directory, not the shared root.
38 
39## Documentation Sync
40 
41When tools are added, removed, or renamed:
42 
43- Run `uv run python scripts/count_mcp_tools.py --update-docs`.
44- Update relevant `.claude/skills/pubmed-*` skills.
45- Update `.github/agents/research.agent.md` if the research flow changes.
46- Add or update MCP protocol tests.
47