Attach domain

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

Annotations already mark this as non-read-only and non-idempotent. The description adds useful context beyond that: every app gets an automatic domain on first deploy, service_show should be checked first, and repeat hostname-less calls generate additional subdomains. This is meaningful behavioral disclosure, though it does not describe side effects of the force flag.

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 with the most important guidance front-loaded. The first sentence is long and parenthetical, but each clause carries a necessary constraint rather than filler.

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 mutating tool with no output schema and five parameters, this description provides strong operational context: when to call, what to check first, and how to avoid the duplicate-subdomain trap. It lacks post-call verification guidance and port semantics, but these are minor compared to the upfront guardrails.

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?

The description adds real meaning for hostname by distinguishing custom vs generated subdomains, but hostname and force already have schema descriptions. Required project/service and optional port receive no explanation, and with only 40% schema coverage the description only partially compensates for the undocumented port parameter.

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 makes clear the tool attaches either a user-supplied custom hostname or generates a default *.onlizard.com subdomain. It explicitly distinguishes this from the automatic domain assigned at first deploy and references service_show, so an agent can tell it apart from domain_verify/domain_delete.

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 exactly when to call: only for an explicit custom domain request, or when service_show shows no domain yet. It also gives a clear negative constraint — do not invent or guess a hostname — and warns against repeated calls without a hostname generating new subdomains instead of returning the existing one.

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