skool_start_chat

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers the core behavior (creates a new DM) and the return value (the conversation), but does not mention side effects, permission requirements, idempotency (whether calling again errors or returns existing), or potential rate limits. It hints at a prerequisite (user_id from skool_list_members) but omits failure scenarios. This is acceptable but not exhaustive.

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, tightly worded sentence. It front-loads the primary action and resource, then provides the parameter source, followed by the return value and next step. Every phrase earns its place—no filler, no redundancy. This is an model of concise, structured tool documentation.

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 only one parameter, no output schema, and no annotations, the description is relatively complete. It states what it does, what it returns, and how to obtain the input. It also indicates the follow-up action (send_message). Missing are potential error scenarios (e.g., invalid user_id, conversation already exists) and any explicit note that authentication is assumed. These are minor gaps given the simplicity.

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?

Given schema coverage is 0%, the description must add meaning to the single parameter. It does so by specifying the source ('user_id from skool_list_members'), which clarifies that it is the member's identifier from a prior call, not a free-form input. It also implies the parameter is required (which the schema confirms). While it doesn't describe format or validation, the source reference adds significant semantic value beyond the bare schema.

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 explicitly states the tool's action ('Open a new DM') and the resource (a member via user_id). It distinguishes from siblings like skool_send_message (sends to existing conversation) and skool_list_conversations (lists conversations) by specifying it creates a new conversation. The phrase 'so you can then skool_send_message into it' clarifies the intended downstream use.

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 implies the tool is a prerequisite for sending messages to a new member, referencing skool_send_message as the follow-up. It also points to skool_list_members as the source for user_id, giving a clear context. However, it does not explicitly state when NOT to use it (e.g., if a conversation already exists) or contrast with skool_list_conversations as an alternative for existing chats. Thus, it provides clear context but no explicit exclusions.

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