# MCP Tools Rationale: User-Facing vs Internal

## Decision: Expose Only User-Facing Capabilities

**Principle**: MCP tools should expose **user-facing capabilities**, not internal implementation details.

---

## ✅ Tools Exposed (User-Facing)

### 1. `dcisionai_solve` ⭐ **REQUIRED**
**Why**: This is what users want - solve optimization problems.

**What it does**:
- Takes problem description
- Runs full workflow (classification → intent → solve → explain)
- Returns complete results

**User Value**: ✅ High - Primary use case

### 2. `dcisionai_solve_with_model` ⭐ **USEFUL**
**Why**: Users with deployed models want to use them directly.

**What it does**:
- Uses pre-built models (Portfolio Optimization, etc.)
- Faster than full solve for known problem types
- Model-specific input/output

**User Value**: ✅ High - For users with deployed models

---

## ❌ Tools NOT Exposed (Internal Implementation)

### `dcisionai_classify_problem` - **REMOVED**
**Why**: Classification is an internal step of `dcisionai_solve`.

**Reasoning**:
- Users don't need to classify separately
- Classification is always part of solve workflow
- Exposing it adds complexity without value
- Results are included in `dcisionai_solve` output

**Status**: ❌ Internal implementation detail

### `dcisionai_extract_intent` - **REMOVED**
**Why**: Intent extraction is an internal step of `dcisionai_solve`.

**Reasoning**:
- Users don't need to extract intent separately
- Intent extraction is always part of solve workflow
- Entities/objectives/constraints are in solve results
- Exposing it adds complexity without value

**Status**: ❌ Internal implementation detail

### `dcisionai_explain_solution` - **REMOVED**
**Why**: Explanation is included in `dcisionai_solve` results.

**Reasoning**:
- Business explanation is part of solve workflow
- Users get explanation automatically with results
- No need for separate tool call
- Reduces API surface area

**Status**: ❌ Included in solve results

---

## Architecture: Internal vs External

### Internal Workflow (Not Exposed)
```
dcisionai_solve()
  ├── classify_problem()        ← Internal
  ├── extract_intent()          ← Internal
  │   ├── extract_entities()
  │   ├── extract_objectives()
  │   └── extract_constraints()
  ├── generate_pyomo()          ← Internal
  ├── solve()                   ← Internal
  └── explain_solution()        ← Internal (but results included)
```

### External API (Exposed)
```
dcisionai_solve(problem_description)
  → Returns: {
      classification: {...},      ← Included in results
      entities: [...],            ← Included in results
      objectives: [...],          ← Included in results
      constraints: [...],        ← Included in results
      solution: {...},            ← Included in results
      explanation: {...}         ← Included in results
    }
```

**Key Point**: Users get all the information they need from `dcisionai_solve`. No need to expose internal steps.

---

## Benefits of Minimal Tool Set

### 1. **Simpler API**
- Fewer tools = easier to understand
- Less confusion about which tool to use
- Clear primary use case

### 2. **Better Performance**
- Users don't call multiple tools unnecessarily
- Single call gets everything
- No redundant processing

### 3. **Cleaner Architecture**
- Internal implementation can change without breaking API
- Clear separation: user-facing vs internal
- Easier to maintain

### 4. **Better User Experience**
- One tool does everything
- No need to understand internal workflow
- Results include all information

---

## Comparison: Planning vs Production

### Original Planning (9 Tools)
- `dcisionai_solve` ✅
- `dcisionai_classify_problem` ❌ (internal)
- `dcisionai_extract_intent` ❌ (internal)
- `dcisionai_solve_with_model` ✅
- `dcisionai_generate_data` ❓ (maybe useful)
- `dcisionai_explain_solution` ❌ (included in solve)
- `dcisionai_validate_pyomo_code` ❌ (internal)
- `dcisionai_validate_pyomo_model` ❌ (internal)
- `dcisionai_get_solver_recommendation` ❌ (internal)

### Production (2 Tools) ⭐
- `dcisionai_solve` ✅ - Main tool
- `dcisionai_solve_with_model` ✅ - Deployed models

**Result**: 78% reduction in API surface area, 100% of user needs met.

---

## Resources Still Exposed

Resources are read-only data, so they're fine to expose:
- `dcisionai://models/list` - Users need to know available models
- `dcisionai://solvers/list` - Users might want solver info

These don't expose internal implementation, just metadata.

---

## Future Considerations

### If Users Request Internal Tools
- **Option 1**: Add them back (if there's clear user need)
- **Option 2**: Create separate endpoints in FastAPI first
- **Option 3**: Document that results include this information

### Data Generation Tool
- `dcisionai_generate_data` might be useful for some users
- Could be added if there's demand
- Currently not exposed (not in current API)

---

## Summary

**Expose**: User-facing capabilities only
- ✅ `dcisionai_solve` - Main optimization
- ✅ `dcisionai_solve_with_model` - Deployed models

**Don't Expose**: Internal implementation details
- ❌ Classification (part of solve)
- ❌ Intent extraction (part of solve)
- ❌ Explanation (included in solve results)
- ❌ Validation (internal checks)

**Result**: Cleaner, simpler API that meets all user needs.

