module_preview

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

Annotations already carry readOnlyHint=true and openWorldHint=false, so the safety profile is covered; but the description adds only internal detail and the word '保存' (save) muddies the read-only semantics. The note that the use switch is controlled by bindings is the only genuine behavioral context, and it is too terse to be useful. Not a hard contradiction since '保存' describes members data rather than the tool's side effects.

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 text is short, but it is under-specified rather than concise: it front-loads dense jargon about member references and switches instead of leading with the tool's purpose, and every clause requires inference.

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 6-parameter tool with zero parameter descriptions, a full output schema, and a long list of ambiguous siblings, the description explains none of the inputs, no invocation semantics, and no differentiation from module_describe, module_apply, or the other preview tools. The output schema covers return values, but everything else an agent needs is missing.

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 0% and the description must compensate, but it only hints at members sub-fields (itemId, role) that don't even appear in the schema. None of the six parameters (id, name, scope, members, baseline, description) are explained, so an agent cannot construct a valid call.

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 never states what the tool does — no verb+resource such as 'preview a module' — and instead describes internal member data mechanics ('members 使用 itemId 和 role, 保存独立来源版本引用'). It reads like an implementation note and gives an agent no way to know this tool produces a module preview or how it differs from module_describe or module_apply.

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?

There is no when-to-use guidance, no conditions, and no mention of alternatives among the many sibling preview/describe/apply tools. The only context is a cryptic note that the usage switch is controlled by bindings, which does not help an agent choose this tool over module_describe or host_preview.

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