08Tool 设计原则

粒度。粗粒度(read_file)简单但灵活性差,细粒度(read_lines, search_in_file, count_lines)灵活但 tool 数量爆炸,模型选错概率上升。经验:每个工具职责单一,但提供 limit/offset/pattern 这类参数让模型自己控粒度。

命名一致性。动词+名词,namespace 用下划线:read_file, write_file, list_directory。MCP 工具天然有 mcp__server__tool 前缀避免冲突。

错误返回。要 parse-friendly:模型看到 "File not found: /tmp/x" 能立刻自纠,看到 Python stack trace 反而困惑。把异常 catch 住,写成短句子。

幂等性。读型工具天然幂等。写型工具(send_email, create_issue)默认不幂等,设计时要么加 idempotency_key 参数,要么明确告诉模型"这会产生副作用,确认后再调"。

副作用边界。一个 tool 最多一个副作用。不要"读+改+提交"打包成一个 refactor_function,出问题没法定位。