Configuration and Constraints

This document helps you configure endpoints correctly. Instead of explaining every field, it focuses on the decisions you need to make and their consequences.

Decision 1: Cron vs. Interval

Question: Should I use a cron expression or fixed interval?

Use Cron When:

Scheduled business logic - Tasks tied to calendar/clock times:

Daily reports at 2 AM: "0 2 * * *"
Hourly data sync: "0 * * * *"
Weekday batch jobs: "0 9 * * 1-5"
End-of-month processing: "0 0 1 * *"

Pros: Predictable timing, aligns with business schedules, easy to reason about

Cons: Can't be tightened by AI (AI interval hints don't apply to cron), uneven spacing (monthly crons have 28-31 day gaps)

Use Interval When:

Continuous monitoring - Tasks measuring ongoing state:

Queue depth checks every 5 minutes: 300000ms
Health checks every 30 seconds: 30000ms
Metric collection every 1 minute: 60000ms

Pros: AI can tighten/relax (adaptive), consistent spacing, simple math

Cons: Drifts from clock (5min interval ≠ :00, :05, :10...), no calendar awareness

Decision Tree:

Does the task care about specific clock times?
├─ Yes → Use cron
│   Example: "Run daily at 3 AM"
└─ No → Use interval
    ├─ Do you want AI adaptation?
    │   ├─ Yes → Use interval (AI can adjust)
    │   └─ No → Either works (prefer interval for simplicity)
    └─ Example: "Check every 5 minutes"

Common Mistake:

❌ Using cron for monitoring: "*/5 * * * *" (every 5 minutes) ✅ Use interval instead: 300000 (AI can tighten to 1 minute during incidents)

Cron works, but you lose adaptive capability. Reserve cron for calendar-aware tasks.

Decision 2: Setting Min/Max Intervals

Question: Should I set minIntervalMs and maxIntervalMs constraints?

When to Set Min Interval:

Rate limiting - External service has request limits:

API allows 100 requests/hour → minIntervalMs: 36000 (36 seconds)
Database writes limited to 1/second → minIntervalMs: 1000

Cost control - Execution is expensive:

AI analysis costs $0.10/run → minIntervalMs: 300000 (5 min minimum)
External API charges per call → Set based on budget

Resource protection - Prevent overwhelming systems:

Heavy computation → minIntervalMs: 60000 (1 min minimum)
Large data transfers → Set based on capacity

Effect: Governor clamps any schedule (baseline, AI hints) to this minimum. Even if AI proposes 10-second interval, endpoint runs at minimum interval.

When to Set Max Interval:

Staleness limits - Data can't be too old:

Real-time monitoring → maxIntervalMs: 300000 (5 min max)
Fraud detection → maxIntervalMs: 60000 (1 min max)

SLA requirements - Guaranteed check frequency:

"Must check health every 10 minutes" → maxIntervalMs: 600000

Effect: Governor clamps any schedule to this maximum. If AI tries to relax to 30 minutes, endpoint runs at maximum interval.

Default Strategy:

Start without constraints, then add if needed:

Deploy with baseline only (no min/max)
Monitor execution patterns
Add minIntervalMs if hitting rate limits or costs spike
Add maxIntervalMs if data gets too stale

Constraints are hard limits—they override everything, including AI. Use them sparingly.

Example Configurations:

Health check (must run frequently, no rate limits):

{
  "baselineIntervalMs": 30000,
  "minIntervalMs": null,
  "maxIntervalMs": 120000
}

AI can tighten to 30s (baseline) but not exceed 2 minutes.

External API call (rate limited):

{
  "baselineIntervalMs": 60000,
  "minIntervalMs": 30000,
  "maxIntervalMs": null
}

AI can relax beyond 1 minute but never tighten below 30 seconds.

Expensive operation (cost control):

{
  "baselineIntervalMs": 300000,
  "minIntervalMs": 180000,
  "maxIntervalMs": 900000
}

Constrained to 3-15 minute range, AI operates within that window.

Decision 3: Timeout Configuration

Question: What timeout should I set?

Rule of Thumb:

