Reset Conversation History

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

Annotations only give readOnlyHint: false, indicating a mutation. The description goes beyond this by specifying exactly what is mutated (session dialogue) and what is preserved (crystallized knowledge, facts, weights). It adds valuable context about the side-effect scope, though it does not cover potential edge cases like timeouts or effects on concurrent sessions.

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 two terse sentences plus a usage directive. The core action is front-loaded ('Resets conversational dialogue history'), followed by the preserving qualifier and the usage scenario. No filler or redundancy; every clause earns its place.

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?

Given the tool's simplicity (one optional param, no required fields) and the presence of an output schema, the description covers purpose, side effects, and usage context. It does not describe the return value, but the output schema covers that. Minor omission: it doesn't explain what happens if the space_id is invalid or if resets affect multiple sessions, but these are not essential for basic usage.

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?

The schema covers the sole parameter space_id with a clear description ('Optional memory space partition whose turn history should be reset. Defaults to caller default space.'). The tool description adds no additional meaning about the parameter beyond what the schema provides. With 100% schema coverage, baseline 3 is appropriate.

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 verb ('Resets') and the resource ('conversational dialogue history') while adding a critical qualifier: it preserves all crystallized knowledge and memory weights. This distinguishes it from siblings like icx_search_facts or icx_recall_scoped, which interact with long-term memory rather than session state. The final sentence reinforces the specific scope of the mutation.

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?

Explicitly provides a when-to-use scenario: 'Use when starting a new conversation topic while retaining all learned knowledge.' It also clarifies what is not reset (persistent memory). However, it does not explicitly name alternative tools (e.g., 'for full memory reset, use X') or state when not to use it, so it's slightly below the highest bar.

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