create_alias

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

With no annotations provided, the description carries the full disclosure burden. It discloses the meaningful behaviors: different generation modes for aliases, the destination verification requirement, premium gating, and immediate activation of display_name. It does not go as far as describing error handling, duplicate alias behavior, or response shape, which keeps it from a 5.

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 dense sentences front-load the core operation, then explain mode mechanics and constraints. There is no filler, and every sentence contributes information an agent needs to construct a correct call.

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 creation tool with no output schema and no annotations, this description covers the conditional parameter relationships and the key destination_email constraint, while remaining parameters like label and domain are documented in the schema. It does not describe the expected return value or failure modes, but an agent has enough context to invoke the tool correctly.

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 71%, below the high-coverage baseline, so the description needs to add semantics. It does exactly that by explaining alias_type modes, how custom_code and tag relate to those modes, and the validity rule for destination_email. The display_name detail partially repeats the schema, but the 'activates immediately' clarification adds value.

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 action ('Create a new email alias') and then defines the three alias_type modes, so the agent knows exactly what operation and resource are involved. The create verb plus the mode explanation clearly distinguishes this tool from siblings like update_alias, delete_alias, and list_aliases.

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 description makes creation context explicit and adds eligibility constraints: destination_email must be primary or verified, and display_name is Premium-only. It does not explicitly name alternatives like update_alias or list_aliases for modifying or viewing aliases, but the creation versus maintenance distinction is clear from the description and sibling names.

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