新建会话并可选发首条消息

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds real behavioral nuance: that omitting message skips dispatch entirely, and that the tool returns a real sessionId. It does not discuss failure modes when cwd is invalid, but the schema notes the directory must already exist.

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 tight sentences, front-loaded with the core action and the return-value promise, followed by the mode distinction and the optional-parameter hint. No filler, though the parenthetical for sessionId and ensure_session adds slight nesting.

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?

There is no output schema, and the description compensates by naming the returned sessionId. The wait_seconds blocking semantics are left to the schema, which documents them fully. For a 6-param creation tool this is nearly complete, missing only error/edge-case behavior on an invalid cwd.

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 goes beyond the schema by grouping the optional model knobs (provider/modelId/thinking_level) and pointing at piweb_list_models as the source of valid model values, which the schema text does not say.

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?

States a specific verb and resource (新建 pi 会话) with the scope qualifier 在指定项目目录下, and immediately discloses the return value (真实 sessionId). It also disambiguates its two modes against the related ensure_session semantics, so an agent can distinguish it from piweb_get_session / piweb_list_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?

Explicitly states the two usage modes: with message it sends the first prompt, without message it only creates the runtime. It also routes the agent to piweb_list_models for valid model values. It stops short of stating when to prefer this over piweb_send_message for an existing session, but the context is clear.

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