@debugmcp/mcp-debugger/docs/dynamic-tool-documentation-summary.md

Run-time step-through debugging for LLM agents.

# Phase 5: Dynamic Tool Documentation - Implementation Summary

## Overview
Successfully implemented dynamic tool documentation that provides context-aware path instructions to LLMs based on the runtime environment (host mode vs container mode).

## Problem Solved
LLMs using the MCP debug server had no visibility into where the server was running or how to format paths correctly. They would learn path requirements through trial and error after receiving error messages.

## Implementation Details

### 1. Added Dynamic Path Description Helper
Created `getPathDescription()` method in `src/server.ts` that:
- Detects container mode via `PathTranslator.isContainerMode()`
- Gets current working directory from the environment
- Returns appropriate descriptions based on mode:
  - **Container Mode**: "Path to the {parameterName} (relative to /workspace mount point). Example: 'src/main.py'"
  - **Host Mode**: "Path to the {parameterName} (absolute or relative to server's working directory: {cwd}). Examples: 'src/main.py' or '{fullPath}'"

### 2. Updated Tool Registration
Modified `registerTools()` to use dynamic descriptions for:
- `set_breakpoint` - `file` parameter
- `start_debugging` - `scriptPath` parameter  
- `get_source_context` - `file` parameter

### 3. Test Coverage
Created comprehensive test suite in `tests/unit/server/dynamic-tool-documentation.test.ts`:
- **Host Mode Tests**: Verify CWD inclusion, handle long paths, special characters
- **Container Mode Tests**: Verify /workspace references, no absolute paths
- **Consistency Tests**: Ensure proper terminology (source file vs script)
- **Serialization Tests**: Confirm MCP response format

## Technical Challenges Resolved

1. **Environment Access**: Initially tried to create new dependencies which didn't have mocked values. Fixed by reusing the environment from the provided PathTranslator in tests.

2. **Test Implementation**: Had to carefully mock the MCP SDK's request handler registration to capture and test the dynamic tool descriptions.

3. **TypeScript Types**: Resolved type issues by properly handling the handler capture and invocation in tests.

## Benefits

1. **Improved LLM Experience**: LLMs now receive clear, upfront guidance on path formatting
2. **Reduced Errors**: No more trial-and-error path attempts
3. **Context Awareness**: Descriptions adapt automatically based on runtime mode
4. **Clear Examples**: Each description includes practical examples

## Code Quality
- All tests passing (11/11)
- Maintained high code coverage
- Clean implementation with minimal changes to existing code
- Follows established patterns in the codebase

## Next Steps
The dynamic tool documentation is now fully implemented and tested. LLMs will receive appropriate path formatting instructions immediately when querying available tools, significantly improving the user experience.