email_add_account

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It doesn't mention that this is a credential-storing operation, sensitivity/security implications of handling passwords, whether adding an account triggers connectivity tests, failure behavior if the IMAP host is unreachable, or whether existing accounts with the same email are deduplicated. For an account-mutating operation with zero annotation coverage, this is a significant gap.

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, front-loaded sentence that states the core purpose in the first clause and appends the important provider limitation in a parenthetical. It's efficient with no wasted words, though it could have used the word budget to add parameter or behavioral detail instead of purely conciseness.

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 9-parameter tool with 0% schema coverage, no output schema, and no annotations, the description is notably incomplete. The agent needs to know how host/port/tls/password relate to IMAP, how smtpHost/smtpPort relate to outgoing mail, what the required 'provider' values are, and what success/failure looks like. The description addresses only the provider-level distinction and leaves substantial gaps for the most complex part of the operation.

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%, so the description must compensate for 9 undocumented parameters including host, port, tls, password, smtpHost, and smtpPort. The description only mentions the provider types; it adds nothing about how the IMAP/SMTP fields interact, whether smtpHost/smtpPort are optional, or what TLS controls. The description names provider but not the other 8 parameters, leaving the agent to guess at semantics.

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 tool adds a new email account and specifies the scoping (IMAP or iCloud), with a distinct parenthetical limitation about Gmail/Outlook requiring the setup wizard. This distinguishes it from sibling tools like email_remove_account, email_test_account, and email_list_accounts. However, the purpose itself (add account) is largely evident from the name, so it's clear but not exceptional.

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 one important usage constraint: Gmail and Outlook are not supported here and require the setup wizard. While this gives meaningful when-not-to-use guidance, it doesn't explicitly name alternatives (the setup wizard) or describe broader context for when this tool should be selected over siblings like email_test_account. The guidance is implied rather than fully explicit.

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