read_file

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

没有 annotations，因此描述承担了行为透明度责任。它披露了编码要求（UTF-8）、大小限制（1MB）、以及拒绝绝对路径和父目录段的限制，这些都是 schema 中不存在的行为约束。仅未提错误行为，但整体已较充实。

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?

工具只有一个必填参数，复杂度低，且存在 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?

input schema 对 path 参数零描述，只有类型和变量名，因此描述必须补偿。描述中 'relative to the workspace root'、'Refuses absolute paths and parent-directory segments' 直接定义了 path 的语义和限制，价值明显。虽未进一步说明相对路径格式，但已足够指导调用。

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?

描述以具体动词+资源开头："Read a UTF-8 file relative to the workspace root"，明确说明了读文件这一操作。它与 write_file 形成清晰对照，且通过 'UTF-8'、'workspace root'、'Size limit 1MB' 等限定让工具用途非常具体。

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?

描述通过 'Read a UTF-8 file relative to the workspace root' 清晰表达了适用场景，即读取工作区根目录下的文本文件。虽然没有显式列出 alternatives 或排除条件，但结合 write_file 等兄弟工具，边界已经足够明确。

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