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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the bar is lower; the description nonetheless earns credit by making the destruction concrete ('`tags` replaces the customer's tag list') and by disclosing PATCH-style semantics ('only the fields you pass are sent'). It stops short of stating auth/permission requirements or whether omitted fields are ever cleared server-side.

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?

Two short sentences with the mutation marker front-loaded, then the partial-update rule, then the tag-replacement caveat and endpoint. No filler; every clause carries information an agent needs before calling.

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 7-parameter destructive write with no output schema, the description covers the essentials: what mutates, partial-update behavior, tags replacement, and the underlying endpoint. Remaining gaps are modest — no return/response description and no statement of failure conditions for a nonexistent customer_id or invalid email/phone.

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 only 29% (just tags and customer_id documented), so the description has to carry weight. It does name the updatable fields and clarifies the replace-not-append behavior of tags, but it collapses firstname/lastname into an ambiguous 'name' and adds no format or constraint detail for email, mobile, or phone beyond what the schema already enforces.

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?

It names a specific verb ('change') plus the resource ('a customer') and enumerates the mutable fields, and the 'WRITE:' prefix plus the PUT endpoint makes the operation type unambiguous against read siblings like get_customer or list_customers. The 'name' shorthand is slightly loose versus the schema's firstname/lastname split, but the agent still identifies the operation immediately.

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?

Usage is implied rather than stated: 'change a customer's name...' tells you this is the edit path, and PUT /customers/{customer_id} signals an existing-resource update, which implicitly routes create_customer elsewhere. But there is no explicit when-to-use/when-not guidance, no mention that the customer must already exist, and no reference to update_booking_customer or other update siblings.

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