---
name: improve-descriptions
description: |
  Trigger this skill when improving action descriptions in a connector:

  **Triggers:**
  - "improve descriptions for [provider]"
  - "enhance action descriptions"
  - "make descriptions more detailed"
  - "improve [provider] connector descriptions"
  - When descriptions are generic or unclear

  **What it does:**
  1. Launches autonomous improve_descriptions subagent
  2. Analyzes each action's description and details
  3. Enhances with specific, actionable information
  4. Makes descriptions agent-friendly and user-oriented
  5. Returns improved YAML configuration

  **Expected duration:** 2-5 minutes for comprehensive improvements.
---

# Description Improvement Skill

## Overview

This skill uses an autonomous agent to analyze and improve action descriptions in connector configurations, making them more specific, actionable, and useful for both humans and AI agents.

## When to Use

**Automatic triggers:**
- After initial config building (descriptions often generic)
- Before MCP connector testing
- When agent struggles to understand actions

**Manual triggers:**
- User explicitly asks to improve descriptions
- Preparing connector for production release
- After adding many new actions

## Why Description Quality Matters

### The Problem

**Generic descriptions don't help:**
```yaml
# ❌ BAD - Too generic
- actionId: get_user
  description: Get a user
  details: Gets a user by ID

# Users don't know:
# - What user information is returned?
# - What's required to call this?
# - When should I use this vs list_users?
```

**Agents can't make good decisions:**
- "Show me user details" → Might call wrong action
- "Find active employees" → Doesn't know which action filters
- "Get user with manager info" → Doesn't know if included

### The Solution

**Specific, actionable descriptions:**
```yaml
# ✅ GOOD - Specific and helpful
- actionId: get_user
  description: Retrieve complete user profile including email, name, role, and department
  details: |
    Fetches detailed information about a specific user by their unique ID.
    Returns full profile including: email, first/last name, role, department,
    manager ID, hire date, and custom fields. Use this after finding user ID
    from list_users. Does not include sensitive data like SSN or salary.

# Now clear:
# - What's returned (profile fields)
# - When to use it (after list_users)
# - What's NOT included (sensitive data)
```

## Prerequisites

- Existing connector YAML configuration
- Provider name
- YAML validates successfully

## Execution Flow

### Step 1: Read Current Configuration

```bash
# Read connector YAML
cat connectors/<provider>/<provider>.connector.s1.yaml

# Read all partials
find connectors/<provider> -name "*.partial.yaml" -exec cat {} \;
```

### Step 2: Identify Improvement Needs

**Look for these red flags:**

1. **Generic verbs only:** "Get", "List", "Create", "Update"
2. **No specifics:** What data? What fields? What format?
3. **Missing use cases:** When to use this action?
4. **No context:** How does this relate to other actions?
5. **Ambiguous scope:** What's included vs excluded?

**Example red flags:**
```yaml
# Red flag: Generic
description: Get message

# Red flag: No details
description: List items
details: Lists all items

# Red flag: Ambiguous
description: Update settings
# Which settings? All? Specific ones?
```

### Step 3: Launch Improvement Agent

```typescript
// Launch async improvement (2-5 minutes)
const result = improve_descriptions({
  config: yamlConfigAsString,
  maxIterations: 3              // Default: 3 (focused improvements)
});

// Extract taskId
const taskId = result.taskId;
```

### Step 4: Poll for Status

```typescript
// Check status every 30-60 seconds
const status = get_improve_descriptions_task_status(taskId, "provider_name");

// Status progression:
// "pending" → Task queued
// "running" → Active improvement (shows iteration/maxIterations)
// "complete" → Finished successfully
// "error" → Failed
```

**Expected Timeline:**
- **Minute 0:** Launch task
- **Minutes 0-1:** Status = "pending"
- **Minutes 1-5:** Status = "running"
- **Minute 5:** Status = "complete"

### Step 5: Extract Improved YAML

```typescript
// When status = "complete"
const improvedYaml = status.result;

// Save improved version
fs.writeFileSync(
  `connectors/<provider>/<provider>.connector.s1.yaml`,
  improvedYaml
);
```

### Step 6: Review Changes

**Compare before/after:**

```bash
# Show differences
git diff connectors/<provider>/<provider>.connector.s1.yaml

# Review each change
# - Is description more specific?
# - Does details add value?
# - Are use cases clear?
```

