> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Tips and strategies for getting the most from the evaluation system

## Writing effective tasks

### Start with clear objectives

Define success criteria upfront:

<CodeGroup>
  ```text Good theme={null}
  Calculate 15% commission on $50,000. Expected result: $7,500
  ```

  ```text Better theme={null}
  Calculate 15% commission on $50,000 sale. Verify calculation matches 
  $7,500. Send result to manager@company.com with breakdown.
  ```
</CodeGroup>

### Use progressive complexity

Start simple, then increase complexity:

<Steps>
  <Step title="Week 1: Simple tasks">
    Basic calculations, single-step operations
  </Step>

  <Step title="Week 2: Medium tasks">
    Research, multi-step workflows
  </Step>

  <Step title="Week 3: Complex tasks">
    Multiple tools, external integrations
  </Step>

  <Step title="Week 4: Production use">
    Full automation, batch processing
  </Step>
</Steps>

***

## Checkpoint strategies

### When to use auto-detect

<Check>**Use auto-detect when:**</Check>

* You're new to the system
* Task involves external actions (emails, purchases)
* You don't know optimal verification points
* Task complexity is high

**Example:**

```json theme={null}
{
  "autoDetectCheckpoints": true,
  "testMode": "with-verification"
}
```

### When to use manual checkpoints

<Check>**Use manual checkpoints when:**</Check>

* Testing specific decision points
* You know exactly where verification is needed
* Task has well-defined stages
* Regulatory requirements dictate specific checks

**Example:**

```json theme={null}
{
  "checkpoints": [
    {"stage": "calculation", "description": "Verify math"},
    {"stage": "submission", "description": "Approve sending"}
  ],
  "testMode": "with-verification"
}
```

### Optimal checkpoint placement

<Tip>
  **2-4 checkpoints** is ideal for most tasks

  * Too few (0-1): May miss critical verification points
  * Just right (2-4): Balance oversight with efficiency
  * Too many (5+): Slows down evaluation, verification fatigue
</Tip>

***

## Verification workflow tips

### Responding to checkpoints

<CardGroup cols={3}>
  <Card title="approve" icon="check">
    Agent continues to next step
  </Card>

  <Card title="reject" icon="xmark">
    Agent stops execution
  </Card>

  <Card title="hint: [text]" icon="lightbulb">
    Agent adjusts approach with your guidance
  </Card>
</CardGroup>

### Using hints effectively

<AccordionGroup>
  <Accordion title="When to use hints">
    * Agent is close but needs adjustment
    * You want to guide without rejecting
    * Teaching agent better approaches
    * Minor corrections needed
  </Accordion>

  <Accordion title="Good hint examples">
    ```
    hint: Use CoinMarketCap instead of CoinGecko for more accurate prices
    hint: Include all team members in the CC field
    hint: Round to 2 decimal places
    hint: Use the Alternative Simplified Credit method, not regular method
    ```
  </Accordion>

  <Accordion title="Bad hint examples">
    ```
    hint: Do it better
    hint: Wrong
    hint: Not that
    ```

    Be specific about what to change!
  </Accordion>
</AccordionGroup>

***

## Testing strategies

### Baseline comparisons

Always run tasks both ways to measure human impact:

```bash theme={null}
# Run 1: With verification
{
  "taskName": "Task A - With Human",
  "testMode": "with-verification",
  "autoDetectCheckpoints": true
}

# Run 2: Without verification (baseline)
{
  "taskName": "Task A - Baseline",
  "testMode": "without-verification"
}
```

**Metrics to compare:**

* Success rate
* Execution time
* Cost per task
* Error rate
* Quality scores

### A/B testing checkpoints

Test different checkpoint strategies:

```bash theme={null}
# Version A: Auto-detect
{
  "taskName": "Test - Auto Checkpoints",
  "autoDetectCheckpoints": true
}

# Version B: Manual
{
  "taskName": "Test - Manual Checkpoints",
  "checkpoints": [/* specific points */]
}

# Version C: No checkpoints
{
  "taskName": "Test - No Checkpoints",
  "testMode": "without-verification"
}
```

Compare which approach gives best results for your use case.

***

## Performance optimization

### Batch processing

Submit multiple tasks efficiently:

```python theme={null}
import concurrent.futures
import requests

def submit_task(task_data):
    response = requests.post(
        "https://app.mixus.ai/api/eval/create-task-agent",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=task_data
    )
    return response.json()

# Submit 10 tasks in parallel
tasks = [create_task_data(i) for i in range(10)]
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
    results = list(executor.map(submit_task, tasks))
```

