untrash_thread

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

Annotations already declare idempotent=true, destructive=false and readOnly=false, so the safety profile is covered. The description adds value the annotations don't: the 100-item ceiling and the fact that items return to their prior location ('back where it was'). It says nothing about partial failure when some IDs in a list are invalid.

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 core sentence is front-loaded and the batch limit is placed prominently. The 'Args:' block largely restates the schema's single property, which is minor waste but keeps it navigable.

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?

An output schema exists so return values need not be explained, and the batch cap is covered. However, for a batch mutation tool the description omits the key behavioral question of what happens when some supplied IDs are not trashed or not found.

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%, and the schema exposes an anyOf union of string vs array with no explanation. The description does explain that threadId accepts a single ID or a list, which disambiguates the union, but adds no ID format or length expectations beyond the 100-item cap.

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?

Names a specific verb and resource ('take a whole thread ... out of the trash') and the parenthetical '(or a list)' plus 'whole thread' implicitly separates it from the untrash_message sibling. It stops short of naming that sibling or stating the distinction outright, so it is clear but not fully differentiated.

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?

Usage is only implied: the reader infers you call this to restore trashed threads rather than messages, and that untrash_message is the alternative for single messages. No explicit when/when-not or prerequisite conditions are given.

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