Chronicle MCP

Overview Schema Source Related Servers Discussions Admin

Search Chat History

search_history

Read-onlyIdempotent

Search the local chat archive to find transcript chunks for recalling past work; supports semantic, keyword, date-range, and related-chat queries.

Instructions

Search the local chat archive and return matching transcript chunks. Use this first to recall past work on a topic; then read a hit with get_chat_logs. For extracted action items, comparisons or briefs use compile_project_insights instead. Methods: 'semantic' (default) ranks chunks with Okapi BM25 plus recency decay and returns [{file, score}]; 'keyword' returns chunk ids containing every keyword; 'date_range' returns [{file_name, last_modified}] for chats saved between start_date and end_date; 'related' returns [{file, score}] for chats similar to file_name. Chunk ids look like 'name__part_2.json' and can be passed to get_chat_logs as chat_id. Active handoff receipts are ranked first. Read-only for chat data; it refreshes the local search index cache. An empty archive returns a single placeholder entry such as 'No stored chats found.'.

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum results for 'keyword' and 'date_range' searches.
`query`	No	Free-text query for 'semantic' search; for 'keyword' it is split on spaces when 'keywords' is omitted.
`top_k`	No	Maximum results for 'semantic' and 'related' searches.
`client`	No	Archive namespace (a subfolder of the chats directory). Built-in: 'default', 'cursor', 'chatgpt', 'claude'; any other name creates its own subfolder. Omit to use 'default'.	default
`method`	No	Search strategy (see the tool description).	semantic
`end_date`	No	Inclusive end date (YYYY-MM-DD, UTC) for method='date_range'. Required with start_date.
`keywords`	No	Exact terms for method='keyword'; all must appear. Overrides 'query' for that method.
`file_name`	No	Reference chat file for method='related' (for example 'my-chat.json'). Falls back to 'query'.
`start_date`	No	Inclusive start date (YYYY-MM-DD, UTC) for method='date_range'. Required with end_date.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv1.6.2Oct 22, 2026

addedInput schema / properties / client / description

Added value: +"Archive namespace (a subfolder of the chats directory). Built-in: 'default', 'cursor', 'chatgpt', 'claude'; any other name creates its own subfolder. Omit to use 'default'."

addedInput schema / properties / end_date / description

Added value: +"Inclusive end date (YYYY-MM-DD, UTC) for method='date_range'. Required with start_date."

addedInput schema / properties / file_name / description

Added value: +"Reference chat file for method='related' (for example 'my-chat.json'). Falls back to 'query'."

addedInput schema / properties / keywords / description

Added value: +"Exact terms for method='keyword'; all must appear. Overrides 'query' for that method."

addedInput schema / properties / limit / description

Added value: +"Maximum results for 'keyword' and 'date_range' searches."

addedInput schema / properties / limit / minimum
```
Added value: +1
```

addedInput schema / properties / method / description

Added value: +"Search strategy (see the tool description)."

addedInput schema / properties / method / enum

Added value: +[
+  "semantic",
+  "keyword",
+  "date_range",
+  "related"
+]

addedInput schema / properties / query / description

Added value: +"Free-text query for 'semantic' search; for 'keyword' it is split on spaces when 'keywords' is omitted."

addedInput schema / properties / start_date / description

Added value: +"Inclusive start date (YYYY-MM-DD, UTC) for method='date_range'. Required with end_date."

addedInput schema / properties / top_k / description

Added value: +"Maximum results for 'semantic' and 'related' searches."

addedInput schema / properties / top_k / minimum
```
Added value: +1
```

First observedv1.5.4Jun 29, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds non-obvious traits beyond them: active handoff receipts are ranked first, the search index cache is refreshed as a side effect, and an empty archive returns a placeholder entry rather than nothing. These are real behaviors an agent could not predict from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and sibling routing before the method catalogue, and each sentence carries information. It is dense and long — the method list plus return shapes plus cache note plus empty-archive case is a lot for one description — but little is genuinely wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter multi-method search tool, the description supplies method selection, return shape per method, id handoff to get_chat_logs, ranking behavior, and the empty-result edge case. An output schema exists, but the extra return detail supports correct method choice rather than duplicating it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 earns a point by explaining cross-parameter behavior the schema does not — that chunk ids like 'name__part_2.json' can be passed to get_chat_logs as chat_id, and by mapping each method to its distinct return shape. It does not discuss limit vs top_k, leaving that to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('search the local chat archive and return matching transcript chunks') and immediately distinguishes itself from get_chat_logs (read a hit) and compile_project_insights (derived outputs). The four search methods further pin down the resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this first to recall past work on a topic; then read a hit with get_chat_logs' gives an explicit ordering, and 'For extracted action items, comparisons or briefs use compile_project_insights instead' names the alternative and the condition selecting it. Method-level guidance is also spelled out per case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server