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

Annotations are all-false hints, so the description carries the burden, and it adds real behavioral context: the tool returns a provider-owned auth link, requires no user password, and is a browser fallback. It does not detail side effects like link expiry or whether initiating re-auth revokes the old session, but the core behavior and security stance are clearly disclosed. There is no contradiction with the 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?

Every sentence adds a distinct fact: purpose, trigger, re-auth condition, sibling routing, and password prohibition. It is dense but not bloated, and the main purpose is front-loaded before caveats. The length is proportionate to the tool's branching cases.

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 2-param tool with no output schema, the description covers providers, re-authentication, sibling alternatives, and security guidance; the returned 'link' is identified even if its shape/expiry is not. It could note the imap_connect sibling as an alternative, but nothing essential for correct invocation is missing.

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?

Although schema coverage is 100%, the description substantially enriches both params. It maps account_id to the concrete unipile_account_id from list_connected_accounts and explains that omitting it creates a new account, and it clarifies the 'email' vs 'imap' enum distinction. This goes well beyond the schema's property 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 opens with a specific verb and resource: 'Get a secure connection (or reconnection) link' for listed providers, and explicitly names sibling alternatives (whatsapp_connect, telegram_connect) to differentiate. The provider list and the re-authentication clause make the tool's exact role unmistakable. It clearly distinguishes from siblings rather than merely restating the name.

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 use it ('when the user asks to connect/add/reconnect an account'), when to pass account_id, and when not to use it (prefer whatsapp_connect/telegram_connect for QR in-conversation). It also gives a hard rule: never ask for provider passwords. This is explicit routing with no reliance on inference.

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