Dsh model

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

With no annotations provided, the description carries the full burden and delivers exceptionally. It discloses the transport constraint and exact failure mode (ACP returns UNSUPPORTED_TRANSPORT, never pretends success), the select-side-effect of also attempting to persist a global default (with failure only natively logged, hence not session-only), the status fallback formula (current = projection.next ?? catalog.default), the validation-before-write sequence, and the read-back verified result. No behavioral trait is left hidden.

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?

Every sentence earns its place — there is no filler — and the core purpose plus transport caveat is front-loaded in the first clause. However, it is a single dense multi-clause paragraph in Chinese with nested parentheticals and no bullet or line-break structure, which makes it harder for an agent to parse than its information density justifies. Slightly restructured formatting would earn a 5.

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 real complexity (3 actions, 6 parameters, side effects, fallback logic, transport restrictions) and the absence of both annotations and an output schema, the description is remarkably complete. An agent receives everything needed to invoke correctly: action semantics, parameter constraints, failure modes, side-effect disclosure, and explicit non-behaviors. There is no material gap.

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%, so the baseline is 3; the description adds genuine operational meaning on top — it maps each action to its parameter set, explains that select validates every id against the live catalog (禁止猜测), and that status accepts either cwd or session_id with an explicit fallback computation. The reasoning_effort defaulting behavior ('不传则由原生选择决定') reinforces the schema. The per-parameter descriptions in the schema already carry the basic semantics, and the description complements rather than repeats them.

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 opens with a specific verb+resource statement ('原生模型目录与选择' — native model catalog and selection) and precisely defines each of the three actions (list/status/select) with distinct semantics. It also draws scope boundaries against siblings by stating what the tool does not do (does not create/resume/start sessions, does not modify settings.yaml), so an agent can distinguish it from dsh_start/dsh_session/dsh_workspace.

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?

Clear per-action routing is given: list for reading the public catalog, status for an existing session's current selection, select for choosing a model on an existing session, with the requirement that target sessions already exist. The description also gives explicit when-not conditions (no session creation/restoration, no settings.yaml changes, web transport only). It stops short of naming sibling tools as named alternatives — e.g., it never says 'use dsh_start to create a session' — so routing relies on exclusions rather than explicit alternatives.

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