tg_folder_edit

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

Beyond the annotations, the description adds valuable behavioral detail: 'Anything not passed is left untouched' clarifies partial-update semantics, and 'The chats themselves are not touched' explains the delete behavior. This aligns with destructiveHint=true while reassuring that chat data is preserved. It provides meaningful context about side effects.

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 well organized with a concise intro followed by a labeled Args list. The most important invariant ('Anything not passed is left untouched') is front-loaded. Every sentence earns its place without redundant filler.

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?

For a tool with 9 parameters, no output schema, and nested objects, the description covers all parameters and key behavioral guarantees. It does not mention return values, error conditions, or interactions between mutually exclusive operations like create and delete, which leaves a modest gap for an agent planning a call.

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?

With schema description coverage at 0%, the description carries full responsibility for explaining parameters, and it does so for all nine: folder, add, remove, create, delete, rename, emoji, rules, and exclude. It adds constraints like 'max 12 characters' for create and lists rule checkbox names. Some details remain underspecified, such as the exact formats for chat identifiers and the rules object structure, so it is not perfect.

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 opens with specific verbs and a resource: 'Create, delete, rename and fill Telegram folders.' This clearly distinguishes tg_folder_edit from sibling read-only tools like tg_folders and from chat/topic editing tools. The scope is unambiguous and action-oriented.

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 gives practical usage context, such as 'folder: existing folder by title or id (from tg_folders); not needed with create,' which tells the agent when the param is required and where to get it. It also communicates safe partial updates with 'Anything not passed is left untouched.' However, it does not explicitly state when to prefer this tool over alternatives or when not to use it.

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