end_session

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

With no annotations provided, the description carries the full burden. It discloses one behavioral trait—'does not auto-commit changes'—but misses other critical aspects: it doesn't mention that session_summary is required, what side effects 'update progress' has, whether the session termination is reversible, or any permission requirements. The disclosure is partial and insufficient for a destructive-sounding operation.

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 a single, well-structured sentence that front-loads the main action and adds a useful parenthetical clarification about auto-commit behavior. Every word earns its place; it is appropriately concise without being under-specified.

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 complexity (3 parameters, 1 required, no schema descriptions, no annotations, many sibling tools), the description is too sparse. It explains the core action but omits parameter semantics, usage context relative to generate_handoff or commit_changes, and important side effects. The presence of an output schema reduces the need to describe return values, but the lack of parameter and behavioral details makes the description incomplete.

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 description coverage is 0% for the 3 parameters (path, known_issues, session_summary), and the description does not mention any of them. The required session_summary is completely unexplained, and path and known_issues are also left undocumented. The description adds no semantic value for parameters, making it very difficult for an agent to know what values to provide.

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 uses a specific verb ('End') and resource ('current session'), and clearly distinguishes the tool from siblings like generate_handoff and commit_changes by noting it updates progress, generates a handoff file, and explicitly does not auto-commit changes. This differentiates it from other session/handoff tools.

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 implies usage when ending a session and creating a handoff, and the parenthetical 'does not auto-commit changes' hints that commit tools should be used separately. However, it doesn't explicitly name alternatives or state when NOT to use this tool, leaving the guidance implied rather than explicit.

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