derivation_update_step

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

With no annotations, the description carries the transparency burden. It discloses a key behavioral constraint: it cannot change calculation results, and fields like expression/operation type require rollback. However, it does not clarify overwrite vs. merge behavior, validation of step_number, or error handling, leaving some ambiguity for a mutation tool.

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 well-structured: it starts with a prominent warning, lists updatable and non-updatable fields, provides an Args section with default behavior, a Returns line, and an example. The decorative lines and repetition are somewhat verbose but aid readability and emphasis. Overall, it is clear 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?

For a simple metadata update tool, the description covers most essential aspects: what can be updated, what cannot, and the meaning of None. However, it misses session_id, which may be required to identify the derivation session in context, and the Returns description is vague ('更新結果'). Since an output schema exists, return values may be documented elsewhere, but the session_id gap remains a completeness issue.

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 description coverage is 0%, so the description must explain parameters. It adequately explains step_number (1-based), and states that None means 'don't update' for description, notes, assumptions, and limitations. However, it omits session_id entirely, which is a parameter in the schema, and does not explain the array types for assumptions/limitations (though these are evident from the schema). This is a notable gap.

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: '更新步驟的元資料' (update step metadata). It explicitly lists the updatable fields (description, notes, assumptions, limitations) and specifies what is not updatable (expression, operation type), which distinguishes it from rollback and other derivation 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?

The description clearly states when to use this tool: only for updating descriptive fields, and that changing expressions or operation types requires 'rollback' instead. This provides an explicit exclusion and names the alternative tool. However, it does not mention other potentially overlapping siblings like derivation_add_note or derivation_insert_note, so it is not fully comprehensive.

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