Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kitty-mcp-server open a new tab and run htop"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for controlling the kitty terminal emulator.
Exposes 40 tools for managing kitty windows, tabs, layouts, text, appearance, and more via the Model Context Protocol. Communicates with kitty through its remote control protocol using the kitten CLI.
kitty terminal emulator with remote control enabled
Node.js 20+
Related MCP server: iterm2-mcp
npm install
npm run buildAdd these lines to your ~/.config/kitty/kitty.conf:
allow_remote_control yes
listen_on unix:/tmp/kitty-{kitty_pid}Restart kitty after making changes.
Add to .claude/settings.json:
{
"mcpServers": {
"kitty": {
"command": "node",
"args": ["/path/to/kitty-mcp-server/dist/index.js"]
}
}
}When the MCP server runs inside a kitty window, it automatically picks up the KITTY_LISTEN_ON environment variable.
{
"mcpServers": {
"kitty": {
"command": "node",
"args": ["/path/to/kitty-mcp-server/dist/index.js"],
"env": {
"KITTY_MCP_SOCKET": "unix:/tmp/kitty-12345"
}
}
}
}Variable | Description |
| Override the kitty remote control socket path. Takes highest priority. |
| Set automatically by kitty inside its windows. Used as fallback when |
| Override the kitty CLI binary name or path. Default: |
| Password for kitty remote control authentication, if configured. |
kitty_ls -- list all OS windows, tabs, and windows as a JSON tree
kitty_get_text -- retrieve text content from a window (screen, scrollback, selection, last command output)
kitty_get_colors -- get terminal color definitions
kitty_select_window -- visually select a window with overlay labels
kitty_launch -- launch a new process in a window, tab, or OS window
kitty_close_window -- close windows
kitty_focus_window -- focus a window
kitty_resize_window -- resize a window within its layout
kitty_detach_window -- move windows to a different tab or OS window
kitty_set_window_title -- set window title
kitty_close_tab -- close tabs
kitty_focus_tab -- focus a tab
kitty_set_tab_title -- set tab title
kitty_set_tab_color -- change tab bar colors
kitty_detach_tab -- move tabs to a different OS window
kitty_send_text -- send text to windows
kitty_send_key -- send key presses to windows
kitty_scroll -- scroll window content (lines, pages, prompts, start/end)
kitty_set_colors -- set terminal colors
kitty_set_font_size -- set font size
kitty_set_spacing -- set padding and margins
kitty_set_background_opacity -- set background opacity
kitty_disable_ligatures -- control ligature rendering
kitty_goto_layout -- switch to a specific layout
kitty_last_used_layout -- toggle to the previous layout
kitty_set_enabled_layouts -- set which layouts are available for cycling
kitty_create_marker -- highlight text matching a pattern
kitty_remove_marker -- remove markers from a window
kitty_run -- run a program and get its output
kitty_action -- run a mappable kitty action
kitty_kitten -- run a kitten (kitty extension)
kitty_load_config -- reload kitty configuration
kitty_signal_child -- send Unix signals to foreground processes
kitty_env -- change environment variables for new windows
kitty_set_user_vars -- set user variables on windows
kitty_resize_os_window -- resize, fullscreen, or hide OS windows
kitty_dump_scrollback -- dump scrollback to a temp file with pagination
kitty_get_tab_text -- get text from all windows in a tab in one call
kitty_clear_cache -- clear the MCP server internal cache
kitty_health_check -- verify kitty connectivity and server status
MIT
Run a mappable kitty action in the specified window. Actions are the same action names used in kitty.conf key mappings (e.g. "scroll_line_down", "copy_to_clipboard", "new_tab"). Arguments are space-separated within the action string.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | Run the action on the window this command runs in. | |
| match | No | Window match expression. | |
| action | Yes | The action to perform, with optional arguments as a single string (e.g. "scroll_line_down 5"). Required. | |
| no_response | No | Don't wait for a response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It does not disclose behavioral traits like side effects, return values, error handling, or whether the action is destructive. Only states it runs an action in a window.
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?
Two concise sentences. First sentence states purpose, second adds crucial format details. No fluff, well-structured for quick comprehension.
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?
Given no output schema and no annotations, the description is reasonably complete but lacks guidance on parameter selection (self vs match) and does not explain what happens after the action runs (e.g., no response, return value).
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 coverage is 100%, baseline 3. The description adds value by explaining that arguments are space-separated within the action string and provides examples, aiding correct parameter usage.
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 it runs a mappable kitty action in a specified window, distinguishing it from sibling tools which are specific actions. Examples are provided (e.g., 'scroll_line_down', 'copy_to_clipboard').
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?
Examples of actions are given, but it does not explicitly guide when to use this generic tool versus the many specific sibling tools like kitty_send_key or kitty_scroll. No 'when not to use' or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear the MCP server internal cache. Useful if you suspect stale data from cached ls or get-colors results.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states it clears internal cache but lacks detail on what exactly is cleared, potential side effects, or safety implications. Adequate for a simple cache clear but could be more explicit.
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?
Two sentences with no wasted words. First sentence states action, second gives guidance. Front-loaded and efficient.
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 no parameters, no output schema, and no annotations, the description fully covers its purpose and usage context. No additional info needed.
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?
No parameters; schema coverage is 100%. The baseline for 0 params is 4, and the description adds no confusion. It rightly omits parameter info since none exist.
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?
Description clearly states the action 'Clear the MCP server internal cache' with a specific verb and resource. It distinguishes itself from sibling tools like kitty_ls, kitty_get_colors, etc., by focusing on cache clearing.
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?
Provides explicit context: 'Useful if you suspect stale data from cached ls or get-colors results.' This tells the agent when to use it, though it falls short of listing alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the specified kitty tabs. If no match expression is provided, the active tab is closed.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | Close the tab this command runs in. | |
| match | No | Tab match expression for tabs to close. | |
| ignore_no_match | No | Do not return an error if no tabs match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states the destructive action of closing tabs and the default behavior, but lacks details on side effects, permissions, or parameter interactions (e.g., self vs match).
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 extremely concise with two sentences, front-loaded with the main action. No unnecessary words.
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 description covers the core functionality but leaves out details about parameter interactions (e.g., when both self and match are provided) and return values. Given the tool's simplicity and no output schema, it is adequately complete but not exemplary.
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 schema covers all parameters (100%). The description adds value by clarifying the default behavior when match is omitted, which is not in the schema. However, it does not elaborate on self or ignore_no_match beyond schema descriptions.
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 verb 'close' and the resource 'kitty tabs', and specifies the default action when no match is provided. It is distinct from sibling tools like kitty_focus_tab or kitty_detach_tab.
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 usage when you want to close tabs, but does not explicitly state when to use this tool versus alternatives like kitty_close_window, nor does it provide any 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the specified kitty windows. If no match expression is provided, the active window is closed.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | Close the window this command runs in instead of the active window. | |
| match | No | Window match expression for windows to close. | |
| ignore_no_match | No | Do not return an error if no windows match the expression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes default action (close active window if no match) but omits behavior when match fails (error handling via ignore_no_match) and potential side effects (e.g., closing last window).
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?
Two concise sentences, no unnecessary words, front-loaded with key action and default case.
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?
Adequate for a simple mutation tool, though could mention irreversibility or impact on tabs; no output schema needed.
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?
Adds value beyond schema by explaining the default behavior when match is omitted, linking to the match parameter.
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?
Clearly states the tool closes windows, with differentiation from siblings like kitty_close_tab (tabs) and kitty_detach_window (detach). Includes behavior when no match is given.
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?
Provides context on default behavior (active window) but does not explicitly guide when to use over alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a marker that highlights text matching a pattern in a kitty window. Marker types: "text"/"itext" for literal matches, "regex"/"iregex" for regex matches, "function" for custom Python functions. Color groups 1-3 use different highlight colors as configured in kitty.conf.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | Target the window this command runs in. | |
| match | No | Window match expression. | |
| marker_spec | Yes | Marker specification: first element is the type (text, itext, regex, iregex, function), followed by pairs of <color_group> <pattern>. Example: ["text", "1", "ERROR", "2", "WARNING"] or ["regex", "1", "\\bERROR\\b"]. Required. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Explains that marker highlights text using types and colors, but does not disclose side effects, persistence, or whether markers replace existing ones. Adequate but not thorough.
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?
Two sentences: first states purpose, second lists types and color groups. No wasted words, front-loaded with key information.
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?
Given no output schema and 3 parameters, description covers main purpose and marker types. Could mention marker lifetime or that they can be removed with kitty_remove_marker, but still reasonably complete.
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 coverage is 100% with detailed descriptions for all parameters, including marker_spec structure. Tool description adds minimal extra meaning beyond the schema, so baseline 3 is appropriate.
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?
Clearly states it creates a marker to highlight text matching a pattern. Mentions marker types and color groups. Does not explicitly differentiate from sibling kitty_remove_marker, but purpose is clear.
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?
Implies usage for highlighting patterns, but no explicit guidance on when to use vs other tools like kitty_send_text or kitty_run. No exclusions or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detach tabs and move them to a different or new OS window. By default, detached tabs are moved to a new OS window. Use target_tab to specify a destination OS window.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | Detach the tab this command runs in. | |
| match | No | Tab match expression for the tab(s) to detach. | |
| target_tab | No | Tab match expression identifying the destination OS window. The detached tab is moved to the OS window containing the matched tab. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses default behavior (new window) and the effect of target_tab. No contradictions. Could add more detail on side effects, but adequate without annotations.
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?
Two sentences, front-loaded with the core action. No fluff.
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?
Covers main behavior and all parameters. Lacks examples or edge cases, but sufficient for a simple tool with no output schema.
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 coverage is 100% with solid parameter descriptions. The description adds context to target_tab beyond the schema, improving usability.
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 action ('Detach tabs') and the resource ('OS window'). It distinguishes this tool from siblings like kitty_close_tab and kitty_focus_tab.
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?
Provides clear default behavior and explains how to use the target_tab parameter to specify a destination. Lacks explicit when-not-to-use or alternatives, but sufficient for the tool's scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detach windows and move them to a different tab or a new OS window. By default, detached windows are moved to a new OS window. Use target_tab to specify a destination tab, or "new" to create a new tab.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | Detach the window this command runs in. | |
| match | No | Window match expression for windows to detach. | |
| target_tab | No | Tab match expression for the destination, or "new" to create a new tab. If omitted, a new OS window is created. | |
| stay_in_tab | No | Keep focus in the current tab after moving windows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains default behavior and the effects of target_tab and stay_in_tab. It does not disclose any side effects, failure conditions, or permission requirements, but it provides adequate transparency for a simple move operation.
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?
Two sentences, zero fluff. The first sentence states the core purpose, the second adds key behavioral details. Every word serves a purpose.
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?
Four parameters, none required, no output schema, no annotations. The description covers the main behavior and two key parameters (target_tab, stay_in_tab). The 'self' and 'match' parameters are left to the schema, which is acceptable given high schema coverage.
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 coverage is 100%, so baseline is 3. The description adds value by clarifying the default for target_tab (omitted = new OS window) and the purpose of stay_in_tab (keep focus). This goes beyond the schema's descriptions.
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 action ('Detach windows') and the outcome ('move them to a different tab or a new OS window'). It distinguishes this tool from siblings like kitty_detach_tab and kitty_close_window by specifying moving to tabs or new windows.
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 explains default behavior (new OS window) and how to use target_tab for different destinations. It also mentions the stay_in_tab parameter for focus control. However, it does not explicitly state when not to use this tool or contrast it with similar tools like kitty_close_window.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Control ligature rendering for specified kitty windows/tabs. "never" shows ligatures normally, "always" disables them everywhere, "cursor" disables them only under the cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Apply to all windows. | |
| match | No | Window match expression. | |
| strategy | Yes | Ligature strategy. "never" = show normally, "always" = disable, "cursor" = disable only under cursor. Required. | |
| match_tab | No | Tab match expression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavior. It only explains the strategy values but does not describe side effects, whether the change is immediate, if it requires specific permissions, or what happens on invalid input. This leaves important behavioral traits undisclosed.
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 two sentences long, with the purpose in the first sentence and the strategy details in the second. It is extremely concise and front-loaded with essential information, leaving no wasted words.
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?
Given the tool has 4 parameters and no output schema, the description is somewhat incomplete. It does not explain return values, error cases, prerequisites, or the effect of the tool (e.g., immediate change?). While the parameter schemas are clear, more context on the tool's behavior would improve completeness.
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 baseline is 3. The description adds some meaning by explaining the strategy enum values in more user-friendly terms, but does not add extra information for 'all', 'match', or 'match_tab' beyond the schema. It provides marginal added value.
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 tool controls ligature rendering for specific windows/tabs. It explains the three strategy values, making the purpose unambiguous. No sibling tool handles ligatures, so it is well-differentiated.
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 usage when controlling ligatures but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. No exclusions or alternative tools are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dump a window's full scrollback to a temp file and read it back with pagination. Solves the problem of scrollback buffers too large to return in a single response. First call dumps and returns a page; follow-up calls with file_path paginate through the dump without re-fetching from kitty.
| Name | Required | Description | Default |
|---|---|---|---|
| ansi | No | Include ANSI formatting/color codes. | |
| limit | No | Maximum lines to return per page. Default: 5000. | |
| match | No | Window match expression (e.g. "title:my_term"). | |
| extent | No | What text to capture. Default: "all" (screen + full scrollback). | |
| offset | No | Line offset to start reading from. Default: 0 (beginning). | |
| file_path | No | Path to a temp file from a previous dump_scrollback call. If provided, reads from this file instead of re-dumping, enabling efficient pagination. |
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 the two-phase behavior and pagination mechanism but does not mention side effects like temp file creation, cleanup, or error handling. The behavioral traits described are accurate but incomplete.
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?
Three sentences, front-loaded with purpose, each sentence adds essential information. No redundant or trivial content.
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?
Given 6 parameters and no output schema, the description effectively explains the core workflow and pagination. It covers the primary use case but could mention the return format (lines of text) and the temp file path pattern for clarity. Overall, it is mostly complete.
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 baseline is 3. The description adds value by explaining the pagination pattern involving file_path, which is not detailed in the schema. However, it does not elaborate on other parameters beyond what the schema provides.
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 it dumps a window's full scrollback to a temp file and reads with pagination, solving the problem of large buffers. However, it does not differentiate from sibling tools like kitty_get_text or kitty_get_tab_text, which may also retrieve text from a window.
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 a usage pattern: first call dumps and returns a page, follow-up calls with file_path paginate. However, it lacks explicit when-to-use or when-not-to-use guidance, e.g., for small scrollback consider using another tool. No alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change environment variables seen by newly launched kitty windows. Use "NAME=VALUE" to set a variable, or just "NAME" (without =) to unset it.
| Name | Required | Description | Default |
|---|---|---|---|
| env | Yes | Environment variable specs. "NAME=VALUE" to set, "NAME" to unset. Example: ["EDITOR=vim", "OLDVAR"]. Required. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description conveys key behavioral traits: variables affect only newly launched windows. No contradiction or missing critical behavior.
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?
Extremely concise: one sentence for purpose, one sentence for usage. No superfluous content, front-loaded with purpose.
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 tool with no output schema or annotations, the description fully covers what the tool does, how to use the parameter, and the scope (new windows). Complete.
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?
Adds significant meaning beyond schema: explains format 'NAME=VALUE' for set, 'NAME' for unset, includes example. Schema coverage is 100% and description enhances it.
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 tool changes environment variables for newly launched kitty windows, with a specific verb and resource.
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?
Provides clear format instructions for setting and unsetting variables, but lacks guidance on when to use this tool versus alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Focus the specified kitty tab. The active window in that tab will be focused.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Tab match expression for the tab to focus. | |
| no_response | No | Don't wait for a response from kitty. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds value by stating that the active window in the focused tab will be focused, which is a behavioral detail beyond the name. However, it does not mention side effects, error handling, or prerequisites.
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 two short sentences with no wasted words. The main action is front-loaded, making it efficient and easy to parse.
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 tool with two parameters and no output schema, the description is fairly complete. It explains the effect and behavior. It does not clarify what happens if the match expression fails, but overall meets the needs for this 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?
Schema description coverage is 100%, so the schema already documents both parameters. The description does not add additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.
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 tool focuses a specified kitty tab and specifies that the active window in that tab will be focused. This distinguishes it from sibling tools like kitty_focus_window, which focuses a specific window.
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 usage when you want to focus a tab, but does not explicitly state when to use this tool versus alternatives like kitty_focus_window or other tab-related tools. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Focus the specified kitty window, bringing it to the foreground. If no match expression is provided, the command window is focused.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Window match expression for the window to focus. | |
| no_response | No | Don't wait for a response from kitty. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description lacks details on side effects (e.g., what if window doesn't exist, or if it's on different desktop). Minimal disclosure for a focus action.
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?
Extremely concise—two sentences with no wasted words. Front-loaded with key information.
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?
Adequate for a simple tool with no output schema, but could be improved by mentioning edge cases (e.g., behavior if window is not found).
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 coverage is 100%, so description adds minimal value beyond what schema already provides for 'match' and 'no_response'. Baseline 3 is appropriate.
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?
Clearly states the action (focus) and resource (kitty window). Defines default behavior when no match is provided, distinguishing it from sibling tools like close or detach.
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?
No guidance on when to use this tool over alternatives (e.g., kitty_select_window). Does not specify prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get terminal color definitions for a kitty window. Returns color names and hex values in kitty.conf format (e.g. "background #1e1e2e"). Use --configured to get the original kitty.conf colors instead of any runtime overrides. Results are cached for 10 seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Window match expression. | |
| configured | No | If true, return the originally configured colors from kitty.conf instead of the current (possibly overridden) colors. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the return format (kitty.conf colors and hex values with an example), and discloses caching for 10 seconds, which is a behavioral trait. No contradictions.
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?
Two sentences, front-loaded with the main purpose. Every sentence adds value: purpose, output format, flag explanation, and caching. No wasted words.
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?
Given no output schema, the description covers return format and gives an example. It lacks error conditions or behavior when match fails, but for a simple getter, it is largely complete.
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 coverage is 100% with detailed parameter descriptions. The description adds context for the --configured parameter but does not significantly extend meaning beyond the schema. Baseline 3 is appropriate.
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 starts with 'Get terminal color definitions for a kitty window,' providing a clear verb and resource. It distinguishes from sibling tools like kitty_set_colors (which sets colors) and kitty_ls (which lists windows).
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 explains when to use the --configured flag to get original colors versus current overrides, and mentions caching behavior. However, it does not explicitly state when not to use the tool or mention alternatives for modification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get text content from ALL windows in a specific tab in a single call. Combines kitty_ls + multiple kitty_get_text calls. Returns text from every window in the tab with per-window headers showing ID, title, CWD, PID, and dimensions. Useful for understanding what is happening across split panes or monitoring multiple processes.
| Name | Required | Description | Default |
|---|---|---|---|
| ansi | No | Include ANSI formatting/color codes. | |
| match | No | Tab match expression (e.g. "index:0", "title:work", "id:3"). If omitted, the active tab is used. | |
| extent | No | What text to retrieve from each window. Default: "screen". | |
| max_lines_per_window | No | Maximum lines per window. Oldest lines are truncated when exceeded. Default: 10000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It describes output details (per-window headers) and that it retrieves text. Could explicitly state non-destructive nature but otherwise clear.
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?
Two sentences: first states core action, second explains composition and output. No waste, front-loaded.
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?
Given no output schema and 4 parameters, description covers purpose, output format, and usage. Examples missing but not required for completeness.
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 coverage is 100%, so baseline 3. The description adds minimal extra meaning beyond schema parameter descriptions (e.g., match examples are already in 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 clearly states it gets text from all windows in a specific tab in one call. It distinguishes from sibling tool kitty_get_text by explicitly combining kitty_ls and multiple kitty_get_text calls.
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 gives use cases: understanding split panes or monitoring processes. It implies when to use vs kitty_get_text (single window) but lacks explicit when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve text content from a kitty window. Supports multiple extent modes: "screen" (visible content), "all" (screen + scrollback), "selection" (selected text), "last_cmd_output" (output of most recent command), and more. When extent is "all", output is truncated to max_lines (keeping most recent lines) to prevent overwhelming context.
| Name | Required | Description | Default |
|---|---|---|---|
| ansi | No | Include ANSI formatting/color codes in the output. | |
| self | No | Get text from the window this command runs in. | |
| match | No | Window match expression (e.g. "title:my_term"). | |
| extent | No | What text to retrieve. Default: "screen" (visible content). "all" includes full scrollback. "last_cmd_output" gets output of the most recent shell command (requires shell integration). | |
| max_lines | No | Maximum lines to return. When exceeded, oldest lines are truncated. Default: 50000. | |
| add_cursor | No | Add cursor position and style as ANSI codes. | |
| clear_selection | No | Clear the selection after retrieving it. | |
| add_wrap_markers | No | Add carriage returns at line-wrap positions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses truncation for 'all' extent and requirement of shell integration for 'last_cmd_output', adding good transparency for a read-only tool.
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 two sentences with front-loaded purpose; the list of extent modes is necessary but slightly long, making it concise overall.
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 description covers key behaviors (extent modes, truncation) and parameter purpose, though it omits return format and a few extent mode details. Ready for use.
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 coverage is 100%, but the description adds value by explaining extent modes (e.g., 'screen' as visible content) and truncation logic beyond the schema's enum descriptions.
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 tool retrieves text from a kitty window, specifies multiple extent modes, and distinguishes from siblings like kitty_get_tab_text and kitty_get_colors.
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 explains extent modes and truncation behavior but does not explicitly state when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch to a specific window layout in the active or specified tab. Valid layouts: fat, grid, horizontal, splits, stack, tall, vertical. Layout names can include options after a colon (e.g. "tall:bias=70").
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Tab match expression. | |
| layout | Yes | The layout name to switch to (e.g. "tall", "splits", "tall:bias=70"). Required. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses valid layouts and option syntax (e.g., 'tall:bias=70'), but does not detail side effects, permissions, or failure modes. Adequate for a straightforward action.
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?
Two focused sentences with no extraneous information. Front-loaded with the core action and immediately followed by key details (valid layouts, options). Efficient.
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?
Given no output schema and simple functionality, the description is sufficient. It covers the action, valid inputs, and optional parameters. No major gaps for an agent to invoke correctly.
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 coverage is 100%, but the description adds value beyond the schema by listing valid layout names and explaining option syntax after a colon, which helps the agent understand parameter formatting.
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 uses a specific verb ('Switch to') and resource ('window layout in active or specified tab'), and lists valid layouts, clearly distinguishing it from siblings like 'kitty_last_used_layout' and 'kitty_set_enabled_layouts'.
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 states the tool is for switching layouts in the active or specified tab, providing clear context. It lacks explicit 'when not to use' or alternative suggestions, but the context is sufficient for its simple use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform a health check of the kitty MCP server. Verifies that the kitty CLI is accessible and all server subsystems are operational.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states the tool checks CLI and subsystems but does not mention side effects, destructiveness, or other behaviors (e.g., network calls, output format). It adequately describes purpose but lacks depth on non-obvious effects.
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 two sentences that front-load the core action. Only necessary information is included, with no redundancy or wasted words.
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?
Given the tool has no parameters and no output schema, the description sufficiently covers purpose and verification scope. It is complete for a simple health check tool, leaving no major gaps for an AI agent to understand its use.
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 tool has zero parameters and schema coverage is 100%, so the schema already fully describes inputs. Per guidelines, 0 parameters baseline is 4. The description does not need to add parameter info, and none is provided.
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 tool's action ('Perform a health check') and the resource ('kitty MCP server'). It further specifies what is verified (CLI accessibility and subsystem operational status), making it distinct from sibling tools which focus on specific actions like sending keys or managing tabs.
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 usage for server health verification but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or context for when health checks are appropriate are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a kitten (kitty extension) over the specified windows. The kitten can be a builtin name or a path to a Python file containing a custom kitten.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Additional arguments to pass to the kitten. | |
| match | No | Window match expression. | |
| kitten_name | Yes | The name of the kitten to run (e.g. "unicode_input", "hints"). Required. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry full behavioral disclosure. It fails to detail side effects, permissions, or what 'running a kitten' entails beyond the basic action.
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?
Single sentence, 28 words, front-loaded with purpose. No wasted words; efficient and to the point.
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 description omits key behavioral context, such as what a kitten is, how to use match expressions, and expected outcomes. Given no output schema, this leaves the agent underinformed.
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 baseline is 3. The description adds minimal value beyond the schema, only hinting at the 'match' parameter with 'over the specified windows'. No extra context for 'args' or 'kitten_name'.
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 tool runs a kitten over specified windows, with a specific verb and resource. It distinguishes from siblings like kitty_send_text by focusing on the kitten concept unique to kitty.
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?
No usage guidelines provided. The description does not indicate when to use this tool over alternatives, nor does it mention prerequisites or context for invoking it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Switch to the previously active window layout in the specified tab. Works like a layout toggle between the current and last layout.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Change the layout in all tabs. | |
| match | No | Tab match expression. | |
| no_response | No | Don't wait for a response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the toggle behavior but does not disclose what happens if there is no previous layout, nor does it clarify the effect of parameters like 'all' or 'match'.
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 two concise sentences, no wasted words, and front-loaded with the core purpose.
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?
Given the low complexity and no output schema, the description is largely complete. However, it could benefit from mentioning the requirement of a layout history to toggle, but overall it provides enough context for an agent.
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 no additional meaning or context for the parameters beyond what the schema already provides.
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 action ('Switch') and the resource ('previously active window layout'), and explicitly mentions it works as a toggle. This distinguishes it from sibling tools like kitty_goto_layout which sets a specific layout.
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 usage as a toggle between current and last layout but does not explicitly state when to use it versus alternatives (e.g., kitty_goto_layout for specific layouts) or mention edge cases like no previous layout.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch a new process in a kitty window, tab, or OS window. This is the primary window creation tool. Returns the ID of the newly created window. If no command is specified, the default shell is launched. Supports many launch options including window type, location, environment, and stdin source.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory. Special values: "current", "oldest", "last_reported", "root". | |
| env | No | Environment variables as "NAME=VALUE" strings. Example: ["TERM=xterm-256color", "DEBUG=1"]. | |
| var | No | User variables as "NAME=VALUE" strings, accessible via kitty match expressions. | |
| hold | No | Keep window open after the command exits. | |
| self | No | Use the tab of the window this command runs in. | |
| type | No | Where to launch: window (in current tab), tab (new tab), os-window (new OS window), overlay (over current window), etc. Default: window. | |
| match | No | Tab match expression — which tab to create the window in. | |
| copy_env | No | Copy environment from the source window. | |
| location | No | Where in the tab to place the new window. "vsplit"/"hsplit" create vertical/horizontal splits. Default: default. | |
| tab_title | No | Title for the new tab (if launching in a new tab). | |
| keep_focus | No | Keep focus on the current window instead of switching. | |
| copy_colors | No | Copy colors from the source window. | |
| command_args | No | The command and its arguments to run. Example: ["python3", "-m", "http.server", "8080"]. If omitted, the default shell is launched. | |
| copy_cmdline | No | Copy command line from the source window. | |
| stdin_source | No | Where to get stdin for the launched process. | |
| window_title | No | Title for the new window. | |
| allow_remote_control | No | Allow remote control from the new window. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses that the tool returns the newly created window ID and that omitting command_args launches the default shell. However, it does not mention side effects (e.g., resource usage, focus behavior if keep_focus not set) or permission requirements.
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 three sentences (though one is short) and front-loads the core purpose. It is efficient with no wasted words, but could be slightly more structured by grouping related info.
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?
Given the tool's complexity (17 params, no output schema), the description is fairly complete: it explains the return value, default behavior, and key options. It could be enhanced by mentioning error handling or examples, but the rich schema compensates.
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 coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema, only highlighting that many launch options are supported and that no command defaults to shell. This does not significantly improve understanding of parameters.
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 tool launches a new process in a kitty window, tab, or OS window, and identifies itself as the 'primary window creation tool'. This verb+resource+scope is specific and distinguishes it from sibling tools like kitty_close_window or kitty_focus_window.
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 this is the go-to tool for creating windows, but does not explicitly mention when not to use it or provide alternatives. It mentions default shell behavior but lacks guidance like 'use kitty_run for quick commands' or 'use kitty_kitten for scripting'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reload kitty configuration files. If no paths are specified, the previously specified config file is reloaded. Paths are resolved relative to the kitty config directory.
| Name | Required | Description | Default |
|---|---|---|---|
| paths | No | Config file paths to load. | |
| override | No | Config overrides as "NAME=VALUE" strings. Example: ["font_size=14", "background_opacity=0.9"]. | |
| ignore_overrides | No | Ignore previous config overrides. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that paths are relative to the config directory and that omitting paths reloads the previous config. However, it does not mention side effects, error behavior, or whether the action is destructive.
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 two sentences long, concise, and front-loaded with the primary action. No unnecessary words.
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?
Given the 3 parameters and no output schema, the description covers the main action and path resolution. However, it lacks details on return values, error handling, and the overall effect on the terminal emulator. It is adequate but not comprehensive.
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 coverage is 100%, so baseline is 3. The description adds value by explaining that no paths reloads the previous config and that paths are relative to the config directory. The override and ignore_overrides parameters are not discussed in the description, but their schema explanations are clear.
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 tool reloads kitty configuration files, using a specific verb and resource. It also explains the default behavior when no paths are specified, distinguishing it from other kitty tools that modify individual settings.
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 purpose of loading config files is implied, but no explicit guidance is given on when to use this tool versus alternatives like kitty_set_font_size or other config-modifying tools. There are no exclusions or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all kitty OS windows, tabs, and windows as a JSON tree. Returns the full hierarchy: OS-window[] -> tab[] -> window[], including window IDs, titles, PIDs, cwds, foreground processes, and layout info. Use --match / --match-tab to filter. Results are cached for 3 seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | If true, only return information about the window this command runs in. | |
| match | No | Window match expression to filter windows (e.g. "title:my_term", "id:42"). Uses kitty match syntax. | |
| match_tab | No | Tab match expression to filter tabs (e.g. "index:0", "title:work"). | |
| all_env_vars | No | If true, include all environment variables for each window, not just those that differ from the kitty process. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description discloses caching behavior (3 seconds) and return format (JSON tree with specific fields). Does not cover permissions or rate limits, but for a read-only listing, this is sufficient.
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?
Two concise sentences; first sentence states purpose, second adds filtering and caching. Front-loaded with no wasted words.
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?
Explains return hierarchy and fields, includes caching detail. No output schema, so description compensates. Could mention snapshot nature but still fairly complete for a listing 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?
Schema covers all parameters (100% coverage). Description adds context by noting filtering flags and cache, but does not provide significant additional meaning beyond schema descriptions.
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?
Clearly states the tool lists kitty OS windows, tabs, and windows as a JSON tree, specifying the resource hierarchy and action. Distinguishes from sibling tools as the primary listing command.
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?
Mentions filtering via --match and --match-tab but does not explicitly state when to use this tool over alternatives or provide exclusions. Lacks guidance on context-specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove the currently set marker (if any) from the specified kitty window.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | Target the window this command runs in. | |
| match | No | Window match expression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It notes the conditional 'if any', indicating no-op when no marker exists, but does not disclose other behavioral traits like whether it requires a focused window or affects multiple windows.
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 that is front-loaded with the essential action. Every word contributes to understanding without unnecessary elaboration.
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?
Given the simplicity of the tool, no output schema, and clear sibling differentiation, the description is nearly complete. It could benefit from confirming behavior when no window is specified, but overall it provides sufficient context for an agent to invoke it correctly.
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 coverage is 100% with both parameters described in the input schema. The description does not add additional meaning beyond the schema, meeting the baseline for a tool with complete parameter documentation.
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 uses a specific verb 'Remove' and clearly identifies the resource 'marker' and context 'kitty window'. It distinguishes itself from sibling tools like kitty_create_marker by describing a distinct operation.
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 usage when a marker needs to be removed from a window, but lacks explicit guidance on when to use this tool versus alternatives (e.g., kitty_create_marker or other window actions). No prerequisites or conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resize, show, hide, or toggle fullscreen/maximized state of kitty OS windows. Note that some window managers (e.g. tiling WMs) may not allow applications to resize their windows.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | Resize the window this command runs in. | |
| unit | No | Size unit for width/height. Default: cells. | |
| match | No | Window match expression. | |
| width | No | Desired window width. 0 leaves unchanged. Default: 0. | |
| action | No | The action to perform. Default: "resize". | |
| height | No | Desired window height. 0 leaves unchanged. Default: 0. | |
| incremental | No | Treat sizes as increments on existing size. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It mentions the restriction on certain window managers but does not disclose side effects, permissions, or whether actions are reversible. Adequate but with gaps.
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?
Two sentences that are concise and front-loaded. The first sentence lists actions and target, the second adds a crucial caveat. No unnecessary words.
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 description covers the main purpose and a limitation, but given the complexity (7 parameters, no output schema), it could add more context like how 'match' works or differentiate from kitty_resize_window. It is minimally adequate.
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 description does not need to add parameter details. It does not provide additional semantics beyond the schema, achieving the baseline score.
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 tool's actions (resize, show, hide, toggle fullscreen/maximized) and the target (kitty OS windows). It distinguishes from siblings like kitty_resize_window by specifying 'OS windows'.
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 note about window managers not allowing resizing provides important context for when the tool may not work. However, it doesn't explicitly compare with sibling tools or specify when to use this over others like kitty_resize_window.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resize the specified kitty window within its current layout. Not all layouts support resizing in all directions. Use axis "reset" to restore default sizes.
| Name | Required | Description | Default |
|---|---|---|---|
| axis | No | Axis to resize along. "reset" restores the default size. Default: horizontal. | |
| self | No | Resize the window this command runs in. | |
| match | No | Window match expression. | |
| increment | No | Number of cells to change size by. Can be negative. Default: 2. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It notes that not all layouts support all directions, which is a key constraint, but lacks details on side effects, failure modes, or prerequisites.
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 extremely concise with two sentences, no redundancy, and front-loads the core purpose. Every sentence adds value.
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?
Given no output schema and 4 parameters, the description covers the main behavioral caveat (layout-dependent resizing) but omits what happens on failure, impact on other windows, or any prerequisites.
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 coverage is 100% with descriptions for all 4 parameters. The description adds context about layout support and the 'reset' axis behavior, which goes beyond the schema's enum and default values.
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 it resizes a kitty window within its current layout. The verb 'resize' and resource 'specified kitty window' are specific. It distinguishes from sibling 'kitty_resize_os_window' by context, but does not explicitly differentiate from other window tools.
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 mentions using axis 'reset' to restore defaults and notes layout limitations, but does not provide explicit when-to-use or when-not-to-use guidance compared to alternatives like 'kitty_resize_os_window' or 'kitty_launch'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a program on the computer where kitty is running and get its output (stdout, stderr, exit code). This waits for the process to complete. For fire-and-forget, use kitty_launch with type "background" instead.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Environment variables as "NAME=VALUE" strings. | |
| cmdline | Yes | The command and arguments to run. Example: ["ls", "-la", "/tmp"]. Required. | |
| timeout | No | Timeout in milliseconds. Default: 120000 (2 minutes). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description carries full burden. It discloses waiting behavior and output capture, but omits details on timeout behavior, environment handling, error scenarios, and output format.
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?
Two sentences with no redundancy. First sentence states primary action; second provides alternative. Efficient and front-loaded.
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?
Given no output schema or annotations, description covers the basic purpose and sibling differentiation but lacks details on return structure, timeout handling, and environmental defaults.
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 coverage is 100%, so baseline is 3. Description adds no additional meaning beyond schema descriptions for env, cmdline, timeout; it only restates that cmdline is required.
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 tool runs a program and captures stdout, stderr, and exit code. It explicitly contrasts with kitty_launch for fire-and-forget cases, providing distinct purpose among siblings.
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 explicitly tells when to use (wait for output) and when not (use kitty_launch for background), giving clear guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scroll the content of a kitty window. Supports scrolling by lines, pages, to start/end, to prompts (with shell integration), and unscrolling. Examples: "5" (5 lines down), "2p-" (2 pages up), "start", "end", "1r" (next prompt), "1r-" (previous prompt), "0.5p" (half page down).
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Window match expression. | |
| amount | Yes | Scroll amount. "start"/"end" to jump to edges. Number with optional unit (l=lines, p=pages, u=unscroll, r=prompt) and direction (+down, -up). Examples: "5", "2p-", "1r-", "0.5p". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes scroll actions, which are typically non-destructive, but does not explicitly state safety, reversibility, or system impact. The description is adequate but could be more transparent about behavioral traits.
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 concise, front-loading the purpose, and includes a compact list of examples. Every sentence serves a purpose with no unnecessary text.
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?
Given the tool's simplicity, no output schema, and 100% parameter schema coverage, the description covers key usage patterns. It could briefly mention the match parameter's role or scrolling constraints, but overall it is sufficiently complete for an agent to invoke the tool correctly.
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 coverage is 100%, with descriptions for both parameters. The description adds value by giving concrete examples and syntax for the amount parameter, clarifying units and directions. It does not elaborate on the match parameter beyond the schema, but overall it enriches understanding of the amount parameter.
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 tool scrolls kitty window content and lists supported scrolling modes (lines, pages, start/end, prompts, unscroll). It uses a specific verb 'scroll' and resource 'kitty window', effectively distinguishing from sibling tools like kitty_send_key or kitty_get_text.
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 detailed usage examples for the amount parameter, guiding the agent on valid inputs. However, it does not explicitly mention when not to use this tool or suggest alternatives, but the context of sibling tools implies it is the correct tool for scrolling actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Visually select a window in a kitty tab. Kitty overlays letter/number labels on each window and waits for user input. Returns the selected window's ID. This is an interactive command with a 60-second timeout.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | Select from the tab containing this command window. | |
| match | No | Tab match expression to select which tab to show windows from. | |
| title | No | Description text shown to the user during selection. | |
| exclude_active | No | Exclude the currently active window from selection choices. | |
| reactivate_prev_tab | No | Reactivate the previously active tab after selection. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly explains the interactive nature: overlays labels, waits for user input, has a 60-second timeout, and returns selected window ID. This is comprehensive for an interactive tool.
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?
Three sentences, each essential. Front-loaded with core action, then explains mechanism and timeout. No redundant words.
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?
With 5 parameters fully described in schema and no output schema, description covers interactive behavior and timeout. Lacks detail on timeout result or blocking behavior, but overall adequate.
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%. The description does not add meaning beyond what the schema already provides for each parameter. Baseline 3 is appropriate.
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 action: 'Visually select a window in a kitty tab.' It explains the interactive overlay of labels and return of window ID, distinguishing it from siblings like kitty_focus_window.
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?
No explicit guidance on when to use this tool versus alternatives like kitty_focus_window. The interactive nature is implied but not contrasted with programmatic selection methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send key presses to specified kitty windows. Keys are kitty key names like "ctrl+a", "enter", "shift+f1", "alt+left". All keys are sent as press events then release events in reverse order.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Send to all windows. | |
| keys | Yes | Key names to send. Example: ["ctrl+a", "enter", "alt+f1"]. Required. | |
| match | No | Window match expression. | |
| match_tab | No | Tab match expression. | |
| exclude_active | No | Exclude the active window. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that keys are sent as press events then release events in reverse order, which is beyond the schema. No annotations exist, so this disclosure is valuable for understanding side effects.
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?
Two concise sentences: first states purpose, second explains key event behavior. No fluff, front-loaded, efficient.
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?
Covers basic functionality and key format, but lacks information on return values, error behavior, or what happens when no window matches. With no annotations, more detail on side effects would improve completeness.
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 covers all 5 parameters with descriptions; the description adds key format examples (e.g., ctrl+a) but does not significantly expand on parameter meaning beyond the 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 clearly states the tool sends key presses to specified kitty windows, with specific examples of key names, distinguishing it from siblings like kitty_send_text.
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?
No guidance on when to use this tool versus alternatives (e.g., kitty_send_text for text input). No explicit when-not-to-use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send arbitrary text to specified kitty windows. The text follows Python escaping rules on the kitty side (e.g. \e for ESC, \n for newline). Use from_file to send file contents. Use bracketed_paste to control paste mode behavior.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Send to all windows. | |
| text | No | The text to send. Required unless from_file is provided. Supports kitty escape sequences (\e, \n, etc.). | |
| match | No | Window match expression. | |
| from_file | No | Path to a file whose contents to send. Contents are sent as-is (no escape interpretation). | |
| match_tab | No | Tab match expression. | |
| session_id | No | Session ID for broadcast sessions. | |
| exclude_active | No | Exclude the active window. | |
| bracketed_paste | No | Bracketed paste mode. "auto" lets kitty decide based on the running program. Default: not set (kitty decides). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses Python escaping rules and the as-is behavior of from_file, which is useful. However, it lacks details on matching behavior, authorization, or side effects. Since no annotations are provided, the description carries the full burden.
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 three sentences long, front-loaded with the main purpose, and contains no unnecessary words. Every sentence adds value.
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?
Given the complexity (8 parameters, no output schema), the description covers the main behavioral aspects well. It could mention the return value or error handling, but overall it is fairly complete.
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 coverage is 100%, providing a baseline of 3. The description adds value by clarifying the escaping rules (Python escaping) and giving usage context for from_file and bracketed_paste, which goes beyond the schema descriptions.
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 tool sends arbitrary text to specified kitty windows, with a specific verb and resource. However, it does not explicitly differentiate from similar sibling tools like kitty_send_key, which sends key presses.
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?
No guidance on when to use this tool versus alternatives is provided. The advice on using from_file and bracketed_paste relates to parameter usage, not tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the background opacity for kitty windows. Requires dynamic_background_opacity to be enabled in kitty.conf. Opacity affects all windows in the same OS window.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Apply to all OS windows. | |
| match | No | Window match expression. | |
| toggle | No | Toggle between the specified value and the default. | |
| opacity | Yes | Opacity value: a number between 0.0 (transparent) and 1.0 (opaque), or "default" to reset. Required. | |
| match_tab | No | Tab match expression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the prerequisite (dynamic_background_opacity enabled) and that opacity affects all windows in the same OS window. Without annotations, this is sufficient behavioral context.
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?
Two sentences, front-loaded with the action. No redundant or extraneous information.
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?
Covers prerequisite and scope. No output schema, but given the simplicity of the tool, it is reasonably complete.
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 has 100% coverage. Description only echoes the opacity format from schema, adding no new meaning beyond what structured fields provide.
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?
Clearly states 'Set the background opacity for kitty windows' with a specific verb and resource. Distinguishes itself from sibling tools by its unique function.
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?
Provides a clear prerequisite and scope. No explicit when-not-to-use or alternative suggestions, but context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set terminal colors for specified windows/tabs. Colors are specified as "key=value" strings (e.g. "foreground=red", "background=#1e1e2e") or a path to a .conf file. Use reset to restore all colors to startup values.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Apply to all windows. | |
| match | No | Window match expression. | |
| reset | No | Reset all colors to startup values. When true, color specs are ignored. | |
| colors | No | Array of color specs ("key=value") or a single .conf file path. Example: ["foreground=#cccccc", "background=#1e1e2e"]. Required unless reset is true. | |
| match_tab | No | Tab match expression. | |
| configured | No | Also change the configured (persistent) colors. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that setting 'reset' to true causes color specs to be ignored, and that 'configured' changes persistent colors. This adds behavioral context beyond the 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?
Three sentences that are front-loaded with the action, then provide specifics. Every sentence adds information without verbosity.
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?
Given no output schema, the description adequately covers tool behavior and parameter semantics. It could mention the return value (e.g., success/error), but for a mutation tool this is acceptable.
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 coverage is 100%, but the description adds value by explaining color spec format ('key=value' strings or .conf file path), reset behavior, and that 'configured' makes colors persistent. This goes beyond the schema descriptions.
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 verb 'set' and the resource 'terminal colors for specified windows/tabs', with examples of color specification. It distinguishes from sibling tools like 'kitty_get_colors' which retrieves colors.
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 explains when to use 'reset' parameter to restore all colors to startup values, and provides format guidance for color specs. However, it does not explicitly state when not to use this tool versus alternatives, though the context of sibling tools makes it reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set which layouts are available for cycling in the specified tab. If the current layout is not in the list, switches to the first enabled layout. Use "all" or "*" to enable all layouts.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Tab match expression. | |
| layouts | Yes | Array of layout names to enable. Example: ["tall", "stack", "splits"]. Use ["all"] to enable all layouts. Required. | |
| configured | No | Also change the configured default so new tabs use these layouts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Discloses key behavior: if current layout is not in the enabled list, it switches to the first enabled layout. Does not mention permissions or side effects, but sufficient for a settings tool.
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?
Three sentences: purpose stated first, then behavioral detail, then usage hint. No redundant words or filler. Efficient and front-loaded.
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?
Explains purpose and fallback behavior. Does not clarify behavior when match is omitted (likely current tab) or persistence across sessions. However, given no output schema and low complexity, it is fairly complete.
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?
Input schema covers all 3 parameters (100% coverage). Description adds minimal extra value: mentions using '*' as alternative to 'all' for layouts. Baseline 3 is appropriate as schema already provides meaning.
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?
Describes specific verb 'Set', resource 'layouts available for cycling', and scope 'in the specified tab'. Distinguishes from siblings like kitty_goto_layout (which sets current layout) and kitty_last_used_layout.
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?
Implies usage for configuring cycling layouts, describes behavior when current layout not in list. No explicit exclusions or alternatives mentioned, but context signals sibling differentiation is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the font size in the active OS window. All sub-windows in the same OS window share the same font size. Use "+N"/"-N" for relative changes, a number for absolute size, or "0" to reset to default.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Apply to all OS windows. | |
| size | Yes | Font size: a number in points (e.g. "14"), "+N" to increase, "-N" to decrease, or "0" to reset. Required. |
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 a key behavioral trait: all sub-windows in the same OS window share font size. However, it omits details on destructive nature, permissions, or error handling, leaving some transparency gaps.
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 extremely concise at two sentences, with no redundant information. The first sentence establishes purpose and a key behavioral point, and the second provides complete parameter guidance. Every word earns its place.
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?
Given the simplicity of the tool (2 parameters, no output schema, no nested objects), the description covers the essential aspects: what it does, how to specify size, and the sharing behavior. It is complete enough for an agent to use correctly, though it could mention return status or confirmation.
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 coverage is 100% with both parameters having descriptions. The description adds significant value beyond the schema by explaining the exact format of the size string (relative changes, absolute, reset) and the effect of the 'all' parameter, which is only briefly described in the 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 clearly states the verb 'Set' and resource 'font size in the active OS window', providing a specific action and context. It also distinguishes behavior by noting that all sub-windows in the same OS window share the same font size, which differentiates it from siblings like kitty_resize_window or kitty_set_spacing.
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 explains how to use the tool with clear formatting for the size parameter ('+N', '-N', number, '0'). It implies the context of active vs all OS windows via the 'all' parameter. However, it does not explicitly state when not to use this tool or compare it to alternatives like kitty_set_spacing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set paddings and margins for specified kitty windows. Settings are "key=value" strings like "margin=20", "padding-left=10", "margin-h=30", "padding-v=5". Use "default" as value to reset.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Apply to all windows. | |
| match | No | Window match expression. | |
| settings | Yes | Array of spacing specs in "key=value" format. Example: ["margin=20", "padding-left=10"]. Required. | |
| match_tab | No | Tab match expression. | |
| configured | No | Also change the configured spacing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It explains the format of settings but omits details about side effects (e.g., immediate application, repaint), scope of effect (e.g., currently focused window), or any potential limitations. The description is minimal in this regard.
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 comprises two sentences that are direct and to the point. It front-loads the purpose and immediately follows with essential usage details. There is no unnecessary information.
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?
Given the tool's simplicity (5 parameters, no output schema), the description covers the key aspects: action, format, and reset behavior. It could mention the default window scope but the schema's 'all' parameter implies it. Overall, it's adequately complete for a setter 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?
Schema description coverage is 100%, so the schema already documents all 5 parameters. The description adds value by explaining the 'key=value' format and the 'default' reset value, but this only marginally augments what is in the 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 clearly states the tool sets paddings and margins for kitty windows. It specifies the resource (kitty windows) and the action (set spacings). While it doesn't explicitly distinguish from siblings, the name and description are sufficiently unique among the listed sibling tools, which focus on other actions like actions, colors, or text.
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 usage examples and mentions using 'default' to reset, which is helpful. However, it does not specify when to use this tool versus alternatives, nor does it offer guidance on prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the foreground/background colors of a tab in the tab bar. Colors can be color names (e.g. "red"), hex values (e.g. "#1e1e2e"), or "none" to revert to the default.
| Name | Required | Description | Default |
|---|---|---|---|
| self | No | Set colors for the tab this command runs in. | |
| match | No | Tab match expression. | |
| colors | Yes | Object mapping color names to values. At least one key required. Example: { "active_bg": "#1e1e2e", "inactive_fg": "gray" }. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that colors can be names, hex values, or 'none' to revert to default, adding useful behavioral info. However, it does not mention persistence, error behavior (e.g., invalid color), or any side effects. With no annotations, this is adequate but not comprehensive.
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 extremely concise—two sentences covering purpose, color formats, and special value 'none'. No filler, front-loaded with the action. Every sentence serves a purpose.
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?
Given no output schema and no annotations, the description is fairly complete for a simple color-setting tool. It explains input format and the special 'none' behavior. It could mention error scenarios or that the 'colors' object requires at least one key, but those are covered in the schema. Missing notes about 'self' and 'match' parameters, but they are documented in the schema.
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 coverage is 100% and well-documented. The description adds meaning beyond the schema by explaining that 'none' reverts to default and that color values can be names or hex. This enriches the 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 states the tool's action: changing foreground/background colors of a tab in the tab bar. It uses a specific verb ('Change') and resource ('colors of a tab'), effectively distinguishing it from siblings like 'kitty_set_colors' and 'kitty_set_background_opacity'.
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 does not provide explicit when-to-use or when-not-to-use guidance. It implies usage for modifying tab bar colors but does not mention alternatives or prerequisites. The context is clear but lacks exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the title for the specified kitty tabs. If no title is provided, resets to the active-window-controlled title.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Tab match expression. | |
| title | Yes | The new title for the tab. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the reset behavior but omits important details like prerequisites (e.g., whether the tab must be in focus), error handling for invalid match expressions, or side effects. With no annotations, more behavioral disclosure is expected.
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, clear sentence with no extraneous information, making it highly concise and well-structured.
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?
Given the simplicity of the tool (2 params, no output schema), the description provides essential information including the reset feature. However, additional details about the match expression and return behavior would enhance completeness.
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 coverage is 100%, but the description adds value by explaining that omitting the title resets to the active-window-controlled title, providing context beyond the schema's basic type/description.
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 tool sets the title for specified kitty tabs and specifies a reset behavior when no title is provided, which distinguishes it from sibling tools like kitty_set_window_title.
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 usage for setting or resetting tab titles but lacks explicit guidance on when to use this tool versus alternatives such as kitty_set_window_title or other tab-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set user variables for the specified kitty windows. User variables are accessible via kitty match expressions (var:NAME). Use "NAME=VALUE" to set, or just "NAME" to unset. If no variables provided, prints current vars.
| Name | Required | Description | Default |
|---|---|---|---|
| var | No | User variable specs as "NAME=VALUE" or "NAME" to unset. | |
| self | No | Target the window this command runs in. | |
| match | No | Window match expression. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It covers basic behavior (set, unset, print) but lacks details on persistence, scope, or side effects. Adequate for a simple tool but could be more transparent.
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?
Three sentences, front-loaded with purpose, each sentence adds necessary information without redundancy. Extremely concise and well-structured.
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?
Given the tool's simplicity and lack of output schema, the description covers core functionality well. It explains the three parameters implicitly and the special case of no arguments. Minor missing details on return values or confirmation, but sufficient for the complexity level.
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 coverage is 100%, but the description adds value by explaining the format of 'var' strings and the no-argument printing behavior. This goes beyond the schema's parameter descriptions.
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 tool sets user variables for kitty windows, and distinguishes itself from other set_* tools by specifying the unique 'var:NAME' match expressions. The verb 'Set' and resource 'kitty windows' are explicit.
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 clear usage patterns ('NAME=VALUE' to set, 'NAME' to unset, no variable to print). It does not explicitly state when not to use this tool, but among siblings it is the only one for user variables, making the context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the title for the specified kitty windows. By default the title is permanent (programs cannot change it). Use temporary to allow programs to change it. Omit title to reset to the child-process-controlled title.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Window match expression. | |
| title | No | The new title. Omit or leave empty to reset to the child-process-controlled title. | |
| temporary | No | Allow programs to change the title afterwards. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It explains the default permanence, the effect of temporary, and the reset behavior, which are key behavioral traits.
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?
Three sentences, front-loaded with the core action, no extraneous words. Efficient and clear.
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?
Given the tool's simplicity and no output schema, the description adequately covers the essential behaviors. Could mention required permissions or side effects if any, but not necessary.
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 coverage is 100%, baseline 3. Description adds context beyond schema by explaining the effect of omitting title and the purpose of temporary, enhancing understanding of parameter usage.
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 action ('Set the title') and the target resource ('kitty windows'), and it distinguishes from sibling tools like kitty_set_tab_title by specifying the resource type.
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?
Provides guidance on when to use the temporary parameter and how to reset the title, but does not explicitly mention alternatives or when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send one or more Unix signals to the foreground process in the specified kitty windows. If no signals are specified, SIGINT is sent by default. Signal names can be with or without the SIG prefix.
| Name | Required | Description | Default |
|---|---|---|---|
| match | No | Window match expression. | |
| signals | No | Signal names to send (e.g. ["TERM"], ["SIGKILL"]). Defaults to ["SIGINT"] if not specified. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. States default signal and prefix handling. Could be more explicit about destructive potential of signals like SIGKILL, but adequate for typical use.
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?
Three concise sentences, front-loaded with core purpose. No redundant information.
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?
Sufficient for a simple two-parameter tool. Covers purpose, default, and naming. Missing edge cases (e.g., invalid match) but not critical.
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 coverage is 100% and already includes default and examples. Description reinforces but adds minimal new information beyond what schema provides.
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?
Clear verb ('Send') and specific resource ('Unix signals to foreground process in kitty windows'). Distinct from siblings like kitty_send_key or kitty_close_window, which deal with different actions.
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?
Provides default behavior (SIGINT) and signal naming convention, but lacks explicit when-to-use or when-not-to-use guidance and does not mention alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0kitty_actionkitty_clear_cachekitty_close_tabkitty_close_windowkitty_create_markerkitty_detach_tabkitty_detach_windowkitty_disable_ligatureskitty_dump_scrollbackkitty_envkitty_focus_tabkitty_focus_windowkitty_get_colorskitty_get_tab_textkitty_get_textkitty_goto_layoutkitty_health_checkkitty_kittenkitty_last_used_layoutkitty_launchkitty_load_configkitty_lskitty_remove_markerkitty_resize_os_windowkitty_resize_windowkitty_runkitty_scrollkitty_select_windowkitty_send_keykitty_send_textkitty_set_background_opacitykitty_set_colorskitty_set_enabled_layoutskitty_set_font_sizekitty_set_spacingkitty_set_tab_colorkitty_set_tab_titlekitty_set_user_varskitty_set_window_titlekitty_signal_childEach tool targets a distinct action on a specific kitty resource, such as windows, tabs, colors, or markers. Descriptions clearly differentiate between similar operations (e.g., kitty_close_tab vs. kitty_close_window, kitty_get_text vs. kitty_get_tab_text), leaving no ambiguity.
All tools follow a consistent 'kitty_<verb>_<noun>' pattern using lowercase and underscores. Even outliers like kitty_action or kitty_env fit the verb_noun structure. No mixing of conventions or unexpected variations.
With 40 tools, the server exceeds the typical well-scoped range (3-15). While each tool serves a specific purpose, the sheer number may overwhelm agents and suggests excessive granularity, making it harder to navigate.
The tool set covers nearly all aspects of kitty terminal management: window/tab lifecycle, text retrieval, configuration, input, scrolling, layouts, and more. Minor gaps exist (e.g., moving windows between tabs, tab reordering), but core workflows are fully supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/secemp9/kitty-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
