update_merchant

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

With no annotations provided, the description self-discloses key behaviors: changes take effect immediately ('變更立即生效'), may appear on customer-visible pages (receipts, emails), and are non-reversible but can be overwritten by calling again. It also mentions the PUT API and return structure, which is excellent 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 with clear sections (用途, API, 回傳結構, 副作用) and front-loads the purpose. It is somewhat lengthy, but each section provides distinct value without redundancy.

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 no annotations and no output schema, the description covers purpose, usage, API endpoint, return structure, and side effects comprehensively. For a write operation with two parameters (including a nested object), this is complete.

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?

Both parameters have schema descriptions (100% coverage), but the description adds the crucial partial-update semantics for merchant_data, explicitly stating that only passed fields are modified. This goes beyond the schema's example JSON and enhances understanding of how to use the parameter.

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 '更新商家基本資料' and elaborates on modifying specific merchant fields (name, contact info, address). It distinguishes itself from read-only siblings like get_merchant_detail by emphasizing the update operation.

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: '僅傳入要修改的欄位，未傳入的欄位不會被覆蓋' (only pass fields to modify, untouched fields won't be overwritten) and suggests a use case (搬遷、更名). It does not explicitly mention alternatives, but no other update-merchant tool exists, so context is sufficient.

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