write_session_log

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

Annotations indicate a non-read-only, non-destructive operation. The description adds context by specifying the output location and downstream integration with search_decisions(), but it does not clarify whether files are appended or overwritten, naming conventions, or required permissions. Some behavioral context is added, but significant gaps remain.

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 composed of three short, purposeful sentences: the first states the action and destination, the second identifies the caller and trigger, and the third explains the downstream value. No filler or redundancy.

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?

For a tool with 8 parameters and no output schema, the description provides useful context about purpose and integration but lacks details on return behavior, file handling, or the exact structure of the log. It is adequate for a straightforward write operation but not fully complete.

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 description coverage is 63%, covering 5 of 8 parameters (task, phase, skill_ids, task_type, session_id), but the description itself does not describe any parameters or add meaning beyond 'structured session log'. Missing descriptions for decisions, files_changed, and next_steps are not compensated for in the description.

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 writes a structured session log to a specific directory path .agents/logs/YYYY-MM-DD/. It distinguishes itself from siblings like record_decision by focusing on the entire session log, and mentions its role as the Documenter's end-of-session action.

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 explicitly states it is called by the Documenter at the end of every session, giving a precise trigger and context. It does not mention alternative tools or when not to use it, but the specific caller and timing serve as sufficient guidance.

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