update_order

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

With no annotations, the description carries full behavioral disclosure. It clearly states side effects: immediate and irreversible changes (訂單資料立即變更，不可復原), the ability to overwrite via another call, and status-based field restrictions. It also documents the API endpoint and return structure, which exceeds minimal expectations.

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-organized with clear sections (purpose, API, return, side effects), uses bullet-style formatting, and front-loads the write indicator [WRITE]. Every sentence contributes useful information without repetition or fluff.

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's simple two-parameter interface and lack of output schema, the description covers essential aspects: the exact API method, return structure, and side effects. It does not address error cases or authentication requirements, but these are somewhat self-evident from the context and schema.

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?

The input schema already describes both parameters, but the description adds critical partial-update semantics (僅傳入要修改的欄位，未傳入欄位不受影響), clarifying that only provided fields are modified. It also documents the return structure (dict with success, resource_id, message), which is not in an output schema. This meaningfully enhances the schema.

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 updates order fields (更新訂單欄位), lists example fields (備註, 配送地址), and distinguishes it from sibling order operations by specifying PATCH /v1/orders/{order_id} and partial-update behavior. This makes the tool's purpose specific and unambiguous.

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 implies usage for modifying editable order fields and notes that some fields may be restricted by order status. However, it does not explicitly state when to use this tool over siblings like update_order_status or update_order_tags, nor does it provide explicit exclusion criteria. The guidance is contextual but not directive.

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