plan_heartbeat

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

The description adds meaningful behavioral context beyond annotations: it clarifies the tool only records state, does not execute the agent's actions, and reveals a dependency on 'converge' (which will reject evidence lacking reference/revision). Annotations already declare idempotentHint=true and destructiveHint=false, which the description does not contradict. The description reinforces the non-destructive, bookkeeping nature.

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 paragraph of about 100 Chinese characters, front-loading the purpose and then key constraints. Every sentence adds value. It could be slightly improved with bullet points or separate sections for first call vs subsequent calls, but it is already very concise without waste.

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 tool has 16 parameters, deep nesting, no output schema, and is part of a complex Delegated Plan workflow, the description is too minimal. It does not explain what the tool returns (likely just success/failure), how to handle conflicts or errors, the lifecycle of a heartbeat sequence, or what happens if the plan_id is invalid. For such complexity, more completeness is needed to guide the agent fully.

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 only 25% (4 of 16 parameters have descriptions). The description compensates by stating that 'plan' is required on first call and that subsequent calls merge various categories like evidence, artifacts, acceptance_results, etc. However, it does not explain individual parameter semantics for fields like 'unresolved_items', 'last_verified_revision', or the differences between 'memory_candidates' and 'architecture_candidates'. The constraint for evidence (reference/revision) is helpful but insufficient for the overall parameter richness.

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 records lightweight checkpoints during Delegated Plan execution, with the specific verb '记录' and resource '检查点'. It also distinguishes itself from siblings by focusing on status recording rather than execution ('只记录状态，不代替 Agent 执行'). However, it does not explicitly differentiate from all 24 sibling tools.

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 that the first call must provide a complete plan and subsequent calls merge various fields (steps, evidence, artifacts, etc). It also provides a key constraint: for convergence, evidence must include 'reference' or 'revision' unless it is 'requirements'. This gives clear usage context. However, no explicit 'when NOT to use' or comparison to alternatives like 'converge' is provided.

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