# Prompts and Resources

Understanding MCP Resources and Prompts - advanced features that help AI agents discover and learn.

## What Are MCP Resources?

Resources are named, readable content that AI agents can discover and browse directly, similar to how humans browse documentation.

### Key Differences from Tools

| Feature | Tools | Resources |
| --------- | ------- | ----------- |
| **Purpose** | Execute commands | Read documentation |
| **Input** | Required parameters | Resource URI |
| **Output** | Command results | Document content |
| **Use Case** | Actions | Learning and discovery |
| **Agent Behavior** | Call with parameters | Browse and read |

### How Agents Use Resources

Instead of searching or guessing:

```bash
Agent: "I want to import data but I'm not sure how"

Traditional (without resources):
- Agent calls hana_search → finds import.md
- Agent guesses at parameters
- Agent tries import (may fail)

With Resources:
- Agent lists available resources
- Agent reads hana://docs/commands/import
- Agent learns correct usage
- Agent succeeds first time
```

## Available Resources

### Core Documentation Resources

#### Project Overview

- `hana://docs/overview` - Project introduction and features
- `hana://docs/getting-started` - Installation and setup guide

#### Connection and Setup

- `hana://docs/connection-guide` - 7-step connection resolution
- `hana://docs/security` - Security best practices
- `hana://docs/parameters` - Standard parameter conventions

#### Architecture and Design

- `hana://docs/best-practices` - Naming conventions and patterns
- `hana://docs/project-structure` - Project folder organization
- `hana://docs/implementation` - Technical implementation details

### Category Guides

Organized by functionality:

- `hana://docs/categories/data-quality` - Data validation, profiling, duplicates
- `hana://docs/categories/performance` - Performance analysis and tuning
- `hana://docs/categories/data-operations` - Import, export, sync
- `hana://docs/categories/inspection` - Schema, table, view exploration
- `hana://docs/categories/backup` - Backup and recovery operations
- `hana://docs/categories/security` - User management and security
- `hana://docs/categories/btp` - SAP BTP integration

### Command Documentation

Individual command guides (available for all 150+ commands):

- `hana://docs/commands/import` - Import command with examples
- `hana://docs/commands/export` - Export command with examples
- `hana://docs/commands/dataValidator` - Data validation guide
- `hana://docs/commands/dataProfile` - Data profiling guide
- `hana://docs/commands/compareSchema` - Schema comparison guide
- `hana://docs/commands/[any-command]` - Any command documentation

**Each command resource includes:**

- Detailed description
- All parameters explained
- Use cases and examples
- Common issues and solutions
- Related commands

### Examples and Presets

- `hana://examples/import` - 5 real-world import scenarios
- `hana://examples/export` - 3 export scenarios
- `hana://examples/data-migration` - Migration examples
- `hana://presets/safe-import` - Safe import parameter template
- `hana://presets/quick-export` - Quick export template

### Workflow Resources

Pre-built task sequences:

- `hana://workflows/data-quality-check` - Data quality check workflow
- `hana://workflows/schema-migration` - Schema migration workflow
- `hana://workflows/performance-baseline` - Performance baseline workflow
- `hana://prompts` - All available prompts and guide workflows

## What Are MCP Prompts?

Prompts are guided conversation templates that help AI agents follow structured workflows for common tasks.

### How Prompts Work

Prompts provide:

1. **Multi-step guidance** - Step-by-step instructions
2. **Context preservation** - Information carries through steps
3. **Best practices** - Baked-in standards
4. **Error prevention** - Validation and checks
5. **Learning support** - Explanations and tips

### Example Prompt Flow

**User:** "Help me safely import customer data"

**System:** Invokes `import-data` prompt

**Prompt Steps:**