### Step 7: Validate Improved Config

```bash
# MANDATORY: Re-validate after improvements
stackone validate connectors/<provider>/<provider>.connector.s1.yaml

# Must return: ✓ Validation successful
```

## Improvement Patterns

### Pattern 1: Add Specific Field Information

**Before:**
```yaml
- actionId: get_user
  description: Get user information
  details: Retrieves user data from the system
```

**After:**
```yaml
- actionId: get_user
  description: Retrieve complete user profile including email, name, role, department, and manager
  details: |
    Fetches detailed information about a specific user by their unique ID.
    Returns: email, first_name, last_name, role, department, manager_id,
    hire_date, status (active/inactive), and custom_fields object.
    Use this after obtaining user ID from list_users. Required scope: users:read.
```

### Pattern 2: Clarify When to Use

**Before:**
```yaml
- actionId: list_users
  description: List all users
  details: Gets a list of users
```

**After:**
```yaml
- actionId: list_users
  description: Retrieve paginated list of all users with optional status filtering
  details: |
    Fetches directory of all users in the organization. Supports filtering
    by status (active, inactive, pending) and pagination via cursor. Returns
    basic profile info (id, name, email, status). Use this to discover user IDs,
    then call get_user for full details. Maximum 100 results per page.
```

### Pattern 3: Distinguish Similar Actions

**Before:**
```yaml
- actionId: get_message
  description: Get a message
  details: Gets message details

- actionId: get_thread
  description: Get a thread
  details: Gets thread details
```

**After:**
```yaml
- actionId: get_message
  description: Retrieve single email message with full content, headers, and attachments
  details: |
    Fetches complete details of a specific email message by ID. Returns subject,
    sender, recipients, body (text/html), attachment list, headers, labels, and
    thread ID. Use this for reading individual emails. For conversation context,
    use get_thread instead.

- actionId: get_thread
  description: Retrieve entire email conversation with all messages in chronological order
  details: |
    Fetches a complete email thread/conversation by thread ID. Returns array of
    all messages in the conversation chronologically, with subject, participants,
    and message count. Use this to view full conversation history. For single
    email content, use get_message instead.
```

### Pattern 4: Document Prerequisites and Scope

**Before:**
```yaml
- actionId: create_user
  description: Create a new user
  details: Creates a user account
```

**After:**
```yaml
- actionId: create_user
  description: Create new user account with email, name, and role assignment
  details: |
    Creates a new user in the organization. Required fields: email (must be unique),
    first_name, last_name. Optional: role (default: member), department, manager_id.
    Sends invitation email to user. Returns newly created user with assigned ID.
    Requires admin:write scope. Email domain must match organization's verified domains.
```

### Pattern 5: Explain Limitations and Gotchas

**Before:**
```yaml
- actionId: delete_item
  description: Delete an item
  details: Deletes the specified item
```

**After:**
```yaml
- actionId: delete_item
  description: Permanently delete item (cannot be undone)
  details: |
    Permanently deletes the specified item by ID. WARNING: This action is
    irreversible and cannot be undone. Item will be immediately removed from
    all lists and searches. Child items are NOT automatically deleted - handle
    separately if needed. Returns 204 No Content on success. Requires delete scope.
```

### Pattern 6: Add Use Case Examples

**Before:**
```yaml
- actionId: search_messages
  description: Search for messages
  details: Searches messages by query
```

**After:**
```yaml
- actionId: search_messages
  description: Search emails by sender, subject, body content, or date range
  details: |
    Powerful search across all email messages. Supports filters: from (sender email),
    to (recipient), subject (keywords), body (content), after/before (date range),
    has:attachment, is:unread, label:name. Returns list of matching message IDs with
    snippets. Example queries: "from:boss@company.com", "subject:invoice after:2025-01-01",
    "has:attachment is:unread". Maximum 500 results, use pagination for more.
```

## Agent Improvements

The improvement agent automatically:

✅ **Adds specific field names** - Not just "user data", but "email, name, role"
✅ **Documents return values** - What fields are in the response
✅ **Clarifies when to use** - Context for choosing this action
✅ **Lists prerequisites** - Required scopes, permissions, setup
✅ **Highlights limitations** - What's NOT included, constraints
✅ **Provides examples** - Concrete use cases or query formats
✅ **Distinguishes from similar actions** - Why use this vs that
✅ **Warns about gotchas** - Irreversible operations, side effects

