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

With zero annotations, the description carries the full burden, and it delivers exceptional behavioral disclosure: TTL caps (5min destructive vs 24h config), server-forced single-use, grant storage keyed by user id + action_type, backend-enforced channel-difference rule, and the critical gotcha that a 200 with requires_email_selection: true means NO session was started and nothing was sent. The qr_text warning ('it is the link already rendered as QR art') prevents a subtle misuse. This far exceeds the minimum viable transparency for a mutation-style tool.

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 long (~300 words), but nearly every sentence carries high-value information that prevents real failure modes: the channel rule, the email-selection trap, the QR handling, and the retry sequence. It is well-structured with a front-loaded purpose statement, policy summary, then a numbered agent workflow. Minor redundancy exists—TTL caps and the channel constraint are repeated in the schema—so it is not perfectly lean, but no sentence is filler.

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 high-complexity tool with 6 params, no output schema, and subtle edge cases, the description is notably complete: it covers access prerequisites (Proof account, authentication), the trigger condition, channel-specific response payloads (deep_link, sms_message, qr_text), the polling handoff to wait_for_2fa, and non-success response semantics. The main gap is that it never specifies the full success-path response structure (e.g., challenge identifier fields) beyond the named payload fragments, which an agent would need to inspect the actual response for. Given the complexity and zero annotations, this is a minor omission.

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% with already-rich parameter descriptions, placing the baseline at 3. The description adds meaningful context beyond the schema: it explains when email_id becomes necessary (the requires_email_selection multi-email edge case), why channel must differ (backend enforcement with consequence), and how single_use/ttl interact with the agent's multi-mutation session workflow. It doesn't fully detail every response field, but the added workflow context justifies a score above baseline.

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 first sentence states a specific verb and resource: 'Start a 2FA challenge that grants the authenticated user permission to perform a sensitive action.' This clearly distinguishes it from login-oriented siblings like start_2fa and verify_2fa, and the closing line 'start_login does NOT open this tool' reinforces the differentiation. The purpose is unambiguous and actionable.

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 'Agent usage:' section provides an explicit 5-step protocol: trigger on 403 2fa_required, call with the noted action_type, present the challenge per channel (routing telegram/whatsapp deep_link to render_auth_link, sms to sms_message, email with the multi-address requires_email_selection fallback), poll wait_for_2fa, then retry. It also names alternatives (render_auth_link, wait_for_2fa) and gives a when-not-to guidance ('Never hand qr_text to a link renderer'). This is explicit when-to-use and when-not-to-use with no inference required.

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