iterm2-mcp

by lorencarvalho

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation5/5
Each tool targets a distinct action (e.g., clear, close, create, focus, get, list, read, run, send, set, split, write). Even closely related tools like write_to_terminal and send_control_character have clear differentiation through descriptions.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern in snake_case (e.g., clear_buffer, create_tab, get_variable, set_badge). No mixing of conventions or ambiguous prefixes.
Tool Count4/5
18 tools is slightly above the typical 5-15 range, but each tool has a well-defined purpose covering window, tab, session, and terminal operations. No obvious bloat.
Completeness4/5
Covers core CRUD and lifecycle operations for sessions/tabs/windows, plus screen reading, command execution, variable access, and profile listing. Minor gaps like missing pane resizing or session info retrieval, but nothing critical for automation.
Average 3.9/5 across 18 of 18 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on April 19, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states the tool closes a session and describes the force parameter for skipping confirmation, but fails to mention destructive nature, impact on running processes, or error handling. Important behavioral traits are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, comprising one line for the purpose and two lines for parameters. It is front-loaded with the action, and every sentence serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple close operation with an output schema, the description covers purpose and parameters. However, it lacks guidance on usage context and behavioral transparency. Given the absence of annotations, more details about side effects or prerequisites would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides meaningful parameter explanations: session_id is 'The session UUID to close' and force effect is detailed. This adds value beyond the schema's type/title, though no further details like valid formats or constraints are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Close a specific session,' specifying the verb and resource. This distinguishes it from sibling tools like focus_session or get_active_session. The purpose is immediately clear, but the description is minimal and does not elaborate beyond the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as focus_session or split_pane. The description only explains the force parameter's effect, but offers no context for selecting close_session over other session manipulation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It only lists parameter docstrings and does not disclose behavioral traits such as whether the tab becomes active, side effects, or authentication/rate limits. The description adds minimal behavioral context beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence stating the action plus three parameter lines. No redundant or irrelevant information. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are documented elsewhere. However, the description lacks context about the effects of creating a tab (e.g., whether it gets focus, relationship to sessions) and does not mention any requirements or side effects. It is adequate for a basic understanding but incomplete for full autonomous use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage; the description compensates by providing brief explanations for all three parameters (window_id defaults to current, command is a shell command, profile is an iTerm2 profile). This adds meaning beyond the schema, though descriptions are concise and could be more detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new tab in a window') and the resource ('tab'). It is a specific verb+resource combination, but does not differentiate from sibling tools like 'create_window' or 'split_pane', which operate on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., creating a new window or splitting a pane). There is no mention of prerequisites or contexts where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It states the outcome (window raised, tab/pane selected) but omits error conditions (e.g., invalid session ID), side effects, or whether it is a no-op if already focused. This is incomplete for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences front-loaded with the action, followed by a parameter docstring. Every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and the existence of an output schema (not described), the description is adequate but missing key context: it does not mention that the session must exist, error handling, or what the output contains. It also fails to clarify how it relates to siblings like 'get_active_session'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, which has no property descriptions (0% coverage). It explains the session_id parameter is a UUID and specifies the result of calling the tool, compensating well for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Bring a session to the foreground') and the effect on the session's window and tab/pane. It distinguishes the tool from siblings like 'close_session' or 'get_active_session' by specifying that it activates an existing session, though it does not explicitly contrast with alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when wanting to bring a session to the foreground) but provides no explicit guidance on when not to use or alternatives. For example, it doesn't mention that the session must already exist or that 'get_active_session' could be used to check which is active.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It only states the action ('Set the title/name') without disclosing side effects, permissions required, or what happens to existing titles. For a mutation tool, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and includes param docs in a structured docstring format. However, it could be more concise by omitting the redundant 'title/name' phrase. Still, it earns its keep without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and an output schema (unmentioned), the description is somewhat incomplete. It doesn't explain return values, validation of session_id format, or error conditions. However, for a simple setter, the param coverage partly compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the param docs in the description add significant meaning: 'name' is the new session name, 'session_id' is the target session UUID with a default of active session. This clarifies the role and default behavior beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets a title/name on an iTerm2 session, using a specific verb ('Set') and resource ('title/name of an iTerm2 session'). It distinguishes itself from sibling tools like 'set_badge' (which sets a badge) and 'close_session' (which destroys a session).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings (e.g., 'set_badge' for badge, 'get_variable' for reading). There is no mention of prerequisites, context, or scenarios where alternatives are better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It mentions returning coordinates and default session, but does not disclose whether it is read-only, required permissions, error conditions, or 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded purpose, no redundant information. The parameter doc is integrated nicely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 optional param, output schema exists), the description is fairly complete. It covers purpose and the only parameter. Minor gap: could mention return format, but output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description includes a docstring for the parameter ('Target session UUID. Defaults to the active session.'), which adds meaning beyond the schema's type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns cursor coordinates x,y within the visible screen. The verb 'Return' and resource 'cursor coordinates' are specific and distinguish it from siblings like 'run_command' or 'read_screen'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It does not mention when not to use or provide any context about prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral details. It discloses the prerequisite about the profile's Badge field and the default session behavior, but does not describe side effects like overwriting previous badges or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two short paragraphs plus parameter docstrings. The first sentence front-loads the purpose. However, the param docstring format adds minor redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema but the description does not explain return values. It does provide important setup context (profile interpolation). Missing details on failure modes or cancellation are gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description adds value. For badge it clarifies 'Text to display as the badge.' For session_id it explains 'Target session UUID. Defaults to the active session.' This goes beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set the iTerm2 session badge (translucent overlay text)' and explains the prerequisite about the profile's Badge field referencing \(user.badge). This provides a specific verb and resource, distinguishing it from other session-related sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 set_session_name or focus_session. Does not mention 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as whether the operation is read-only, potential errors, or permissions required. It only states the return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and resource. Every word is necessary and there is no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 an output schema exists, the description is adequate but lacks context about edge cases (e.g., no active session) and error handling. It is minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100%. The description adds no parameter information, which is acceptable as there are none. Baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'ID and name of the currently focused iTerm2 session'. It distinguishes itself from sibling tools like 'list_sessions' by specifying 'currently focused'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 'focus_session' or 'list_sessions'. However, the purpose is straightforward and usage is implied for retrieving the focused session's identity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions it uses an iTerm2-proprietary control sequence, indicating platform-specific behavior. However, it lacks details on side effects (e.g., cursor position, impact on ongoing operations). No annotations exist to compensate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a parameter line. Every sentence adds value, with no redundancy or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter, the description covers the action, mechanism, and parameter. It lacks return value info, but an output schema exists (though not shown). Overall, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes a parameter docstring ('Target session UUID. Defaults to the active session.'), which adds meaning beyond the schema (which only provides type and default). This helps the agent understand usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Clear both the visible screen and the scrollback buffer,' which is a specific verb+resource. It distinguishes from sibling tools like read_screen or send_control_character by focusing on buffer clearing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or context about when clearing is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full behavioral burden. It discloses that adding a newline causes command execution and defaults session to active, but omits details on side effects (e.g., error handling if session is invalid) or synchronous behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured as a docstring with clear parameter breakdown. It is efficient without extraneous content, though slightly verbose due to reStructuredText formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is an output schema but no return value description, and parameter explanations are basic, the description leaves gaps (e.g., character encoding, error cases). It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains all three parameters: 'text' as characters, 'session_id' with default behavior, and 'add_newline' with example usage. This adds meaningful context beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Send text to an iTerm2 session' which is a specific verb-resource combination. It distinguishes itself from siblings like 'run_command' and 'send_control_character' by focusing on raw text input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for using 'add_newline' (e.g., set False for interactive prompts) but does not explicitly clarify when to use this tool versus alternatives like 'run_command' for sending commands or 'send_control_character' for control keys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only states what the tool lists, without mentioning side effects, permissions, or read-only nature. While listing is inherently read-only, the description does not confirm this or other 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It clearly and efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no nested objects) and the presence of an output schema, the description is complete enough. It tells the agent what the tool does without needing further elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters and 100% schema description coverage, so the description adds no parameter information. Baseline is 3, and the description does not need to add value beyond the schema here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all iTerm2 profiles with their names and GUIDs.' It uses a specific verb ('List') and resource ('iTerm2 profiles'), and distinguishes itself from sibling tools like 'list_sessions' or 'close_session' by focusing on profiles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to see available profiles), but does not explicitly state when to use it versus alternatives. However, given the tool's simplicity and the lack of overlapping functionality among siblings, the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It discloses that a new window is created and parameter defaults, but lacks details on side effects (e.g., focus behavior, error conditions, or session identification).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief with two sentences: one for purpose and one structured parameter documentation. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, return values need not be explained. The description covers the tool's purpose and both parameters adequately. Minor omission: no mention of prerequisites like iTerm2 running.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with only titles and types. The description adds meaningful details: 'command' is an optional shell command, 'profile' is a profile name defaulting to default. This compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new iTerm2 window' with a specific verb and resource. It distinguishes from sibling tools like create_tab (creates tab in existing window) and split_pane (splits pane).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage is clear (when a new window is needed), but no explicit guidance on when to use this vs alternatives like create_tab or split_pane, nor 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description does not disclose side effects, permission requirements, or error behavior. However, the action is simple and low-risk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is brief, well-structured, with param documentation inline, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, reducing need for return value explanation. Description covers input details but lacks error handling or result info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description adds valuable context: accepted formats for letter (A-Z, ESC, ESCAPE, ]) and session_id defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool sends a control character to an iTerm2 session and lists supported values, distinguishing it from siblings like send_escape_sequence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains supported values and default session but does not explicitly state when to use this tool over alternatives like send_escape_sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states the split direction but lacks details on side effects (e.g., whether the original session remains active) or failure modes. This is 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a parameter list. It is efficient and front-loaded with the core action. The structure is clear and scannable, though the docstring format is slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no required parameters, and the description covers the default behavior (active session). An output schema exists, so return value documentation is not needed. The description is sufficient for an agent to understand the tool's effect and parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description's parameter comments add needed meaning. For example, 'vertical: If True, split left/right; if False, split top/bottom' clarifies the boolean. The description compensates well for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Split an iTerm2 pane horizontally or vertically,' which is a specific verb-resource pair. Among siblings like 'create_tab' and 'close_session,' this tool's purpose is uniquely distinguished as splitting an existing pane.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for splitting a pane, which is a distinct operation from creating tabs or windows. However, it does not explicitly mention when not to use it or provide alternatives, but the context is clear given sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description discloses that reading certain variables requires shell integration and explains the naming convention for custom variables (prefix user.). This adds valuable 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the key action, followed by a list of examples and parameter docs. It is concise with no wasted sentences, though the parameter section could be slightly more integrated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the two parameters, no annotations, and existing output schema, the description provides adequate context. It explains variable availability and default behavior, making the tool understandable for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description thoroughly explains both parameters: provides examples for 'name' (common names and prefix) and clarifies that 'session_id' defaults to the active session. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function as reading an iTerm2 session variable, with specific examples of commonly useful names. This distinguishes it from sibling tools like run_command or send_escape_sequence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (reading session variables) and gives common variable names, but does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses the return format (tree with IDs) and the presence of a focused marker. It does not cover possible side effects, but being 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with the key information front-loaded. Every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, clear output), the description provides all necessary information: what is listed, the return format, and the marker meaning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the baseline is 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all windows, tabs, and sessions, and mentions it returns a tree with session IDs and a marker for the focused item, distinguishing it from siblings like get_active_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating session IDs can be passed to other tools, but does not explicitly state when to use or provide alternatives. However, the context is clear enough for a listing tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses ANSI escape stripping, trailing blank line trimming, and default session behavior. It's sufficient 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just 4 sentences, front-loaded with the core purpose, followed by essential behavioral notes and parameter docs. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters, an existing output schema, and low complexity, the description covers key aspects. Minor gap: no error handling or auth info, but acceptable for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds clear meaning for both parameters: session_id is a target UUID defaulting to active, max_lines returns last N lines. This fully compensates for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads visible contents of an iTerm2 session as plain text, distinguishing it from siblings like run_command or write_to_terminal. The verb 'read' and resource 'visible contents' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for reading screen content but does not explicitly contrast with siblings or provide exclusions. However, the context is clear enough for an AI agent to infer when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: blocking wait for completion, dependency on PromptMonitor, timeout handling with a [timeout] marker, and return of the resulting screen. This is comprehensive for a command execution tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two paragraphs), with the main purpose front-loaded and parameter details clearly listed. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (3 params, 1 required) and the presence of an output schema, the description covers prerequisites, behavior, and edge cases, making it fully sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides meaningful explanations for all three parameters (command, session_id, timeout_seconds), including defaults and purpose. It adds value beyond the schema's bare names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a command and waits for completion, returning the screen output. It specifies the resource (command execution in iTerm2) and the action (run and wait), distinguishing it from siblings like read_screen or write_to_terminal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the prerequisite of iTerm2 shell integration and explains the timeout behavior, but does not explicitly guide when to use this tool versus alternative sibling tools like write_to_terminal or send_control_character.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that Python string escapes are interpreted before sending, a key behavioral trait. It also notes the default for session_id. It does not mention potential error handling or side effects, but overall provides good transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of three sentences that front-load the purpose and then detail parameters. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown), the description covers the essential context: purpose, parameter semantics, and escape interpretation behavior. It misses any mention of prerequisites or error conditions, but for a simple tool with two parameters, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description includes parameter details: 'sequence' is the escape sequence string with Python escape interpretation, and 'session_id' is target session UUID with default. It adds significant meaning beyond the schema's bare type/name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sends a raw escape sequence to an iTerm2 session, with examples like clear screen and cursor home. It distinguishes from siblings such as send_control_character and write_to_terminal by specifying 'raw escape sequence' and explaining Python escape interpretation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that Python string escapes are interpreted, which guides usage. It also indicates session_id defaults to active session. However, it does not explicitly state when to use this over alternatives like send_control_character or write_to_terminal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![iterm2-mcp MCP server](https://glama.ai/mcp/servers/lorencarvalho/iterm2-mcp/badges/card.svg)](https://glama.ai/mcp/servers/lorencarvalho/iterm2-mcp)

Score Badge

Copy to your README.md:

[![iterm2-mcp MCP server](https://glama.ai/mcp/servers/lorencarvalho/iterm2-mcp/badges/score.svg)](https://glama.ai/mcp/servers/lorencarvalho/iterm2-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lorencarvalho/iterm2-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server