Link a game to a channel

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

With no annotations provided, the description carries the full burden. It discloses that this is a mutating operation (linking/unlinking) and explains the effect: 'where its tickets get posted, and where the View channel button on its notifications goes.' It also notes the equivalence to Discord's /ticket config, implying a known behavior. However, it doesn't mention potential side effects (e.g., overwriting existing links) or error conditions (e.g., invalid channel), which would add more transparency. Given the absence of annotations, a 4 is appropriate for the added context beyond the bare schema.

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 highly concise: three sentences total. The first sentence states the core action and effect. The second clarifies a technical nuance (Discord equivalence and no server requirement). The third gives a direct instruction for the parameter source. Every sentence adds unique value with zero filler. It is front-loaded with the most important information: what the tool does.

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 only 2 parameters, both fully described in the schema, and the description adds crucial context about what linking means (ticket posting location, View channel button destination) and the unlink behavior. With no output schema, the description doesn't need to explain return values. The main gap is that it doesn't specify what the response looks like or any error conditions, but given the simplicity and the schema's completeness, the description is nearly sufficient. A 4 reflects this minor gap.

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 100%, so the baseline is 3. The description adds value by explaining the role of channelId: 'Take the id from list_artist_channels. Pass no channel to unlink.' This clarifies that channelId is the identifier from a specific source and that its absence changes the operation from linking to unlinking. For the game parameter, the description reinforces the schema's 'Game name or universe id' by contextualizing it as the game being linked. This explains the relationship between parameters better than the schema alone, so a 4 is justified.

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 the purpose: 'Point a game at a channel that already exists: where its tickets get posted, and where the View channel button on its notifications goes.' It specifies the verb (link/point), the resource (game), and the target (channel). It distinguishes from siblings like create_channel (which creates a new channel) and list_artist_channels (which lists channels). It also clarifies the unlink behavior, which is a distinct secondary purpose.

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 explicit usage context: 'where its tickets get posted, and where the View channel button on its notifications goes.' It explains the relationship to Discord's /ticket config and notes that it works 'without needing to be in the server.' It also gives a clear prerequisite: 'Take the id from list_artist_channels.' The instruction 'Pass no channel to unlink' defines when not to include the optional parameter. This covers when and how to use it, contrasting with creating channels.

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