## Quality Checklist

### Every Action Should Have

- [ ] Specific field names mentioned
- [ ] Return value format described
- [ ] Use cases explained
- [ ] Prerequisites listed (if any)
- [ ] Limitations documented (if any)
- [ ] Relationship to other actions clarified
- [ ] Examples provided (for complex actions)

### Description (Short)

- [ ] 1-2 sentences maximum
- [ ] Mentions key returned fields
- [ ] Action-oriented (starts with verb)
- [ ] No redundancy with actionId

### Details (Long)

- [ ] 3-6 sentences
- [ ] Comprehensive field list
- [ ] Use case explanation
- [ ] Relationship to other actions
- [ ] Prerequisites and scope
- [ ] Warnings or limitations

## Integration with Workflow

### After Config Building

```typescript
// Step 4: Config building complete
console.log("Connector YAML created");

// Step 4.5: Improve descriptions (optional but recommended)
console.log("Improving action descriptions...");

const configYaml = fs.readFileSync(
  `connectors/${provider}/${provider}.connector.s1.yaml`,
  'utf-8'
);

const { taskId } = improve_descriptions({
  config: configYaml,
  maxIterations: 3
});

// Poll for completion
let status;
do {
  await sleep(45000);  // 45 seconds
  status = get_improve_descriptions_task_status(taskId, provider);
  console.log(`Improvement progress: ${status.status}`);
} while (status.status !== "complete");

// Save improved version
fs.writeFileSync(
  `connectors/${provider}/${provider}.connector.s1.yaml`,
  status.result
);

// Validate improved config
await exec(`stackone validate connectors/${provider}/${provider}.connector.s1.yaml`);

// Step 5: Proceed to validation
```

### Before MCP Testing

**Recommended: Run improvement before MCP testing to ensure agent-friendly descriptions.**

```typescript
// Improve descriptions first
improve_descriptions(...);

// Then run MCP tests
// Agent will have better context to select correct actions
```

## Output Report

```markdown
## Description Improvement Report: <provider>

### Summary
- Total Actions: 42
- Actions Improved: 38
- Unchanged: 4 (already comprehensive)
- Duration: 4 minutes

### Improvements by Category

#### Specificity Added (18 actions)
- Added field names to return descriptions
- Documented request/response formats
- Listed specific data types

#### Use Cases Clarified (15 actions)
- Explained when to use action
- Related to other actions
- Provided example scenarios

#### Prerequisites Documented (8 actions)
- Listed required scopes
- Noted permission requirements
- Documented setup steps

#### Limitations Noted (12 actions)
- Documented constraints
- Warned about irreversible operations
- Clarified what's NOT included

### Example Improvements

**list_users:**
- Before: "List all users"
- After: "Retrieve paginated list of all users with optional status filtering"
- Added: Pagination details, filter options, field list

**get_message:**
- Before: "Get a message"
- After: "Retrieve single email message with full content, headers, and attachments"
- Added: Specific fields returned, distinguished from get_thread

**delete_item:**
- Before: "Delete an item"
- After: "Permanently delete item (cannot be undone)"
- Added: Irreversibility warning, scope requirement, response details

### Actions Skipped (Already Good)
- create_webhook (already comprehensive)
- update_settings (already specific)
- batch_update (already detailed with examples)
- send_notification (already clear with use cases)

### Validation
- Status: ✅ Passed
- No syntax errors introduced
- All improvements preserved structure

### Next Steps
- [ ] Review git diff for changes
- [ ] Test with MCP agent (if applicable)
- [ ] Proceed to action tracking and testing
```

## Key Principles

1. **Be specific** - Mention actual field names, not generic "data"
2. **Provide context** - When to use, how it relates to other actions
3. **Document limits** - What's included, what's not, constraints
4. **Help selection** - Give enough info for smart action choice
5. **Keep structure** - Don't break YAML syntax

## Anti-Patterns (NEVER DO THESE)

- ❌ Accepting generic "Get X" descriptions
- ❌ No field names in descriptions
- ❌ Unclear when to use vs similar actions
- ❌ Missing prerequisites or scopes
- ❌ Not warning about irreversible operations
- ❌ Breaking YAML syntax during improvement
- ❌ Skipping validation after improvements