timeout = p95 latency × 2 + buffer

Example: If your endpoint usually completes in 2 seconds (p95), set timeout to 5-10 seconds.

What Happens on Timeout:

Request is cancelled
Run status marked as "timeout"
Failure count increments
Exponential backoff applies (interval increases)

Set timeout high enough to avoid false failures, but low enough to prevent zombie runs consuming resources.

Common Mistake:

❌ Setting timeout too low: timeout: 5000 for 10-second operation Result: Frequent timeout failures, exponential backoff kicks in, endpoint runs less frequently

✅ Set based on actual performance: timeout: 30000 with 10-second p95

Decision 4: Response Body Design

Question: What should my endpoint return?

Minimum Viable Response:

{
  "status": "success",
  "timestamp": "2025-11-02T14:30:00Z"
}

AI can work with just execution status, but you get better adaptation with richer data.

Good Response (Monitoring Endpoint):

{
  "status": "healthy",
  "queue_depth": 45,
  "processing_rate_per_min": 100,
  "error_rate_pct": 1.2,
  "avg_latency_ms": 150,
  "capacity_pct": 35,
  "timestamp": "2025-11-02T14:30:00Z"
}

AI can detect:

Growing queue (tighten interval)
High error rate (investigate immediately)
Low capacity usage (relax interval)

Great Response (Coordination Endpoint):

{
  "status": "healthy",
  "metrics": {
    "queue_depth": 45,
    "error_rate_pct": 1.2
  },
  "coordination": {
    "ready_for_downstream": true,
    "upstream_healthy": true,
    "batch_id": "2025-11-02"
  },
  "actions": {
    "last_alert_sent_at": "2025-11-02T12:00:00Z",
    "last_scale_up_at": null
  },
  "timestamp": "2025-11-02T14:30:00Z"
}

AI can:

Detect trends in metrics
Coordinate with siblings (batch_id, ready flags)
Apply cooldowns (check last_alert_sent_at)

What to Include:

Metrics that change: Queue depth, error rates, latencies (not static config)
Status indicators: healthy/degraded/critical, true/false flags
Timestamps: Enable cooldown calculations, staleness checks
Coordination signals: For multi-endpoint workflows
Thresholds: Show when to take action (queue_max, warning_threshold)

What to Exclude:

Large arrays: Truncated at 1000 chars, wastes tokens
Deeply nested objects: Hard for AI to parse
Static data: Endpoint name, config (AI already has this)
Sensitive data: Logged and stored, consider security

Decision 5: Pause vs. Constraints

Question: Should I use pause_until or constraint clamping?

Use Pause When:

Temporary shutdowns:

Maintenance windows
Dependency outages
Manual emergency stop

Effect: Endpoint doesn't run at all until pause expires

Set via: AI tool pause_until() or API

Use Max Interval When:

Slow down but don't stop:

Rate limiting (hit API limits, back off)
Cost control (reduce frequency but keep monitoring)

Effect: Endpoint runs, but not faster than max interval

Set via: Endpoint configuration

Comparison:

Scenario	Use Pause	Use Max Interval
Database maintenance	✓
Rate limit hit (429 response)	✓
Cost budget exceeded		✓
Dependency unavailable	✓
Weekend-only execution	✓
Slow down monitoring		✓

Rule: If you want zero executions, use pause. If you want less frequent executions, use max interval.

Constraint Interaction: How Limits Stack

Understanding how constraints interact:

Priority Order:

Pause (highest priority)
- If pausedUntil > now, return that time (source: "paused")
- Nothing else matters
Governor candidate selection
- Choose between baseline, AI interval hint, AI one-shot hint
- AI interval overrides baseline
- One-shot competes with others
Min/Max clamping (lowest priority)
- Clamp chosen candidate to [now + min, now + max]
- Applies to all candidates (baseline, AI hints)

Example Flow:

Baseline: 5 minutes (300000ms)
Min: 1 minute (60000ms)
Max: 10 minutes (600000ms)
AI proposes: 30 seconds (30000ms)
Pause: Not set

