create_workitem_comment

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

注解已声明 readOnlyHint=false、destructiveHint=false，描述补充了“当前项目内”的范围和默认 Markdown 格式。但未说明权限要求、是否支持线程回复、创建后可见性等额外行为，且与注解不矛盾。

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?

单句描述，动作和默认格式前置，没有冗余措辞。但信息量偏少，导致关键参数语义缺失；这更影响完整性而非简洁性。

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?

工具包含 4 个参数且 schema 无参数描述，parent_id 的回复语义和 content 格式要求均未说明。虽然已有 output 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 参数描述覆盖率为 0%，描述仅补充了 format_type 的默认值为 Markdown。workitem_id、content、parent_id 的语义均未解释，尤其 parent_id 是否用于回复完全缺失。

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?

明确说明动词和资源：向当前项目内的工作项添加评论，并注明默认 Markdown 格式。但未明确区分 list_workitem_comments、update_workitem_comment、delete_workitem_comment 等兄弟工具。

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?

隐含用于创建评论，但没有说明何时应使用本工具而非更新、删除或列出评论工具。也未说明 parent_id 用于回复评论等使用场景。

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