banChatMember

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

With no annotations, the description carries the full disclosure burden, and it does meaningful work: it states the action, the permission prerequisite, and the success return value ('Returns True on success'), which is valuable since there is no output schema. It does not mention that a ban is permanent by default unless until_date is set, nor the message-deletion side effect of revoke_messages — those are left to the schema. For a no-annotation mutation tool, this exceeds the bare minimum.

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?

Three short sentences with zero filler: action+scope, prerequisite, and return value. The action is front-loaded, and every sentence earns its place — the return-value sentence is justified because there is no output schema. This is a model of compact, structured description.

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 core invocation facts are covered (what it does, where, the admin prerequisite, and the return value), and the schema fully documents parameter semantics. The clear gaps are the absence of tool-level guidance on the default-permanent ban behavior (only implied deep inside the until_date schema description) and no positioning against the large moderation sibling family (unban/restrict/banChatSenderChat). Adequate, but an agent would benefit from more orientation.

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% — all four parameters (chat_id, user_id, until_date, revoke_messages) are individually described in the schema, including edge-case semantics like the 366-day/30-second permanent-ban rule. The description itself adds no parameter-level information. Per the rubric, baseline 3 applies when the schema does the heavy lifting.

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 states a specific verb (ban) + resource (a user) + scope (group, supergroup or channel), which fully identifies the operation. It also self-differentiates from the sibling family by action semantics: unbanChatMember is the inverse, restrictChatMember is a lesser restriction, and banChatSenderChat targets a chat rather than a user.

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 supplies a useful precondition ('The bot must be an administrator with the appropriate rights'), which tells the agent when the call can succeed. However, it gives no explicit when-to-use vs alternatives or exclusions — in a sibling list containing unbanChatMember, restrictChatMember, and banChatSenderChat, the agent must infer routing from the names alone. Usage context is present but effectively implied rather than stated.

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