# MCP Tools Interface Cleanup Plan

Date: 2026-02-01

## Goals
- Simplify and standardize tool names for notebook and pipeline operations.
- Replace single-purpose notebook tools with a clean definition-based interface.
- Reduce parameter naming ambiguity (e.g., display_name vs name).
- Keep functional coverage while allowing breaking changes (beta phase).

## Scope
### Notebook tools
- Rename tools for clarity and consistency.
- Add a generic notebook definition update tool.
- Integrate lakehouse attachment into create/update definition flows.

### Pipeline tools
- Unify pipeline creation into a single tool that accepts optional definitions.

### Parameter naming
- Standardize on `notebook_name` and `item_name` (remove `*_display_name`).
- Add folder path convenience for item moves.

## Proposed Changes (Breaking)

### Notebook Tools
1. **Rename** `import_notebook_to_fabric` → `create_notebook`
   - Accepts a notebook definition (ipynb JSON) as input.
   - Optional `folder_path` and `description` preserved.

2. **Remove** `attach_lakehouse_to_notebook`
   - Replace with optional `default_lakehouse_name` (+ optional `lakehouse_workspace_name`) on:
     - `create_notebook`
     - `update_notebook_definition`
   - Default behavior: if not provided, no changes to dependencies.

3. **Add** `update_notebook_definition`
   - Inputs: `workspace_name`, `notebook_name`, `notebook_content` (JSON dict).
   - Optional: `default_lakehouse_name`, `lakehouse_workspace_name`.
   - Behavior:
     - Fetch notebook definition in ipynb format.
     - Preserve existing `metadata.dependencies` unless lakehouse args provided.
     - Replace ipynb payload with supplied content.
     - Update definition via `updateDefinition`.

4. **Rename** `get_notebook_content` → `get_notebook_definition`
   - Return full definition as today.

5. **Rename** `get_notebook_execution_details` → `get_notebook_run_details`
6. **Rename** `list_notebook_executions` → `list_notebook_runs`

7. **Parameter normalization**
   - Use `notebook_name` consistently (no `notebook_display_name`).

### Pipeline Tools
8. **Replace** `create_blank_pipeline` + `create_pipeline_with_definition` with `create_pipeline`
   - Parameters:
     - `workspace_name`, `display_name`, `description`, `folder_path`
     - Optional `pipeline_content_json`
     - Optional `platform`
   - Behavior:
     - If `pipeline_content_json` is omitted, create a blank pipeline.
     - If provided, create with definition.

### Item Tool Parameter Cleanup
9. **Rename** `item_display_name` → `item_name` in `get_item` and `delete_item` tools.
10. **Add** `target_folder_path` to `move_item_to_folder` to avoid folder IDs.

## Implementation Outline

### Notebook
- Add new service method: `update_notebook_definition` in `services/notebook.py`.
  - Reuse `getDefinition?format=ipynb` logic already used in `attach_lakehouse_to_notebook`.
  - Apply lakehouse metadata patch only if `default_lakehouse_name` provided.
  - Encode updated ipynb payload and call `updateDefinition`.
- Update tools in `tools/notebook_tools.py`:
  - Replace `import_notebook_to_fabric` tool with `create_notebook`.
  - Remove `attach_lakehouse_to_notebook` tool.
  - Add `update_notebook_definition` tool.
  - Rename `get_notebook_content`, `get_notebook_execution_details`, `list_notebook_executions`.
  - Update parameter names to `notebook_name`.
- Update tool registry and counts in `tools/__init__.py` and `README.md`.

### Pipeline
- Add new service method `create_pipeline` or adapt existing `create_blank_pipeline` and `create_pipeline_with_definition` to a single entry point in the tool layer.
- Deprecate/remove old tool functions.
- Update registry and docs.

### Item Tools
- Rename params in `get_item`, `delete_item` to `item_name` (keep `item_id` as alt).
- Add optional `target_folder_path` to `move_item_to_folder` and resolve folder ID via existing folder path resolution.

## Tests
- Update unit tests for notebook tools/services:
  - `create_notebook` happy path.
  - `update_notebook_definition` happy path with/without lakehouse metadata.
  - Rename assertions for run tools.
- Update pipeline tool tests:
  - `create_pipeline` blank and with definition.
- Update item tool tests:
  - `get_item`, `delete_item` parameter rename.
  - `move_item_to_folder` with `target_folder_path`.

## Migration Notes (Doc)
- Provide a short migration guide in `docs/` explaining name changes.
- Update README tool list and counts.

## Open Questions
- Confirm default behavior for `update_notebook_definition`:
  - Preserve metadata unless lakehouse args provided (recommended).
- Confirm `create_notebook` input format:
  - JSON dict vs raw string (recommended: JSON dict).

