Update custom domain

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

Annotations already flag destructiveHint and idempotentHint, but the description adds real value beyond them: it explains partial-update semantics ('Only the provided fields change'), the no-op rejection, that the updated domain is returned, and specifically warns that disabling catch_all or replacing mailbox_ids 'can stop future delivery', naming the concrete harm.

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 front-loaded with the core action, then walks each field efficiently in one sentence, and ends with the risk warning. It is dense but largely earns its length; the field glosses partially duplicate the schema descriptions, which is the only mild waste.

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?

With no output schema, the description compensates by stating the updated domain is returned, and it covers partial-update behavior and destructive side effects. For a 5-param update tool that is essentially complete, though it doesn't mention auth/permission requirements that an openWorld mutation might entail.

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 the baseline is 3, but the description goes further by cross-referencing mailbox_list as the source of ids, restating the 1–20 bound, and framing mailbox_ids as a full replacement rather than an append. This adds operational meaning the schema alone doesn't convey.

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 opens with a specific verb and resource ('Update a custom domain') and enumerates exactly which fields can change, so the agent knows the tool's scope immediately. It does not explicitly differentiate itself from siblings like custom_domain_list or custom_domain_trash_list, though none of those overlap in function.

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 states a clear precondition ('Provide at least one change') and clarifies that a no-op call 'is rejected without contacting SimpleLogin', which tells the agent when a call is valid. It does not name alternative tools or describe when an agent should prefer a different operation, so it stops short of full when/when-not guidance.

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