Create thread

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

Annotations indicate a non-read-only, non-destructive write operation, which the description matches ('Start a thread'). It adds behavioral nuance (private only works standalone) beyond the 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 a single well-structured sentence that efficiently conveys the core functionality, modes, and exception. No redundant or unnecessary words.

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 parameter count (7) and absence of an output schema, the description covers the main usage scenarios and provides a critical sibling distinction. It lacks details on parameter defaults and edge cases like announcement channel thread behavior, but remains largely sufficient.

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 71%, so the baseline is 3. The description adds value by explaining the roles of message_id and private in context, and notes the limitation of private mode. However, it does not describe all parameters (e.g., auto_archive_minutes, slowmode_seconds).

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 it starts a thread in text or announcement channels, distinguishes three modes (standalone, branched, private), and explicitly names the sibling tool create_forum_post for forum channels.

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 provides context on when to use this tool (text/announcement channels) and when not (forum channels, with alternative given). It does not detail prerequisites like permissions or default guild behavior, but the sibling differentiation is strong.

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