start_session

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

With no annotations provided, the description carries the full disclosure burden. It usefully reveals that the tool returns a uuid and client_session_id to persist, and clarifies fork-lineage semantics for parent_agent_id. However, it does not disclose the notable default resume=true behavior (that the tool may rebind an existing identity rather than create a new one unless force_new is set), nor any persistence/side-effect characteristics.

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?

Three sentences, zero filler, with the most actionable guidance (common case and return values) front-loaded before the edge-case clarification. Every sentence earns its place.

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 17-parameter tool with no annotations and no output schema, a three-sentence description is thin. The schema picks up substantial slack with 100% parameter coverage, and the description covers the common case well, but gaps remain: resume-by-default behavior, relationship to the identity sibling, parameter interactions, and what distinguishes a session-provisioning call from a resume call are left implicit.

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 coverage is 100%, placing the baseline at 3, and the description adds genuine semantic value beyond the schema: it identifies force_new as the key parameter in the common case and refines parent_agent_id's meaning to exclude same-workspace concurrent sessions. It also tells the agent which outputs to preserve, which is parameter-adjacent guidance the schema lacks.

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 states a specific verb and resource ('starting a session') and positions it as the 'Primary workflow name' and 'Single entry point for new agents' per the schema description. This is clear, though it partially restates the tool name and does not explicitly differentiate from the sibling 'identity' tool, which appears closely related.

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 gives concrete usage direction: 'Common case: force_new=true alone — save the returned uuid and client_session_id' and an explicit exclusion for parent_agent_id ('for a real handoff from an exited predecessor, not for a session sharing the workspace with one still running'). It stops short of routing to alternatives (e.g., when to prefer the identity sibling or resume paths), so it's strong but not a full decision guide.

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