feat: Add tool annotations for improved LLM tool understanding

[triepod-ai]

Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint, title) to all tools to help LLMs better understand tool behavior and make safer decisions about tool execution.

Changes

• Added readOnlyHint: true to read-only tools:
  • conversations_history - Get Conversation History
  • conversations_replies - Get Thread Replies
  • conversations_search_messages - Search Messages
  • channels_list - List Channels
• Added destructiveHint: true to conversations_add_message (Send Message)
• Added human-readable title annotations to all tools

Why This Matters

Tool annotations provide semantic metadata that helps LLMs understand tool behavior beyond just the description:

• readOnlyHint: Tells LLMs the tool is safe to call without side effects
• destructiveHint: Signals that the tool modifies data (posts messages)
• title: Provides a human-readable name for better UX

This enables:

• Safer tool execution by distinguishing read-only from write operations
• Better tool prioritization (read-only tools can be used freely for information gathering)
• Improved user experience in MCP clients that display tool metadata

Before/After

Before:

s.AddTool(mcp.NewTool("conversations_history",
    mcp.WithDescription("Get messages from the channel..."),
    // No annotations
), handler)

After:

s.AddTool(mcp.NewTool("conversations_history",
    mcp.WithDescription("Get messages from the channel..."),
    mcp.WithTitleAnnotation("Get Conversation History"),
    mcp.WithReadOnlyHintAnnotation(true),
), handler)

Testing

The changes use the existing mcp-go v0.40.0 annotation API:

• mcp.WithTitleAnnotation(string)
• mcp.WithReadOnlyHintAnnotation(bool)
• mcp.WithDestructiveHintAnnotation(bool)

These are standard functions from github.com/mark3labs/mcp-go/mcp that are already imported.

---

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]