List pinned messages

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

The read-only annotation already declares this is a safe read operation. The description adds the ordering behavior ('newest pin first'), which is useful context beyond the annotation. No other behavioral traits (e.g., pagination, limits) are disclosed, so it provides some value but not extensive transparency.

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, concise sentence with no filler. It efficiently conveys the core purpose and an important detail (ordering). Excellent structure.

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 simple list operation with a read-only annotation and a clear schema, the description is mostly complete. It covers the essential scope and ordering. There is no output schema, but the return value (a list of pinned messages) is implicit. It might benefit from mentioning pagination or required permissions, but this is not critical for a straightforward tool.

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?

The input schema covers 100% of the parameters with descriptions, so the baseline is 3. The description mentions 'channel' but adds no new meaning beyond the schema. The 'guild' parameter is not referenced in the description, but the schema already explains it. Thus the description does not significantly enhance parameter understanding.

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 indicates the resource (pinned messages) and scope (in a channel), and adds ordering information ('newest pin first'). It lacks an explicit verb, but the title 'List pinned messages' and context make the action clear. It distinguishes from sibling tools like pin_message and read_messages by focusing specifically on pinned messages.

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 usage is implied: use this tool to retrieve pinned messages in a channel. However, it does not explicitly compare to alternatives like read_messages or search_messages, nor does it mention when not to use this tool. The guidance is minimal but the purpose is straightforward enough.

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