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

Annotations already declare destructiveHint=true, so the bar is lower, yet the description adds real value by warning that omitted custom fields are cleared and that the caller must include every field to keep. It also flags the operation as a WRITE and gives the underlying POST endpoint. It stops short of noting auth/permission needs or rate limits.

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?

Front-loaded with the 'WRITE:' mutation signal, then the scope, then the critical custom-field caveat. Efficient and well-ordered, though the raw endpoint path is arguably redundant padding that an agent does not need.

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 with no output schema and a destructiveHint annotation, the description covers the essential risk (custom-field clearing) and the write nature. It omits mention of the double-opt-in/consent parameter's implications and any return/error behavior, leaving minor gaps.

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 100%, so the schema already documents all eight parameters, including the custom_fields clearing warning. The description largely restates the field list rather than adding syntax or format detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb (update) and resource (one subscriber, by ID, in a mailing list) and enumerates the mutable fields (email, name, custom fields, tags, preferences). The 'one subscriber (by ID)' framing cleanly separates it from the sibling moosend_add_subscriber and the bulk list tools.

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 'WRITE:' prefix and the instruction 'Include every custom field you want to keep' give clear context on when and how to invoke it. However, it never explicitly names the alternative (moosend_add_subscriber) or states a when-not-to-use condition, so it falls 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.