<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Detection Rule Optimization

## Agent Tools

| Tool | Description |
|---|---|
| Performance Profiler | `profile_performance(rules)` — Identify slow rules |
| Optimization Advisor | `suggest_optimization(query, time)` — Query tuning suggestions |
| Stagger Planner | `plan_staggering(rules, interval)` — Distribute execution load |

## CLI Usage

```bash
# Profile rules
node agent.js profile --rules '[{"rule_id": "r1", "exec_time_seconds": 45}]'

# Optimize query
node agent.js optimize --query "search * | where user=admin" --time 45

# Plan staggering
node agent.js stagger --rules '[{"rule_id": "r1"}]' --interval 30
```

## Output Format

All commands return JSON with the following structure:

```json
{
  "action": "<command_name>",
  "...": "command-specific fields"
}
```

## Error Handling

- Invalid input returns `{"error": "description"}` with non-zero exit code
- JSON parsing errors are caught and reported with context
- Missing required arguments trigger argparse help display
