tg_invite

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

The description explains the straightforward mutating behavior ('invite people') and the destructive 'revoke' flag, which revokes the old link and issues a new one. However, it does not disclose any permissions required, side effects such as user notifications, or irreversibility of revoking a link. With no annotations, this leaves the agent guessing about safety and consequences.

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 compact two-line summary followed by four bullet-like argument definitions. Every sentence adds information and there is no filler. It is front-loaded with the main purpose, making it easy to scan.

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 an output schema, so the lack of a return description is acceptable. The description covers all four parameters and the two functional modes (inviting and link handling). However, it does not clarify whether users is required when obtaining a link, nor whether revoke automatically returns a new link, leaving a small ambiguity.

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?

The Args section defines each parameter in plain language: chat is 'the group or channel', users is 'who to add', link will 'also return the primary invite link', and revoke will 'revoke the old link and issue a new one'. This compensates for the empty schema descriptions, but it does not go deeper into accepted user formats or whether users is optional when obtaining a link, so a bit more context would be beneficial.

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 starts with 'Invite people to a chat and/or get its invite link,' which clearly identifies the primary action (invite) and resource (chat), and adds a secondary capability (getting the invite link). This distinguishes it from sibling tools like tg_leave or tg_participants, which target different chat operations.

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 what the tool does but does not explicitly state when to use it instead of related tools such as tg_participants or tg_create_group. No exclusions or alternative tool names are mentioned. Usage is implied by the verb 'Invite,' but clear guidelines are absent.

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