预览用户技能恢复

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which matches the stated 只读 nature, so no contradiction exists. The description adds a genuine behavioral fact beyond the annotations: the operation refuses to proceed when content already exists at the target location. It does not describe what the preview contains or how failure is reported, and with no output schema that leaves a gap.

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?

A single compact sentence with two clauses: the read-only preview action first, then the refusal condition. No filler, and the most important information leads.

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 one-parameter, non-destructive tool this is close to sufficient, but the absence of an output schema means the description should say what a '恢复预览' returns and what the agent does with it next. The refusal-on-existing-content rule is mentioned without saying how the agent should react.

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%, so the description carries the burden for the single archiveId parameter and says nothing about it — no mention of where the archive ID comes from or whether it refers to a specific skill archive version. Only the parameter name and uuid format in the schema give hints.

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 gives a specific verb set (只读核对 + 生成预览) and the resource (已归档技能的恢复), which lets an agent distinguish it from the sibling preview_skill_archive: this tool previews a restore, not an archive. It never names a sibling explicitly, so the differentiation is implicit rather than stated.

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 phrase '生成恢复预览' implies this is a pre-flight step before actually restoring, and the refusal condition ('原位置已有内容时拒绝覆盖') gives one concrete circumstance. However, it never names the follow-up action (e.g., execute_skill_plan) or states when to call preview vs. act, leaving the workflow to inference.

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