<Warning>
  **Rate limits:** Max 10 concurrent evaluations per organization
</Warning>

### Webhook vs polling

<CardGroup cols={2}>
  <Card title="Use Webhooks" icon="webhook">
    **When:** Long-running tasks (>5 min)

    **Benefits:**

    * No polling overhead
    * Real-time notifications
    * Lower API usage
  </Card>

  <Card title="Use Polling" icon="rotate">
    **When:** Short tasks (\<5 min)

    **Benefits:**

    * Simpler setup
    * No server needed
    * Direct control
  </Card>
</CardGroup>

### Optimizing task descriptions

<Tip>
  **Shorter is faster**

  Agent processing time increases with description length. Be concise but clear.
</Tip>

<CodeGroup>
  ```text Before (Slow) theme={null}
  Research all available information about the top three artificial intelligence 
  agent platforms currently available in the market, including detailed pricing 
  information for all tiers and plans, comprehensive lists of features and 
  capabilities, target market analysis, and competitive positioning...
  ```

  ```text After (Fast) theme={null}
  Research top 3 AI agent platforms: pricing (all tiers), key features, 
  target market. Create comparison table.
  ```
</CodeGroup>

***

## Cost optimization

### Understanding costs

Evaluation costs include:

* **AI model usage** - Based on tokens processed
* **Tool usage** - External API calls (web search, integrations)
* **Verification overhead** - Human review time (no additional cost)

### Reducing costs

<AccordionGroup>
  <Accordion title="1. Use baseline mode for simple tasks">
    Skip verification for low-risk tasks:

    ```json theme={null}
    {"testMode": "without-verification"}
    ```

    Saves verification overhead, completes faster.
  </Accordion>

  <Accordion title="2. Optimize checkpoint count">
    Fewer checkpoints = lower cost:

    * Auto-detect typically finds 1-3 checkpoints
    * Manual: Only checkpoint truly critical steps
    * Baseline: No checkpoints = lowest cost
  </Accordion>

  <Accordion title="3. Batch similar tasks">
    Group related tasks to reuse context:

    ```json theme={null}
    [
      {"taskName": "Calc 1", "description": "15% of $50k"},
      {"taskName": "Calc 2", "description": "15% of $75k"},
      {"taskName": "Calc 3", "description": "15% of $100k"}
    ]
    ```
  </Accordion>

  <Accordion title="4. Use precise task descriptions">
    Reduce unnecessary research and tool calls:

    ```json theme={null}
    // More expensive
    {"description": "Find crypto prices and calculate"}

    // Less expensive
    {"description": "Calculate: 0.5 BTC × $42,000 + 10 ETH × $2,200"}
    ```
  </Accordion>
</AccordionGroup>

***

## Quality assurance

### Validation strategies

<Steps>
  <Step title="Define expected outcomes">
    Specify what "correct" looks like before running
  </Step>

  <Step title="Run with verification first">
    Verify agent behavior manually before automation
  </Step>

  <Step title="Compare with baseline">
    Measure improvement from human oversight
  </Step>

  <Step title="Iterate on prompts">
    Refine task descriptions based on results
  </Step>
</Steps>

### Tracking quality metrics

Monitor these metrics over time:

```python theme={null}
metrics = {
    "success_rate": 0.95,      # % of successful completions
    "approval_rate": 0.92,     # % of checkpoints approved
    "rejection_rate": 0.05,    # % of checkpoints rejected
    "hint_rate": 0.03,         # % of checkpoints needing hints
    "avg_duration": 180,       # Average seconds to complete
    "avg_cost": 2.50,          # Average cost per task
}
```

<Tip>
  **Target metrics:**

  * Success rate: >90%
  * Approval rate: >85%
  * Rejection rate: \<10%
  * Hint rate: \<15%
</Tip>

***

## Team collaboration

### Assigning reviewers

Match reviewers to task expertise:

```json theme={null}
{
  "financial_tasks": "cfo@company.com",
  "marketing_tasks": "cmo@company.com",
  "technical_tasks": "cto@company.com",
  "legal_tasks": "legal@company.com"
}
```

### Review response times

Set expectations for checkpoint responses:

<CardGroup cols={3}>
  <Card title="Urgent" icon="bolt">
    **\< 5 minutes**

    Financial transactions, customer communications
  </Card>

  <Card title="Normal" icon="clock">
    **\< 1 hour**

    Research, analysis, reports
  </Card>

  <Card title="Low Priority" icon="hourglass">
    **\< 24 hours**

    Baseline tests, experiments
  </Card>
</CardGroup>

### Sharing results

Export evaluation results for team review:

