start_login

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantial behavior beyond that: per-channel return shapes, that deep_link is an empty string on SMS and render_auth_link will reject it, that suggested_region may lack a matching sms_dids entry, that delivery failure surfaces as an error and creates no session, and that tool results are folded away from the user so replies must be composed manually.

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?

Front-loaded with a one-sentence purpose followed by a numbered flow, and each sentence generally carries channel-specific operational detail rather than filler. It is nonetheless long and relies on heavy ALL-CAPS and parenthetical caveats that could be tightened, so it is efficient but not maximally tight.

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?

There is no output schema, so the description must carry the return-value burden and it does: it documents deep_link/qr_code/qr_text for Telegram and WhatsApp, sms_message/sms_dids for SMS, and that email returns nothing displayable. It also covers terminal states (verified, failed, expired) and the delivery-failure error path, leaving nothing an agent needs to invoke it correctly.

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 the baseline is 3, but the description adds real per-parameter semantics: phone_number is required only for SMS, email only for email, and channel selection determines which fields come back and what to do with each. That is more than the schema's field-level notes, though it does not add syntax detail for phone_number beyond E.164 already in the schema.

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 and resource ('Start a login session by sending an authentication challenge') and enumerates the exact channel set (Telegram, WhatsApp, SMS, email). It further disambiguates by naming the downstream siblings it pairs with (render_auth_link, wait_for_login), so an agent can place it in the auth flow without opening the schema.

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?

Provides an explicit numbered flow: (1) call start_login with channel plus phone_number/email, (2) present the challenge, (3) call wait_for_login with the returned session ID. It also gives when-NOT guidance — do not call wait_for_login after a challenge_delivery_failed error because no session exists — and tells the agent to retry or offer another channel instead.

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