add_mindmap_seed

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

With no annotations, the description carries the full burden. It discloses important behaviors: idempotency via idempotency_key ('同一 key 重放此调用返回首次结果, 不重复写入'), server-side ownership validation ('服务端校验归属', '服务端验存在性+归属'), and detailed field/layout contracts (e.g., '非 root 必带 parent_id', 'links 只画跨分支联想'). This goes well beyond a basic 'creates a mindmap' statement.

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?

The description is a single dense paragraph, but every sentence and clause carries essential information. It is well-structured with a logical flow: purpose, REST equivalence, field contract, layout rules, and documentation reference. It is appropriately sized for a tool with such a complex input schema, though it could be slightly more scannable.

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?

The description thoroughly covers purpose, usage, input semantics, validation, and idempotency, which is extensive for a complex tool with a nested object. The main gap is that it does not describe the return value of a successful call (no output schema is present), though it hints at return behavior via idempotency. It also references an external tutorial, which adds completeness.

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?

Although schema coverage is high (86%), the description adds significant meaning beyond the schema. It explains the '字段合同' (field contract) for nodes and links, the layout constraints (pos_x/pos_y ranges, root position), and clarifies the pair_id restriction and idempotency_key behavior. This enriches parameter understanding substantially.

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 clearly states the tool's purpose: attaching an agent-generated mindmap seed to a lesson or course ('为 lesson 或 course 挂一张 agent 出的思维导图 seed'). It also distinguishes it from related tools by explaining it's a merged version of two REST calls (POST /mindmaps + POST /mindmaps/:id/associations), making it distinct from update_mindmap_seed.

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?

The description provides clear context for use: it's for lesson preparation ('省得 agent 备课时绕 REST'), and it explains that it's a combined create-and-associate operation. However, it does not explicitly mention when not to use it or explicitly name alternative tools like update_mindmap_seed, so it lacks explicit exclusions.

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