combell_mail_zones_smtp_domains_update

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the write and safety profile. The description adds a valuable behavioral detail: 'The change is processed in the background (202 Accepted).' This informs the agent that the operation is asynchronous, which is not disclosed by the annotations. No contradictions with annotations.

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?

The description is a single concise sentence with no fluff. The primary action is front-loaded, and the async note is appended. It is efficient and easy to scan, though it could be more structured to include parameter hints. It earns its length.

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 the lack of parameter descriptions, no output schema, and no sibling differentiation, the description is inadequate for an agent to call the tool correctly. It omits what domain_name and hostname refer to, the prerequisites (e.g., domain must already exist), and the full effect of enabling/disabling. The description leaves major knowledge gaps that an agent would need to resolve elsewhere.

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 0%, and the description does not compensate. It only hints at the 'enabled' parameter via the phrase 'Enable or disable,' but provides no explanation of domain_name or hostname. An agent cannot infer what these parameters represent or their expected formats. This is a critical gap for a 3-parameter tool with no schema descriptions.

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 clearly states the action: 'Enable or disable an extra SMTP domain on the mail zone.' It identifies the verb (enable/disable), the resource (SMTP domain on mail zone), and the state change. It distinguishes from create/delete siblings by implying an update operation, though it doesn't explicitly say 'update an existing domain.' The action is specific enough for an agent to grasp the core purpose.

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 provides no explicit guidance on when to use this tool versus alternatives. It doesn't mention that this is for existing domains, nor does it contrast with combell_mail_zones_smtp_domains_create or delete. There is no 'use this when' or 'instead of' language. The agent must infer usage from the action, which is minimal.

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