sieve_update_account

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

No annotations are provided, so the description carries the full burden. It explains the password workaround but does not state whether omitted settings are preserved, what authorization or validation applies, or what happens on failure. Additionally, 'The account must be named explicitly' conflicts with the schema, which allows accountId or an omitted accountName when only one account exists.

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 compact sentences with the core operation front-loaded, followed by the password exception and account identification requirement. There is no filler or redundant restatement.

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 nine-parameter mutation tool with no annotations or output schema, the description is minimally adequate: it tells the agent the main fields and avoids the password field. It still omits partial-update semantics and misstates the account identification requirement relative to the schema, leaving important gaps.

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 56%, so the description must compensate but only partly does. It maps several updatable fields and adds useful guidance on password changes, but it does not clarify the accountId/accountName distinction or explain allowInvalidCertificate beyond the vague 'certificate check'.

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 and resource: changing connection settings of an existing account. It enumerates the relevant settings (host, port, tls, user, certificate check, name), making it clearly distinct from account creation/removal siblings.

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 usefully redirects password changes to a terminal command and says the account must be identified explicitly. However, it does not contrast this tool with sieve_add_account or explain when to prefer one over the other beyond the existing-account framing.

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