Server has 13 well-named tools with consistent verb_noun patterns (list_, get_, set_, post_). All tools have descriptions (avg ~80 chars, within baseline). Input schemas are present and typed for all tools. However, descriptions are terse and lack context for LLM selection, most are single-sentence statements without WHEN/WHY guidance. Parameter descriptions are minimal (e.g., 'Optional session ID' repeated 11 times). Output schemas are not documented, LLMs cannot predict response structure. Error handling is generic (RuntimeError wrapping). No pagination, no result limits documented, no recovery guidance. Security is reasonable (no secrets in params, read-only tools marked), but write tools lack confirmation patterns.

• Document output schemas for all tools. Add a 'Returns' section to each docstring: 'Returns: {windows: [{id: str, tabs: [{id: str, sessions: [{id: str, title: str, ...}]}]}]}'.
• Expand tool descriptions to 100-200 chars with WHEN/WHY context. Example: 'get_screen_contents: Returns the currently visible terminal buffer and cursor position. Use this to see what the user sees right now. Use get_scrollback() for historical output or get_recent_output() for incremental updates since a cursor.'
• Replace boilerplate parameter descriptions with specific guidance. Instead of 'Optional session ID; if not provided, uses ITERM_SESSION_ID environment variable', write 'Session ID (optional; defaults to current session from ITERM_SESSION_ID env var). Pass a specific session ID to target a different window/tab.'
• Add recovery guidance to error responses. Catch known failures (e.g., profile format mismatch for set_badge) and return actionable messages: 'Badge format not supported by profile. Call list_profiles() to find profiles with user.badge support, or update the profile settings.'
• For write tools, add a dry_run parameter or document the idempotency guarantee. E.g., 'set_badge is idempotent, calling it twice with the same text has the same effect as calling it once.'