start_session

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

The description adds substantial behavior beyond the readOnlyHint=false annotation: the new conversation is independent and continues after the current conversation ends, resource shortages cause refusal with a reason unless force=true, names must not collide with managed conversations, and via="app" returns appStart/record values instead of starting the session. This is exactly the kind of mutation and side-effect context an agent needs before invoking start_session.

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 front-loaded with the core action and then covers profile/model precedence, persistence, resource gating, name uniqueness, and the app-mode fallback. It is dense but appropriately sized for a 13-parameter tool with complex behavior. Some parenthetical elaboration could be trimmed, but most sentences carry operational value.

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 complex 13-parameter tool with no output schema, the description covers the important behavioral contract: resource gating, force override, name uniqueness, conversation persistence, and app-mode return values. It does not describe the normal successful return shape, which leaves a small gap. Given the rich schema coverage, this is still a fairly complete definition.

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 very high at 92%, so the schema already documents most parameters. The description still adds meaningful semantics around the key interactions: profile comes from get_usage, model and effort override profile, force bypasses resource checks, and via="app" changes the tool's behavior. It does not explain every parameter, but it improves understanding of the most consequential ones.

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 first sentence states a specific verb and resource: creating a new work conversation and sending its first request, with name, working folder, model, and effort named. It also distinguishes this from continuing the current conversation by saying the new conversation runs separately and persists after this one ends. The special via="app" behavior further clarifies that this tool may not start a session directly in Claude Code desktop mode.

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?

It gives clear usage context: prefer a profile from get_usage that matches the work type, model/effort override profile, and force=true bypasses resource gating. It also describes the via="app" default and the appStart/record handoff. It does not explicitly compare against siblings such as send_message or update_session, so it stops short of full when/when-not guidance.

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