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

The annotations already declare destructiveHint=true, and the description adds useful partial-update semantics: only supplied fields are changed. However, it does not explain consequences of changing new_customer_id, permission requirements, irreversibility, or error behavior, so it only moderately extends the annotation-provided safety profile.

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 three short sentences with zero waste. It front-loads the mutation warning and then states the partial-update behavior and endpoint.

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 an eight-parameter mutation tool, the description covers the essential operation and partial-update behavior. It still omits important implications such as ID changes via new_customer_id, side effects, and failure modes, though the full schema and destructive annotation reduce the burden.

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%, so all eight parameters are already documented in the schema. The description adds the cross-cutting rule that only provided fields change, but it does not add per-parameter meaning such as the effect of new_customer_id or metadata merging behavior.

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 a specific verb and resource ('partially updates a customer') and clarifies that this is a mutation of Autumn billing data. It also gives the underlying API endpoint, making the tool's operation unambiguous relative to get/list/create siblings.

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?

It clearly establishes the update context and notes that only provided fields change, which helps an agent decide to use it for partial updates. It does not explicitly compare against alternatives such as autumn_get_or_create_customer or autumn_create_entity, so it stops short of full routing guidance.

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