session.reset

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

Description adds meaningful context beyond annotations: clarifies that chat history is destroyed (consistent with destructiveHint=true) and that the session ID persists. Also advises user consent, which is not in annotations.

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?

Two sentences: first defines the operation, second provides usage guidance. No extraneous words, highly efficient.

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?

Covers purpose, usage, and behavior. With output schema present, return details are unnecessary. Lacks explicit mention of prerequisites or error conditions, but overall complete for a simple reset tool.

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?

Schema provides parameter description ('The session ID to reset'), and tool description adds clarifying context that the same session ID is kept, reinforcing the parameter's effect. With 100% schema coverage, adds slight additional value.

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?

Clearly states 'Reset a session's chat history (keep same session ID),' specifying the action (reset) and the resource (session's history). Distinguishes from siblings like session.close by emphasizing the session remains open.

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?

Provides explicit use case ('Use for a clean slate when the task changes') and user interaction guideline ('ask the user before resetting'), though does not explicitly mention alternatives or when not to use.

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