jp_lit_start_session

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

The description explains that research_goal and scope_note are saved in the new session's trace, while search results, candidates, and annotations remain in the old session. This adds context beyond annotations, which already indicate the tool is not read-only and not destructive. However, it does not mention any potential limitations like session count limits or authentication requirements.

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 concise, with the main action stated first, followed by the effect on parameters, and then alternative tools for clarity. Every sentence adds value, and there is no 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?

Given the tool's role in session lifecycle management and the presence of an output schema, the description covers the essential behavioral aspects. It explains the fate of old session data and parameters. However, it does not describe the output or what happens if no parameters are provided beyond starting without a purpose, leaving minor gaps.

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 100%, so the baseline is 3. The description adds value by explaining how the parameters are used: both research_goal and scope_note are stored in the new session's trace. It also clarifies that if research_goal is unspecified, the session starts without a purpose, which is not explicit in the schema.

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 action: starting a new empty research session while preserving the current session as history. It uses specific verbs and resources, and differentiates from siblings by naming jp_lit_update_session_trace for updates and jp_lit_list_sessions/jp_lit_export_session for reviewing old sessions.

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 provides when-to-use and when-not-to-use guidance. It states to use jp_lit_update_session_trace for appending to an existing session, and jp_lit_list_sessions or jp_lit_export_session for checking old sessions, making it clear when to choose this tool over alternatives.

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