update_mindmap_seed

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

With no annotations, the description carries full burden. It discloses key non-obvious behaviors: the source=agent permission check, the dual-column write ('写入会同时同步 content 与 agent_seed_snapshot 两列'), and the historical bug motivating this behavior ('只改 content 会让 Clear & redo...诈尸'). This is exactly the kind of context an agent needs to avoid a subtle failure.

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?

Three dense sentences pack purpose, restrictions, validation, and a behavioral caveat. Each sentence earns its place, though the '诈尸' zombie metaphor is colorful and may slightly obscure clarity. Overall, efficient and front-loaded.

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?

Given the complexity (nested object, 3 params, no annotations, no output schema), the description covers purpose, usage restrictions, validation linkage, and a critical write-behavior pitfall. It also mentions the permission error type. This is sufficient for an agent to invoke correctly without additional context.

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 coverage is 100%, so baseline is 3. The description adds value beyond the schema by pointing to the full field contract in add_mindmap_seed ('字段合同见 add_mindmap_seed 说明') and a complete tutorial. This cross-reference helps the agent understand content structure more deeply, exceeding what the schema's brief descriptions provide.

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?

The description opens with '修复/迭代你自己播种的课程脑图' (fix/iterate your own seeded course mindmap), clearly stating the action and resource. It distinguishes from sibling add_mindmap_seed by focusing on updating an existing agent-owned mindmap, and further differentiates scope by specifying source=agent.

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?

Explicitly states when to use: only for source=agent mindmaps. Provides a when-not case: '学习者自己长出来的图不许 agent 动, 会打 PERMISSION' (learner-grown graphs not allowed, will get PERMISSION). Also references add_mindmap_seed as the validation contract, implying the alternative for creation.

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