Governor logic:
1. Check pause → Not paused, continue
2. Choose candidate → AI interval (30000ms) overrides baseline
3. Clamp to min → 30000ms < 60000ms (min), adjust to 60000ms
4. Clamp to max → 60000ms < 600000ms (max), no change
5. Result: 60000ms (1 minute), source: "clamped-min"

Key insight: Min/max are hard limits. AI can propose anything, but Governor enforces bounds.

Decision 6: Writing Effective Descriptions

Question: What should I write in my endpoint description?

Your endpoint description tells the AI when and how to adapt the schedule. This is your primary configuration mechanism—more important than constraints for controlling behavior.

What a Good Description Contains:

Purpose: What does this endpoint do?
Adaptation triggers: When should polling change?
Relationship to siblings: How does it interact with other endpoints?
Stability preferences: Should it react quickly or stay stable?

Examples by Use Case:

Health monitoring:

"Monitors API health. Poll more frequently when status is degraded
or error_rate exceeds 5%. Return to baseline when metrics normalize.
If latency_ms exceeds 2000, investigate more closely."

Data synchronization:

"Checks data sync status. Poll frequently when records_pending is high
(more than 1000). Slow down when caught up (under 100 pending)."

Recovery action:

"Triggers service recovery. Should only run when the health-check
endpoint shows errors. After triggering, wait at least 5 minutes
before allowing another recovery attempt."

Inverse scaling (reduce load under pressure):

"Monitors system load. INVERSE SCALING: when load is HIGH, poll LESS
frequently to reduce overhead. When load is LOW, poll MORE frequently
since the system has capacity."

Stability-focused:

"Monitors volatile metrics. PRIORITIZE STABILITY - don't overreact
to momentary spikes. Only adjust for sustained state changes (5+ minutes).
Response includes smoothed averages - use those, not instant values."

What NOT to Write:

❌ Vague descriptions:

"Monitors things and makes adjustments when needed."

❌ Code-like rules:

"if error_rate > 5% then interval = 30s else interval = 5m"

(AI understands natural language better than pseudo-code)

❌ Just the purpose:

"Health check endpoint."

(Tells AI what it does, but not when to adapt)

No Description vs. Description:

Without description:

AI uses only response data and execution history
Adaptation is generic (tighten on errors, relax on success)
Works, but less precise

With description:

AI knows your specific thresholds and preferences
Adaptation follows your business logic
Much more precise control

Example: Degraded State Detection

For a health monitoring endpoint that should increase frequency during degradation:

{
  "description": "Monitors API health. Poll every 30 seconds when status is degraded or error_rate_pct exceeds 5%. Return to 5-minute baseline when status returns to healthy and error_rate_pct drops below 2%. If latency_ms exceeds 2000, tighten to 1-minute intervals."
}

Why this works well:

Names specific response body fields (status, error_rate_pct, latency_ms)
Provides exact thresholds (5%, 2%, 2000ms) not vague terms
Specifies both tightening AND recovery conditions
References specific interval values (30s, 1min, 5min)

Corresponding response body:

{
  "status": "degraded",
  "error_rate_pct": 8.5,
  "latency_ms": 1200,
  "active_connections": 890,
  "timestamp": "2026-02-03T12:05:00Z"
}

The AI reads status: "degraded" and error_rate_pct: 8.5, matches both against the description thresholds, and calls propose_interval(intervalMs=30000) to tighten polling to 30 seconds.

Best Practices:

Be specific about thresholds: "when queue > 1000" not "when queue is high"
Mention sibling relationships: "when health-check shows errors"
State stability preferences: "don't overreact to momentary spikes"
Use natural language: Write like you're explaining to a colleague
Include inverse behaviors: If high load should mean LESS polling, say so explicitly

Common Configuration Patterns

Pattern 1: Adaptive Monitoring

{
  "baselineIntervalMs": 300000,
  "minIntervalMs": 30000,
  "maxIntervalMs": null,
  "timeoutMs": 10000
}

AI can tighten from 5 minutes to 30 seconds during incidents, but can't go faster (rate limit).

Pattern 2: Scheduled Task with Staleness Limit