```bash
📋 SAFE DATA IMPORT WORKFLOW

Step 1: Verify Source File
└─ Review file location and format
   └─ Expected: CSV, Excel, or TSV file

Step 2: Inspect Target Table
└─ Examine table structure and constraints
   └─ Required: INSERT privilege on table

Step 3: Preview Import (Dry Run)
└─ Run import in preview mode
   └─ Shows what would be imported without actual changes

Step 4: Review Errors
└─ Check dry run results
   └─ Decide: Proceed or fix data issues

Step 5: Execute Import
└─ Run actual import with selected options
   └─ Progress tracking and error handling

Step 6: Validate Results
└─ Verify imported data
   └─ Check count and sample records
   └─ Run quality checks if needed
```

## Available Prompts

### 1. Explore Database (`explore-database`)

**Duration:** 15-30 minutes

**Parameters:**

- `schema` (optional) - Specific schema to explore

**Guided Steps:**

1. Verify database connection
2. Check database version and system info
3. List all schemas
4. For each interesting schema:
   - List tables
   - Inspect some table structures
5. Profile data quality if interested
6. Summarize findings

**Outcomes:**

- Understanding of database structure
- Schema catalog
- Sample table definitions
- Data quality overview

### 2. Import Data Safely (`import-data`)

**Duration:** 20-40 minutes

**Parameters:**

- `filename` (required) - File to import
- `table` (optional) - Target table
- `schema` (optional) - Target schema

**Guided Steps:**

1. Verify file exists and is readable
2. Inspect target table structure
3. Preview import with dry-run
4. Review and resolve errors
5. Execute actual import (if approved)
6. Validate imported data
7. Generate import report

**Outcomes:**

- Successful safe import
- Error documentation
- Validation report

### 3. Troubleshoot Connection (`troubleshoot-connection`)

**Duration:** 20-40 minutes

**Parameters:** None required

**Guided Steps:**

1. Check basic connectivity
2. Verify credentials
3. Test database connection
4. Review user privileges
5. Check schema access
6. Diagnose specific issues
7. Provide remediation steps

**Outcomes:**

- Diagnosed connection issue
- Recommended solutions
- Verified working connection

### 4. Validate Data Quality (`validate-data-quality`)

**Duration:** 30-60 minutes

**Parameters:**

- `table` (required) - Table to validate
- `schema` (optional) - Target schema

**Guided Steps:**

1. Profile the table (data distribution, nulls, etc.)
2. Check for duplicate records
3. Run data validator
4. Analyze issues found
5. Get recommendations
6. Generate quality report

**Outcomes:**

- Data quality assessment
- Issue prioritization
- Remediation recommendations

### 5. Quick Start (`quickstart`)

**Duration:** 15-30 minutes

**Parameters:** None required

**Perfect for:** First-time users

**Teaches:**

1. `hana_status` - Verify connection
2. `hana_version` - Check database version
3. `hana_schemas` - List schemas
4. `hana_tables` - Explore tables
5. `hana_inspectTable` - View table structure
6. `hana_healthCheck` - System health

**Outcomes:**

- Understanding of basic commands
- Confidence in CLI usage
- Ready for advanced workflows

### 6. Export Data Safely (`export-data`)

**Duration:** 20-40 minutes

**Parameters:**

- `table` (required) - Table to export
- `schema` (optional) - Source schema
- `format` (optional) - CSV, Excel, or TSV

**Guided Steps:**

1. Verify source table exists
2. Check user has SELECT privilege
3. Configure export format
4. Preview export
5. Execute export
6. Verify export file
7. Validate data integrity

**Outcomes:**

- Successfully exported file
- Export validation report
- Format verification

## How Agents Use Resources and Prompts

### Resource Discovery Workflow

```bash
1. Agent: "I need help with..."
   
2. System: Lists available resources
   - hana://docs/getting-started
   - hana://docs/commands/import
   - hana://examples/import
   - hana://workflows/data-migration
   
3. Agent: "Show me hana://docs/commands/import"
   
4. System: Reads and formats resource
   - Title, description
   - All parameters explained
   - 5 usage scenarios
   - Common issues
   
5. Agent: Confident in tool usage
   
6. Agent: Runs import command
```

