Last updated: Aug 12, 2025, 01:09 PM UTC

Tool Message UX Improvements Plan

Created: 2025-08-09
Purpose: Incremental improvements to tool message display in ChatInterface
Status: In Progress

Goal

Improve the user experience of tool messages in the chat interface by making them:

  • More compact and less cluttered
  • Business-friendly with clear, contextual descriptions
  • Visually distinguished by status (running, complete, failed)
  • Easy to scan without overwhelming technical details

Implementation Phases

Phase 1: Basic Cleanup (Safe Changes)

1. Remove Tool ID Display

Priority: High | Risk: None | Status: Pending

Current State:

  • Shows cryptic tool ID like tool_use_abc123xyz next to tool name
  • Located at lines 311-313 in ChatInterface.jsx
  • Adds no value for end users

Change:

// Remove this span entirely:
<span className="text-xs text-blue-600 dark:text-blue-400 font-mono">
  {message.toolId}
</span>

Impact: Cleaner header, less technical clutter

2. Simplify Tool Box Design

Priority: High | Risk: Low | Status: Pending

Current State:

  • Large blue bordered box with padding (lines 299-330)
  • Takes up significant vertical space
  • Heavy visual weight

Change:

  • Remove the blue box wrapper
  • Keep tool info inline with lighter styling
  • Use subtle left border instead of full box

New Structure:

// Instead of:
<div className="bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg p-2 sm:p-3 mb-2">

// Use:
<div className="border-l-2 border-blue-400 pl-3 py-1 mb-2">

3. Improve Tool Icons

Priority: Medium | Risk: None | Status: Pending

Current State:

  • Complex gear SVG for all tools
  • No visual distinction between tool types
  • Already have Phosphor icons imported but underutilized

Change:

  • Use specific icons from existing getToolDescription function
  • Add color coding based on status
  • Keep icons small and inline

Icon Mapping (already defined):

  • Read: FileText icon
  • Write: PencilSimple icon
  • Bash: Terminal icon
  • Search: MagnifyingGlass icon
  • etc.

Color Scheme:

  • Running: Blue (animate-pulse)
  • Complete: Green
  • Failed: Red
  • Pending: Gray

4. Add Context to Tool Descriptions

Priority: High | Risk: Low | Status: Pending

Current State:

  • Generic descriptions: "Running system command"
  • No indication of what's actually happening

Change:

  • Extract context from tool inputs
  • Display specific information

Examples:

  • Bash: "Running: npm install" instead of "Running system command"
  • Edit: "Editing: ChatInterface.jsx" instead of "Updating document"
  • Grep: "Searching for: getToolDescription" instead of "Searching for information"

Implementation:

// Add helper function to extract context
const getToolContext = (toolName, toolInput) => {
  try {
    const input = JSON.parse(toolInput);
    switch(toolName) {
      case 'Bash':
        return input.command?.split(' ').slice(0, 3).join(' ');
      case 'Edit':
      case 'Read':
      case 'Write':
        return input.file_path?.split('/').pop();
      case 'Grep':
        return input.pattern?.substring(0, 30);
      // etc.
    }
  } catch {}
  return null;
};

Phase 2: Enhanced Feedback (Moderate Changes)

5. Add Tool Status Indicators

Priority: Medium | Risk: Low | Status: Planned

Features:

  • Small status dots/icons
  • Execution time display
  • Subtle animations for running state

Visual Indicators:

  • ● (pulsing) - Running
  • ✓ - Complete
  • ✗ - Failed
  • ○ - Pending

6. Collapse Tool Details by Default

Priority: Medium | Risk: Low | Status: Planned

Change:

  • Hide detailed tool input/output by default
  • Show only essential information
  • Add expand/collapse chevron

7. Hide Technical Parameters

Priority: Low | Risk: Low | Status: Planned

Change:

  • Don't show raw JSON
  • Display human-readable summaries
  • Keep raw data in expandable section

Phase 3: Advanced Improvements (Careful Implementation)

8. Group Consecutive Tool Uses

Priority: Low | Risk: Medium | Status: Planned

Concept:

  • When multiple tools run in sequence
  • Group them as "Running 3 operations..."
  • Expandable to see individual tools

9. Better Error Display

Priority: Medium | Risk: Low | Status: Planned

Improvements:

  • Red accent for errors
  • Clear error messages
  • Suggestions for common issues

10. Improve Special Tool Displays

Priority: Low | Risk: Low | Status: Planned

Tools Needing Special Treatment:

  • Read: Show file preview
  • TodoWrite: Display task changes
  • Edit: Show diff inline

Implementation Guidelines

Safety Principles

  1. Incremental Changes: Each change should be independent
  2. No JSX Structure Changes: Avoid changing nesting or conditional structure
  3. Test After Each Change: Run build and verify functionality
  4. Preserve Functionality: Don't remove features, only improve presentation

Testing Checklist

  • Build passes without errors
  • Tool messages display correctly
  • Expand/collapse still works
  • Dark mode compatibility
  • Mobile responsive

Code Locations

  • Main component: src/components/ChatInterface.jsx
  • Tool descriptions: Lines 135-170
  • Tool message display: Lines 298-1100
  • Status handling: Could add state tracking for execution status

Success Metrics

  • Reduced Visual Clutter: Less vertical space per tool message
  • Improved Scannability: Users can quickly understand what's happening
  • Better Context: Clear indication of what each tool is doing
  • Professional Appearance: Business-friendly language and presentation

Next Steps

  1. Start with Phase 1 changes (1-4)
  2. Test thoroughly after each change
  3. Get user feedback
  4. Proceed to Phase 2 if successful
  5. Consider Phase 3 based on results

Notes

  • All changes should maintain existing functionality
  • Focus on visual improvements without structural changes
  • Keep JSX nesting intact to avoid parsing errors
  • Each change can be reverted independently if issues arise