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

Annotations cover the safety profile (not readOnly, not idempotent, open-world, non-destructive). The description adds genuinely useful behavior beyond that: it deletes the 'notactivated' role and grants full access, and it requires the account's login credentials. These side-effect and auth disclosures are exactly the value structured data does not carry.

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 same idea — the code arrives by activation email — is restated three times across the German and English fragments, and the English is bolted on awkwardly. The mixed-language content is redundant rather than additive, so length is not earned.

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 3-param mutation with no output schema, it covers the essentials: purpose, required credentials, the code's origin and format, and the account-state side effect. An agent has enough to invoke it correctly; only the absence of explicit sibling routing keeps it from a 5.

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 100%, so baseline is 3. The description goes beyond it by stating the voucher is a 7-digit activation code delivered by email and by identifying loginusername/loginpassword as the registered account's email + password, giving the agent the expected format and source.

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 verb (activate) and resource (registered account) with the mechanism (voucher code). It implicitly distinguishes from register (which comes before) and renew_account, though it doesn't name those siblings explicitly. The German sentences dilute but don't obscure the 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?

It gives real workflow guidance for obtaining the code (ask the human on the standard path, otherwise pull via IMAP), which is more than the bare minimum. However, it never clarifies when to choose this over register, renew_account, or redeem_invite_code, so the routing guidance against siblings is only implied.

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