```bash theme={null}
# Get all evaluation results
curl https://app.mixus.ai/api/eval/results \
  -H "Authorization: Bearer mxs_eval_YOUR_KEY" \
  > team_eval_results.json

# Share with team
```

***

## Common pitfalls

<Warning>
  ### Avoid these mistakes
</Warning>

<AccordionGroup>
  <Accordion title="❌ Vague task descriptions">
    **Problem:** "Research AI companies"

    **Solution:** "Research OpenAI, Anthropic, Google DeepMind pricing"
  </Accordion>

  <Accordion title="❌ Too many checkpoints">
    **Problem:** 8 checkpoints for simple calculation

    **Solution:** 1-2 checkpoints, or use auto-detect
  </Accordion>

  <Accordion title="❌ No baseline comparison">
    **Problem:** Only testing with verification

    **Solution:** Run same task without verification for comparison
  </Accordion>

  <Accordion title="❌ Ignoring metrics">
    **Problem:** Not tracking success/failure rates

    **Solution:** Monitor dashboard, export metrics regularly
  </Accordion>

  <Accordion title="❌ Not using hints">
    **Problem:** Rejecting when small adjustment would work

    **Solution:** Use `hint:` to guide agent to correct approach
  </Accordion>
</AccordionGroup>

***

## Advanced patterns

### Chained evaluations

Run sequential tasks where output of one feeds into next:

```python theme={null}
# Task 1: Research
result1 = submit_task({
    "taskName": "Research Phase",
    "taskDescription": "Research competitor pricing"
})

execution_id_1 = result1["executionId"]
wait_for_completion(execution_id_1)

# Get Task 1 results
results_1 = get_execution_results(execution_id_1)

# Task 2: Analysis (using Task 1 results)
result2 = submit_task({
    "taskName": "Analysis Phase",
    "taskDescription": f"Analyze pricing data: {results_1['output']}"
})
```

### Conditional workflows

Run different tasks based on results:

```python theme={null}
result = submit_task({
    "taskName": "Check Inventory",
    "taskDescription": "Check if Product X has inventory > 100"
})

wait_for_completion(result["executionId"])
inventory_result = get_results(result["executionId"])

if inventory_result["inventory"] > 100:
    # High inventory - run discount campaign task
    submit_task({
        "taskName": "Discount Campaign",
        "taskDescription": "Create 20% discount campaign for Product X"
    })
else:
    # Low inventory - run restock task
    submit_task({
        "taskName": "Restock Alert",
        "taskDescription": "Send restock alert to procurement team"
    })
```

### Template-based tasks

Create reusable task templates:

```python theme={null}
TASK_TEMPLATES = {
    "commission_calc": {
        "taskName": "Commission Calculation",
        "taskDescription": "Calculate {rate}% commission on ${amount}",
        "autoDetectCheckpoints": true,
        "testMode": "with-verification"
    },
    "competitor_research": {
        "taskName": "Competitor Research",
        "taskDescription": "Research {company} pricing and features",
        "autoDetectCheckpoints": true,
        "testMode": "with-verification"
    }
}

# Use template
task = TASK_TEMPLATES["commission_calc"].copy()
task["taskDescription"] = task["taskDescription"].format(
    rate=15,
    amount=50000
)
submit_task(task)
```

***

## Troubleshooting

### Task fails immediately

<Steps>
  <Step title="Check task description">
    Ensure it's clear and actionable
  </Step>

  <Step title="Verify reviewer exists">
    Reviewer must be registered mixus user
  </Step>

  <Step title="Check API key permissions">
    Needs `eval:create` scope
  </Step>

  <Step title="Review error message">
    Look in response or dashboard for details
  </Step>
</Steps>

### Checkpoint not triggering

Possible causes:

* Auto-detect didn't identify action as high-risk
* Task description too vague
* Action type not in checkpoint criteria

**Solution:** Use manual checkpoints to force verification at specific points.

### Slow verification responses

Tips for faster reviews:

* Use mobile notifications
* Set up Slack alerts
* Assign backup reviewers
* Use webhooks for real-time notifications

***

## Next steps

<CardGroup cols={2}>
  <Card title="Examples" icon="lightbulb" href="/evaluation/examples">
    See 10+ ready-to-use tasks
  </Card>

  <Card title="API Reference" icon="code" href="/eval-api">
    Complete API documentation
  </Card>

  <Card title="Get Started" icon="rocket" href="/evaluation/getting-started">
    Submit your first task
  </Card>

  <Card title="Task Preparation" icon="pen" href="/evaluation/task-preparation">
    Write better tasks
  </Card>
</CardGroup>