### Prompt-Guided Workflow

```bash
1. User: "Help me explore the database"
   
2. Agent: Invokes explore-database prompt
   
3. System: Returns structured guidance
   Step 1: Verify connection
   Step 2: Check version
   Step 3: List schemas
   ...
   
4. Agent: Follows steps in order
   - Runs each command
   - Reviews results
   - Proceeds to next step
   
5. System: Automatically suggests next steps
   based on results
   
6. User: Gets clear understanding
   of database structure
```

## Combining Resources and Prompts

### Example: Learn Import by Resources, Execute by Prompt

```bash
Step 1: Resources (Learning)
- Agent reads hana://docs/commands/import
- Agent reviews hana://examples/import
- Agent understands options and best practices

Step 2: Prompt (Execution)
- Agent invokes "import-data" prompt
- Follows step-by-step guidance
- Ensures safe import

Step 3: Resources (Validation)
- If issues arise, agent reads hana://docs/troubleshooting
- Gets solutions from resources
- Applies fixes
```

### Example: Performance Tuning

```bash
Step 1: Understand
- Agent reads hana://docs/categories/performance
- Agent reviews hana://workflows/performance-baseline
- Agent learns approach

Step 2: Execute
- Agent invokes relevant workflow
- Gets structured guidance
- Collects metrics

Step 3: Interpret
- Agent reads performance results
- Gets recommendations
- Plans improvements

Step 4: Implement & Verify
- Agent follows hana_get_template("performance-tuning")
- Implements suggestions
- Re-measures and compares
```

## Best Practices

### For Agent Developers

1. **Start with Resource Discovery**

   ```typescript
   resources = await listResources()
   // Shows available learning material
   ```

2. **Use Prompts for Complex Tasks**

   ```typescript
   await invokePrompt('import-data', { file: 'data.csv' })
   // Provides structured guidance
   ```

3. **Chain Resources and Prompts**

   ```bash
   Read resource → Invoke prompt → Execute → Validate
   ```

4. **Leverage Context**
   - Resources provide context
   - Prompts build on context
   - Results inform next steps

### For Users (Best Practices)

1. **Explore Resources First**
   - Get familiar with available help
   - Learn best practices
   - See examples

2. **Use Prompts for New Tasks**
   - Follow guided workflows
   - Avoid mistakes
   - Learn as you work

3. **Combine Both**
   - Resources for learning
   - Prompts for execution
   - Both for confidence

## Benefits

### For AI Agents

✅ **Reduced tool calls** - Read documentation instead of searching
✅ **Better context** - Full information available
✅ **Guided workflows** - Structured multi-step processes
✅ **Error prevention** - Validation steps built in
✅ **Better outcomes** - Follows best practices

### For Users

✅ **Self-service learning** - Agents can learn from resources
✅ **Structured guidance** - Prompts prevent mistakes
✅ **Quick results** - Faster task completion
✅ **Best practices** - Guided toward optimal approaches
✅ **Confidence** - Clear steps and expectations

## Future Enhancements

Potential additions to resources and prompts:

1. **Video Tutorials**
   - `hana://videos/import-guide`
   - `hana://videos/performance-tuning`

2. **Interactive Guides**
   - Better step feedback
   - Real-time validation
   - Progress tracking

3. **Custom Resources**
   - User-created guides
   - Organization-specific docs
   - Custom workflows

4. **Smart Recommendations**
   - Context-aware prompts
   - Personalized workflows
   - Adaptive guidance

## Next Steps

- **[Discovery Tools](./discovery-tools.md)** - Finding commands by intent
- **[Advanced Features](./advanced-features.md)** - Workflows and interpretation
- **[Implementation Phases](./implementation-phases.md)** - Technical details
- **[Main Documentation Index](./index.md)** - Overview of all features