LightCMS

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

Annotations indicate non-destructive mutation (destructiveHint:false) and stable IDs (openWorldHint:false). The description adds context that this operates on 'existing' resources and identifies which fields are mutable, but doesn't disclose behavioral specifics like error handling for missing IDs or whether unchanged fields must be resubmitted.

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?

高效单句结构（9个词），动作前置。'and/or'略显冗余且与schema中所有字段均为required存在轻微冲突，但整体上零废话。

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?

对于带有完整schema描述的简单三参数更新工具而言基本够用，但缺少关于部分更新行为的重要细节（鉴于schema要求所有字段，而描述暗示可选更新），且未说明返回值或错误场景。

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 has 100% description coverage, establishing baseline 3. The description reinforces semantic relationships by grouping 'name' and 'html' as the updatable fields versus 'id' as the identifier, but doesn't resolve the tension between 'and/or' phrasing and the schema's required field constraints.

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?

Specific verb ('Update'), specific resource ('snippet'), and clear field scope ('name and/or HTML template'). The phrase 'existing snippet' clearly distinguishes this from sibling create_snippet.

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 'existing snippet' implicitly signals this is for modifications, not creation. However, it lacks explicit when-to-use guidance (e.g., 'use create_snippet for new snippets') and doesn't clarify that all fields must be provided even for partial updates despite the 'and/or' phrasing.

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