From 0123bda0b05ec6579884f80dd5e7798567866451 Mon Sep 17 00:00:00 2001 From: Snider Date: Wed, 15 Apr 2026 14:28:56 +0100 Subject: [PATCH] Improve MCP tool descriptions for agents --- pkg/mcp/tools_browser.go | 10 ++++++++-- pkg/mcp/tools_clipboard.go | 10 ++++++++-- pkg/mcp/tools_dialog.go | 5 ++++- pkg/mcp/tools_environment.go | 5 ++++- pkg/mcp/tools_layout.go | 20 ++++++++++++++++---- pkg/mcp/tools_notification.go | 10 ++++++++-- pkg/mcp/tools_tray.go | 5 ++++- pkg/mcp/tools_window.go | 15 ++++++++++++--- 8 files changed, 64 insertions(+), 16 deletions(-) diff --git a/pkg/mcp/tools_browser.go b/pkg/mcp/tools_browser.go index b828948b..c293c227 100644 --- a/pkg/mcp/tools_browser.go +++ b/pkg/mcp/tools_browser.go @@ -55,6 +55,12 @@ func (s *Subsystem) browserOpenFile(_ context.Context, _ *mcp.CallToolRequest, i // --- Registration --- func (s *Subsystem) registerBrowserTools(server *mcp.Server) { - addTool(s, server, &mcp.Tool{Name: "browser_open_url", Description: "Open a URL in the default system browser"}, s.browserOpenURL) - addTool(s, server, &mcp.Tool{Name: "browser_open_file", Description: "Open a file in the system default application"}, s.browserOpenFile) + addTool(s, server, &mcp.Tool{ + Name: "browser_open_url", + Description: `Open a URL in the default system browser. Example: {"url":"https://docs.example.com"}`, + }, s.browserOpenURL) + addTool(s, server, &mcp.Tool{ + Name: "browser_open_file", + Description: `Open a file in the system default application. Example: {"path":"/tmp/readme.md"}`, + }, s.browserOpenFile) } diff --git a/pkg/mcp/tools_clipboard.go b/pkg/mcp/tools_clipboard.go index 99b8ccf4..236c7d6d 100644 --- a/pkg/mcp/tools_clipboard.go +++ b/pkg/mcp/tools_clipboard.go @@ -149,7 +149,13 @@ func (s *Subsystem) registerClipboardTools(server *mcp.Server) { addTool(s, server, &mcp.Tool{Name: "clipboard_read", Description: "Read the current clipboard content"}, s.clipboardRead) addTool(s, server, &mcp.Tool{Name: "clipboard_write", Description: "Write text to the clipboard"}, s.clipboardWrite) addTool(s, server, &mcp.Tool{Name: "clipboard_has", Description: "Check if the clipboard has content"}, s.clipboardHas) - addTool(s, server, &mcp.Tool{Name: "clipboard_read_image", Description: "Read image data from the clipboard as base64"}, s.clipboardReadImage) - addTool(s, server, &mcp.Tool{Name: "clipboard_write_image", Description: "Write base64 image data to the clipboard"}, s.clipboardWriteImage) + addTool(s, server, &mcp.Tool{ + Name: "clipboard_read_image", + Description: `Read image data from the clipboard as base64 PNG bytes. Example: {}`, + }, s.clipboardReadImage) + addTool(s, server, &mcp.Tool{ + Name: "clipboard_write_image", + Description: `Write base64 image data to the clipboard. Example: {"base64":"iVBORw0KGgoAAA..."}`, + }, s.clipboardWriteImage) addTool(s, server, &mcp.Tool{Name: "clipboard_clear", Description: "Clear the clipboard"}, s.clipboardClear) } diff --git a/pkg/mcp/tools_dialog.go b/pkg/mcp/tools_dialog.go index efbd8eb5..3b0c3133 100644 --- a/pkg/mcp/tools_dialog.go +++ b/pkg/mcp/tools_dialog.go @@ -337,7 +337,10 @@ func (s *Subsystem) registerDialogTools(server *mcp.Server) { addTool(s, server, &mcp.Tool{Name: "dialog_open_directory", Description: "Show a directory picker dialog"}, s.dialogOpenDirectory) addTool(s, server, &mcp.Tool{Name: "dialog_confirm", Description: "Show a question/confirmation dialog"}, s.dialogConfirm) addTool(s, server, &mcp.Tool{Name: "dialog_message", Description: "Show a message dialog"}, s.dialogMessage) - addTool(s, server, &mcp.Tool{Name: "dialog_prompt", Description: "Show an input prompt dialog in the active window"}, s.dialogPrompt) + addTool(s, server, &mcp.Tool{ + Name: "dialog_prompt", + Description: `Show an input prompt dialog in the active window. Example: {"title":"Rename","message":"New name","defaultValue":"project-a"}`, + }, s.dialogPrompt) addTool(s, server, &mcp.Tool{Name: "dialog_info", Description: "Show an information message dialog"}, s.dialogInfo) addTool(s, server, &mcp.Tool{Name: "dialog_warning", Description: "Show a warning message dialog"}, s.dialogWarning) addTool(s, server, &mcp.Tool{Name: "dialog_error", Description: "Show an error message dialog"}, s.dialogError) diff --git a/pkg/mcp/tools_environment.go b/pkg/mcp/tools_environment.go index ffbcfd21..1327bf17 100644 --- a/pkg/mcp/tools_environment.go +++ b/pkg/mcp/tools_environment.go @@ -85,6 +85,9 @@ func (s *Subsystem) themeSet(_ context.Context, _ *mcp.CallToolRequest, input Th func (s *Subsystem) registerEnvironmentTools(server *mcp.Server) { addTool(s, server, &mcp.Tool{Name: "theme_get", Description: "Get the current application theme"}, s.themeGet) - addTool(s, server, &mcp.Tool{Name: "theme_set", Description: "Set the application theme to dark, light, or system"}, s.themeSet) + addTool(s, server, &mcp.Tool{ + Name: "theme_set", + Description: `Set the application theme to dark, light, or system. Example: {"theme":"dark"}`, + }, s.themeSet) addTool(s, server, &mcp.Tool{Name: "theme_system", Description: "Get system environment and theme information"}, s.themeSystem) } diff --git a/pkg/mcp/tools_layout.go b/pkg/mcp/tools_layout.go index 53148278..e6d489bf 100644 --- a/pkg/mcp/tools_layout.go +++ b/pkg/mcp/tools_layout.go @@ -351,8 +351,20 @@ func (s *Subsystem) registerLayoutTools(server *mcp.Server) { addTool(s, server, &mcp.Tool{Name: "layout_snap", Description: "Snap a window to a screen edge or corner"}, s.layoutSnap) addTool(s, server, &mcp.Tool{Name: "layout_stack", Description: "Stack windows in a cascade pattern"}, s.layoutStack) addTool(s, server, &mcp.Tool{Name: "layout_workflow", Description: "Apply a preset workflow layout"}, s.layoutWorkflow) - addTool(s, server, &mcp.Tool{Name: "layout_beside_editor", Description: "Position a window beside the detected editor window"}, s.layoutBesideEditor) - addTool(s, server, &mcp.Tool{Name: "layout_suggest", Description: "Suggest the best layout for the current screen and window count"}, s.layoutSuggest) - addTool(s, server, &mcp.Tool{Name: "screen_find_space", Description: "Find an empty rectangle on a screen for a new window"}, s.screenFindSpace) - addTool(s, server, &mcp.Tool{Name: "window_arrange_pair", Description: "Arrange two windows in an optimal split on one screen"}, s.windowArrangePair) + addTool(s, server, &mcp.Tool{ + Name: "layout_beside_editor", + Description: `Position a window beside the detected editor window. Example: {"name":"preview","editor":"code","side":"right"}`, + }, s.layoutBesideEditor) + addTool(s, server, &mcp.Tool{ + Name: "layout_suggest", + Description: `Suggest the best layout for the current screen and window count. Example: {"window_count":2}`, + }, s.layoutSuggest) + addTool(s, server, &mcp.Tool{ + Name: "screen_find_space", + Description: `Find an empty rectangle on a screen for a new window. Example: {"width":800,"height":600,"padding":24}`, + }, s.screenFindSpace) + addTool(s, server, &mcp.Tool{ + Name: "window_arrange_pair", + Description: `Arrange two windows in an optimal split on one screen. Example: {"primary":"editor","secondary":"preview","ratio":0.62}`, + }, s.windowArrangePair) } diff --git a/pkg/mcp/tools_notification.go b/pkg/mcp/tools_notification.go index 5637d886..cdd8ce14 100644 --- a/pkg/mcp/tools_notification.go +++ b/pkg/mcp/tools_notification.go @@ -144,6 +144,12 @@ func (s *Subsystem) registerNotificationTools(server *mcp.Server) { addTool(s, server, &mcp.Tool{Name: "notification_show", Description: "Show a desktop notification"}, s.notificationShow) addTool(s, server, &mcp.Tool{Name: "notification_permission_request", Description: "Request notification permission"}, s.notificationPermissionRequest) addTool(s, server, &mcp.Tool{Name: "notification_permission_check", Description: "Check notification permission status"}, s.notificationPermissionCheck) - addTool(s, server, &mcp.Tool{Name: "notification_clear", Description: "Clear a notification by id or clear all notifications"}, s.notificationClear) - addTool(s, server, &mcp.Tool{Name: "notification_with_actions", Description: "Show an interactive desktop notification with action buttons"}, s.notificationWithActions) + addTool(s, server, &mcp.Tool{ + Name: "notification_clear", + Description: `Clear a notification by id or clear all notifications. Example: {"id":"core-123"}`, + }, s.notificationClear) + addTool(s, server, &mcp.Tool{ + Name: "notification_with_actions", + Description: `Show an interactive desktop notification with action buttons. Example: {"title":"Deploy","message":"Start deployment?","actions":[{"id":"confirm","label":"Deploy"}]}`, + }, s.notificationWithActions) } diff --git a/pkg/mcp/tools_tray.go b/pkg/mcp/tools_tray.go index 961db794..c14d5dc8 100644 --- a/pkg/mcp/tools_tray.go +++ b/pkg/mcp/tools_tray.go @@ -165,6 +165,9 @@ func (s *Subsystem) registerTrayTools(server *mcp.Server) { "required": []string{"items"}, }, }, s.traySetMenu) - addTool(s, server, &mcp.Tool{Name: "tray_show_message", Description: "Show a tray balloon notification"}, s.trayShowMessage) + addTool(s, server, &mcp.Tool{ + Name: "tray_show_message", + Description: `Show a tray balloon notification. Example: {"title":"Sync complete","message":"Files are up to date"}`, + }, s.trayShowMessage) addTool(s, server, &mcp.Tool{Name: "tray_info", Description: "Get system tray configuration"}, s.trayInfo) } diff --git a/pkg/mcp/tools_window.go b/pkg/mcp/tools_window.go index 4407712c..a819a07c 100644 --- a/pkg/mcp/tools_window.go +++ b/pkg/mcp/tools_window.go @@ -499,7 +499,10 @@ func (s *Subsystem) registerWindowTools(server *mcp.Server) { addTool(s, server, &mcp.Tool{Name: "window_list", Description: "List all application windows"}, s.windowList) addTool(s, server, &mcp.Tool{Name: "window_get", Description: "Get information about a specific window"}, s.windowGet) addTool(s, server, &mcp.Tool{Name: "window_focused", Description: "Get the currently focused window"}, s.windowFocused) - addTool(s, server, &mcp.Tool{Name: "window_create", Description: "Create a new application window"}, s.windowCreate) + addTool(s, server, &mcp.Tool{ + Name: "window_create", + Description: `Create a new application window. Example: {"name":"preview","title":"Preview","url":"https://example.com","x":100,"y":100,"width":1200,"height":800}`, + }, s.windowCreate) addTool(s, server, &mcp.Tool{Name: "window_close", Description: "Close an application window"}, s.windowClose) addTool(s, server, &mcp.Tool{Name: "window_position", Description: "Set the position of a window"}, s.windowPosition) addTool(s, server, &mcp.Tool{Name: "window_size", Description: "Set the size of a window"}, s.windowSize) @@ -510,9 +513,15 @@ func (s *Subsystem) registerWindowTools(server *mcp.Server) { addTool(s, server, &mcp.Tool{Name: "window_focus", Description: "Bring a window to the front"}, s.windowFocus) addTool(s, server, &mcp.Tool{Name: "focus_set", Description: "Set focus to a specific window"}, s.focusSet) addTool(s, server, &mcp.Tool{Name: "window_title", Description: "Set the title of a window"}, s.windowTitle) - addTool(s, server, &mcp.Tool{Name: "window_title_set", Description: "Set the title of a window"}, s.windowTitleSet) + addTool(s, server, &mcp.Tool{ + Name: "window_title_set", + Description: `Set the title of a window. Example: {"name":"main","title":"Core GUI"}`, + }, s.windowTitleSet) addTool(s, server, &mcp.Tool{Name: "window_title_get", Description: "Get the title of a window"}, s.windowTitleGet) - addTool(s, server, &mcp.Tool{Name: "window_visibility", Description: "Show or hide a window"}, s.windowVisibility) + addTool(s, server, &mcp.Tool{ + Name: "window_visibility", + Description: `Show or hide a window. Example: {"name":"main","visible":false}`, + }, s.windowVisibility) addTool(s, server, &mcp.Tool{Name: "window_always_on_top", Description: "Pin a window above others"}, s.windowAlwaysOnTop) addTool(s, server, &mcp.Tool{Name: "window_background_colour", Description: "Set a window background colour"}, s.windowBackgroundColour) addTool(s, server, &mcp.Tool{Name: "window_fullscreen", Description: "Set a window to fullscreen mode"}, s.windowFullscreen)