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

Goes beyond the annotations by disclosing a real side effect: include_autoresponder triggers autoresponders that EMAIL the contact, which is a non-obvious external consequence. Also surfaces idempotency-adjacent risk implicitly ('existing contact'), though it never says what happens when the contact is already on the list.

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?

Three short sentences, mutation class front-loaded, and the endpoint appended for traceability. Nothing wasted, though the raw POST path contributes little to tool selection.

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?

Given full schema coverage and a destructive annotation already flagging risk, the definition is nearly complete. The remaining gap is behavior when the contact is already listed or when the email matches no existing member.

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 email/member_id alternation and sub_list_id sourcing are already documented. The description only re-emphasizes the autoresponder email behavior, adding little beyond the schema's own wording.

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 and resource ('put an existing contact on a list') and prefixes 'WRITE:' so the mutation class is immediate. The word 'existing' implicitly separates it from robly_subscribe_contact, though that sibling is never named.

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?

'Existing contact' implies the prerequisite that the contact already be in the account, and the alternative for new contacts (subscribe_contact) is inferable but not stated. No explicit when-not or exclusion guidance.

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