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

With annotations covering the safety profile, the description adds real value: it discloses role/permission constraints and states explicitly that the service credential stays server-side and that mailbox passwords and message content are never returned. It does not explain what 'activation on demand' produces, nor whether a repeated call with the same idempotency_key is deduplicated — notable given the required idempotency_key and idempotentHint=false.

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?

Short and front-loaded, with the core action in the first clause. The clipped sentence fragments ('No guest access. Members can read.') are information-dense but slightly telegraphic.

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 mutation tool with no output schema and three required params, it covers permissions and data-exposure limits, which is useful. It leaves gaps around what the request returns or triggers — it does not mention the sibling commsharbor_email_job_get, so an agent cannot tell whether this is async and needs polling.

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% and each parameter carries its own description, so the schema does the heavy lifting. The description adds no format, enum, or idempotency-key semantics beyond what the schema already provides; 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?

The description states a specific verb+resource ('Request an included service with activation on demand'), which tells an agent what the tool does. It does not, however, distinguish itself from adjacent siblings such as commsharbor_email_trial_activate or commsharbor_email_domain_products_add, which also provision services/add-ons.

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 gives an access-control context ('No guest access. Members can read. Owners, admins and organization keys can manage email'), which implies who may invoke it. It never states when to choose this over trial_activate or domain_products_add, nor what prerequisites (e.g. an existing plan) are required.

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