Verify a user's one-time password (OTP) by posting a token to the SHM billing panel; admins can act on behalf of a specific user with explicit confirmation.
POST /user/otp Проверка OTP Тег: OTP Спека: user
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Тело запроса (application/json) | |
| confirm | No | Явное подтверждение выполнения не-GET операции. Без confirm:true в режиме rw возвращается превью запроса. | |
| user_id | No | admin acts on behalf of this user |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. The only real behavioral detail ('confirm') comes from the schema, not the description. The description doesn't say whether this validates, consumes, or generates an OTP, whether it's idempotent, or what it returns. 'Проверка' hints at verification, but that's it.
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?
It's short – only the route and a title. But that brevity is under-specification rather than conciseness; the structure is just a stack of metadata labels ('Тег', 'Спека') that don't help an agent decide to call it.
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?
The tool has a nested body object, an unusual confirm-gating mechanism, admin impersonation, and sits in a crowded OTP sibling family – yet the description explains none of this and there is no output schema to defer to. An agent cannot reliably call this tool from the description alone.
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%, including the non-obvious 'confirm' guard and 'user_id' admin impersonation param, so the schema does the heavy lifting. The description adds nothing about parameters. Baseline 3 per the rubric when schema coverage is high.
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 is essentially just the HTTP verb and route ('POST /user/otp') plus the title 'Проверка OTP', which restates the name. 'Проверка OTP' does imply verification, but there's no way to distinguish this from sibling tools like user_otp_get, user_otp_put, user_otp_delete, or user_otp_setup_post beyond the ambiguous 'POST'. This is close to tautology for an agent trying to select among the OTP family.
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?
There is no guidance on when to use this tool versus user_otp_get, user_otp_setup_post, or other OTP siblings. An agent has no way to know whether POST here means submit a code, generate, or validate. The 'Тег: OTP, Спека: user' lines are just metadata labels, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.