{
  "baselineCron": "0 2 * * *",
  "minIntervalMs": null,
  "maxIntervalMs": 7200000,
  "timeoutMs": 60000
}

Runs daily at 2 AM, but if it fails, retries within 2 hours (not 24 hours later).

Pattern 3: Cost-Controlled Analysis

{
  "baselineIntervalMs": 600000,
  "minIntervalMs": 300000,
  "maxIntervalMs": 3600000,
  "timeoutMs": 30000
}

Expensive operation runs every 10 minutes normally, AI can relax to hourly or tighten to 5 minutes.

Debugging Configuration Issues

Problem: Endpoint runs too frequently, ignoring baseline

Check:

Active AI interval hint? (check aiHintExpiresAt)
Min interval set too low?
Baseline misconfigured? (wrong units—milliseconds not seconds)

Problem: Endpoint never tightens during incidents

Check:

Using cron instead of interval? (AI can't override cron)
Min interval too high? (AI proposals clamped)
AI quota exceeded? (no analysis happening)

Problem: Endpoint times out frequently

Check:

Timeout too low for actual performance?
Endpoint performance degraded? (check duration trends)
Network issues? (high latency)

Key Takeaways

Cron for calendar tasks, interval for continuous monitoring
Start without constraints, add min/max only when needed
Timeout = p95 latency × 2 + buffer
Include metrics, timestamps, and coordination signals in responses
Pause stops execution, max interval slows it down
Constraints are hard limits—they override AI
Min/max apply relative to now, not lastRunAt

Configure conservatively. The system is designed to be safe by default. Add constraints when you encounter real problems, not anticipated ones.

Decision 1: Cron vs. Interval​

Use Cron When:​

Use Interval When:​

Decision Tree:​

Common Mistake:​

Decision 2: Setting Min/Max Intervals​

When to Set Min Interval:​

When to Set Max Interval:​

Default Strategy:​

Example Configurations:​

Decision 3: Timeout Configuration​

Rule of Thumb:​

Categories:​

What Happens on Timeout:​

Common Mistake:​

Decision 4: Response Body Design​

Minimum Viable Response:​

Good Response (Monitoring Endpoint):​

Great Response (Coordination Endpoint):​

What to Include:​

What to Exclude:​

Decision 5: Pause vs. Constraints​

Use Pause When:​

Use Max Interval When:​

Comparison:​

Constraint Interaction: How Limits Stack​

Priority Order:​

Example Flow:​

Decision 6: Writing Effective Descriptions​

What a Good Description Contains:​

Examples by Use Case:​

What NOT to Write:​

No Description vs. Description:​

Example: Degraded State Detection​

Best Practices:​

Common Configuration Patterns​

Pattern 1: Adaptive Monitoring​

Pattern 2: Scheduled Task with Staleness Limit​

Pattern 3: Cost-Controlled Analysis​

Debugging Configuration Issues​

Key Takeaways​

See Also​

Decision 1: Cron vs. Interval

Use Cron When:

Use Interval When:

Decision Tree:

Common Mistake:

Decision 2: Setting Min/Max Intervals

When to Set Min Interval:

When to Set Max Interval:

Default Strategy:

Example Configurations:

Decision 3: Timeout Configuration

Rule of Thumb:

Categories:

What Happens on Timeout:

Common Mistake:

Decision 4: Response Body Design

Minimum Viable Response:

Good Response (Monitoring Endpoint):

Great Response (Coordination Endpoint):

What to Include:

What to Exclude:

Decision 5: Pause vs. Constraints

Use Pause When:

Use Max Interval When:

Comparison:

Constraint Interaction: How Limits Stack

Priority Order:

Example Flow:

Decision 6: Writing Effective Descriptions

What a Good Description Contains:

Examples by Use Case:

What NOT to Write:

No Description vs. Description:

Example: Degraded State Detection

Best Practices:

Common Configuration Patterns

Pattern 1: Adaptive Monitoring

Pattern 2: Scheduled Task with Staleness Limit

Pattern 3: Cost-Controlled Analysis

Debugging Configuration Issues

Key Takeaways

See Also