update_block

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

没有 annotations，描述承担了行为披露责任。它说明了关键行为：整块替换、不是局部 patch，并警告修改前确认 block_id 避免误改。虽然没有提及权限或是否可恢复，但核心破坏性特征已透明化。

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?

工具本身复杂度不高，且已有输出 schema，返回格式无需赘述。描述覆盖了用途、参数、替换语义和误操作风险；主要缺失是与 insert/append 等替代工具的明确边界说明，但调用所需核心信息基本齐全。

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%，描述必须补偿参数语义。它逐项解释了 block_id、data_type、data 的含义，并补充了 data_type 仅支持 markdown 或 dom 这一关键限制，超出了 schema 本身提供的信息。

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?

描述明确说明“更新块内容”，并以“整块替换，不是局部 patch”进一步界定操作性质，能与 insert_block、append_block 等兄弟操作区分。但没有显式点名替代工具，因此未达到满分。

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?

给出明确适用场景：“已知 block_id 时，直接替换该块内容”，并提示这是整块替换而非局部 patch。不过没有说明何时不应使用，也没有提到可选用的兄弟工具，缺少排除性指引。

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