claude_code_conversation_history

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

With no annotations, the description fully carries the behavioral burden. It reveals key behaviors: global search scope, BM25 keyword search, message truncation to 500 chars with contentLength, and distinct modes (browse/focus/grep) with their pagination and filtering semantics. This goes far beyond the schema.

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

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

The description is well-structured: it opens with the core purpose, then contrasts with alternatives, gives concrete use cases, and breaks down each action with its parameters and modes. Every sentence provides useful information, avoiding redundancy or fluff.

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

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

The description covers all actions, their required and optional parameters, and special modes, making it highly usable. However, since there is no output schema, it does not fully describe the return structure for stats/list results, leaving a minor gap in expected output understanding.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 88% schema coverage, the description adds contextual meaning that the schema lacks, such as 'search requires query', 'read requires session_id', and how offset/limit interact in browse mode or how limit=1 enables focus mode. This explains parameter combinations and conditional usage effectively.

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

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

The description clearly states the tool's purpose: 'Search across ALL past Claude Code conversations, not just the current one.' This uses a specific verb (Search) and resource (conversations), and immediately distinguishes it from the current conversation and from alternatives like git log and memory.

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

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

The description includes a dedicated 'Use when:' section that lists concrete triggers ('User asks about past work, previous sessions, "what did we do", "remember when"'), and explicitly states 'Always use this first, not git log,' providing clear when-to-use and when-not-to-use guidance.

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