Изменение API-токена

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

Annotations already indicate readOnlyHint=false, making it clear this is a write operation. The description adds that it changes the name and/or flag, but it doesn't disclose additional behavioral aspects such as whether changes require special permissions, whether the token value is invalidated, or what the response looks like. With annotations handling the basic safety profile, the description adds minimal extra context, warranting a 3.

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 a single, concise sentence that is front-loaded with the action and key details. It contains no fluff and conveys the essential information efficiently. It is perfectly sized for the tool's simplicity.

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?

Given the tool's simplicity (3 parameters, well-documented schema, annotations present), the description is adequate. It does not explain return values, but for an edit operation, this is not critical. The description, combined with schema and annotations, provides enough context for an agent to select and invoke the tool 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 description coverage is 100%, with each parameter already well-documented. The description's mention of 'имя и/или флаг' aligns with the name and is_able_to_delete parameters, and 'по его ID' clarifies the token_id role, but it doesn't add meaning beyond what the schema provides. Baseline for full coverage is 3.

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 clearly states the tool's action: 'Изменяет имя и/или флаг is_able_to_delete API-токена по его ID' (changes the name and/or is_able_to_delete flag of an API token by its ID). This specifies the verb (change), resource (API token), the fields affected, and the identifier, distinguishing it from sibling tools like create_api_key, delete_api_key, or refresh_api_key.

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 context is clear: use this tool when you need to update the name or deletion permission flag of an existing API token. No explicit exclusions or alternatives are mentioned, but the description implicitly indicates that for creating or regenerating tokens, other sibling tools would be appropriate. Since there is no ambiguity about the primary use case, it earns a 4.

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