updateCustomerMembership

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

Annotations already indicate mutability (readOnlyHint=false) and potential destructiveness (destructiveHint=true). The description adds the app requirement as a critical behavioral constraint. It does not contradict annotations; idempotentHint is consistent with setting a rank. Minor omission: no mention of whether the operation appends or replaces, but the schema implies replacement.

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 four sentences, front-loaded with the core action, then parameters, then usage guidelines. No unnecessary words or repetition. It is concise yet informative.

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 tool has moderate complexity with nested parameters and a mutation operation. No output schema is provided, but the description covers when to use, prerequisites, and alternatives. Given the richness of annotations and schema, the description is complete enough for an agent to invoke correctly.

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 100% with descriptions. The description reinforces these by stating 'customer_id で対象会員、membership.membership_id で新しいランクの ID を指定してください' (specify customer_id and membership_id). It adds value by explaining the role of parameters in the context of updating a membership rank.

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 states 'Updates the membership rank of a specified member customer' (明確に目的を記載). It also distinguishes from sibling tools by naming alternatives: deleteCustomerGroupMembership for removal, getCustomer for retrieval, updateCustomers for general update. This makes the tool's purpose and differentiation clear.

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 explicitly states when to use this tool (to set a new membership rank) and when to use alternatives (deleteCustomerGroupMembership to remove rank). It also notes the prerequisite that the '会員ランク' app must be installed; otherwise an error occurs. This provides comprehensive usage guidance.

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