login_submit

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

No annotations are supplied, so the description carries the full disclosure burden, and it discloses almost nothing: it doesn't say this consumes/validates a credential and yields an authenticated session, whether the code is single-use, whether sessions expire, or what happens on an invalid code. Only the existence of an output schema spares it from needing a return-value explanation.

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?

A single front-loaded sentence with no filler or repetition. Brevity here is efficient rather than padded, though the terseness contributes to the missing flow context.

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 an authentication step with zero annotation coverage, zero schema descriptions, and two required params, the description is far too thin: the caller cannot tell the ordering constraint, the retry semantics, or what authenticating actually means. The output schema covers return values, but everything about invoking it safely and correctly is absent.

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 description coverage is 0%, so the description must compensate for both parameters. It clarifies that 'code' is an SMS/captcha code, which is genuine added meaning, but 'session_id' is left completely undefined — no statement of where it comes from or that it must match a prior login_start result.

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 concrete verb ('submit') and resources ('SMS / captcha code', 'phone_code login session'), which is enough to distinguish it from the other login_* siblings. It stops short of explaining what a 'phone_code login session' is or how it relates to login_start/login_poll.

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?

No explicit when-to-use guidance: it doesn't say this must be called after login_start, how the session_id is obtained, or what to do if the code is rejected (retry vs restart). The reader must infer the position in a multi-step auth flow entirely from the name and the word 'session'.

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