restrict_participant

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds valuable behavioral context by explaining that each bool=True means prohibition of the corresponding action, and clarifies the polarity of send_* flags – this is beyond what annotations provide. No contradictions with annotations.

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 concise, with clear structure: purpose statement, then usage semantics, then argument explanation. Every sentence adds value, and it avoids redundant phrasing. The line breaks improve readability.

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 output schema exists (so return values are covered) and the description covers the tool's purpose, boolean semantics, and until_unix parameter, the description is quite complete. It could mention prerequisites (e.g., admin rights) or reversibility, but these are not critical given the annotations and schema. The description is sufficient for an agent to use 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 0%, so the description must compensate. It provides a general rule for all boolean parameters (bool=True means prohibition) and explains until_unix specifically. While chat and user are not described, they are self-evident. This effectively covers all 12 parameters despite not listing each one individually.

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 function: 'Ограничить права участника супергруппы (read-only mute и т.п.)' – restrict a supergroup participant's rights. This specific verb+resource+scope distinguishes it from siblings like ban_participant (ban) and kick_participant (remove), and the mention of 'read-only mute' clarifies the exact use case.

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 description explains how to interpret boolean flags (send_*=False allowed, True prohibited) and until_unix semantics, which is useful guidance. However, it does not explicitly say when to use this tool versus alternatives like ban_participant or kick_participant, nor does it provide exclusion criteria. The usage context is implied but not contrasted with sibling tools.

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