Capability Verbs

Modal verbs that express different levels of agent capabilities.

Overview

Capability verbs are modal verbs used in agent definitions to express different levels of capability, obligation, permission, and prohibition.

Keywords

  • can - Ability/capability
  • must - Strong obligation
  • should - Recommendation
  • may - Permission
  • will - Intention/commitment
  • shall - Formal requirement
  • cannot - Prohibition/inability

can - Ability/Capability

Indicates the agent is able to perform an action.

Usage

agent OrderProcessor {
    can fetch order
    can validate items
    can process payment
}
✨ Edit in Studio

With Conditions

agent SmartProcessor {
    can process order when validated
    can send notification if successful
}
✨ Edit in Studio

Use Cases

  • Standard capabilities
  • Optional actions
  • Conditional operations

must - Strong Obligation

Indicates the agent is required to perform an action.

Usage

agent ComplianceAgent {
    must validate input
    must log transaction
    must verify signature
}
✨ Edit in Studio

With Conditions

agent SecurityAgent {
    must authenticate when accessing_secure_data
    must encrypt when storing_sensitive_info
    must audit_log when making_changes
}
✨ Edit in Studio

Use Cases

  • Critical operations
  • Compliance requirements
  • Security checks
  • Mandatory logging

should - Recommendation

Indicates the agent ought to perform an action (best practice).

Usage

agent BestPracticeAgent {
    should validate input
    should cache results
    should retry when failed
}
✨ Edit in Studio

Use Cases

  • Best practices
  • Recommended but not critical actions
  • Optimization suggestions

may - Permission

Indicates the agent is permitted to perform an action.

Usage

agent PermissionedAgent {
    may access premium_features when subscribed
    may export data if authorized
    may modify settings
}
✨ Edit in Studio

Use Cases

  • Permission-based actions
  • Optional features
  • Conditional access

will - Intention/Commitment

Indicates the agent intends to or will perform an action.

Usage

agent PromiseAgent {
    will send confirmation
    will update status
    will notify subscribers
}
✨ Edit in Studio

Use Cases

  • Future commitments
  • Guaranteed actions
  • Promise of execution

shall - Formal Requirement

Indicates a formal requirement (similar to must, more formal).

Usage

agent FormalAgent {
    shall comply with regulations
    shall maintain audit trail
    shall verify credentials
}
✨ Edit in Studio

Use Cases

  • Formal requirements
  • Regulatory compliance
  • Contract obligations

cannot - Prohibition/Inability

Indicates explicit prohibition or inability.

Usage

agent RestrictedAgent {
    cannot delete user_data
    cannot proceed if unauthorized
    cannot modify when locked
}
✨ Edit in Studio

Use Cases

  • Explicit prohibitions
  • Security restrictions
  • Business rule violations

Comparison Table

VerbStrengthMeaningUse Case
canNeutralAble to performStandard capability
mustStrongRequired to performCritical operation
shouldWeakOught to performBest practice
mayPermissivePermitted to performOptional with permission
willCommitmentIntends to performFuture guarantee
shallFormalFormally requiredCompliance
cannotProhibitiveNot able/allowedRestriction

Real-World Examples

Payment Processing

agent PaymentProcessor {
    # Required operations
    must validate card_details
    must encrypt payment_info
    must log transaction
    
    # Standard capabilities
    can process payment when validated
    can retry payment if declined
    
    # Best practices
    should notify customer when complete
    should cache validation results
    
    # Permissions
    may issue refund if authorized
    
    # Commitments
    will send receipt
    will update order status
    
    # Prohibitions
    cannot store raw_card_numbers
    cannot proceed if fraud_detected
}
✨ Edit in Studio

Content Moderation

agent ContentModerator {
    # Required checks
    must scan for prohibited_content
    must flag suspicious_activity
    must log moderation_actions
    
    # Capabilities
    can auto_approve when clearly_safe
    can auto_reject when clearly_violates
    
    # Best practices
    should escalate when uncertain
    should provide feedback to users
    
    # Commitments
    will review flagged_content
    will notify users of decisions
    
    # Formal requirements
    shall comply with content_policy
    shall maintain moderation_records
    
    # Prohibitions
    cannot publish without_review
    cannot delete without_logging
}
✨ Edit in Studio

Data Management

agent DataManager {
    # Critical operations
    must validate data_integrity
    must backup before_modifications
    must verify permissions
    
    # Standard operations
    can read data when authorized
    can write data if validated
    can transform data
    
    # Recommendations
    should cache frequently_accessed_data
    should compress large_datasets
    should clean old_data
    
    # Optional features
    may export to external_systems if configured
    may archive old_records
    
    # Guarantees
    will maintain consistency
    will log all operations
    
    # Restrictions
    cannot delete without_confirmation
    cannot expose sensitive_data
    cannot bypass audit_logging
}
✨ Edit in Studio

Combining Verbs

Agents can use multiple verbs to express complex behavior:

agent ComplexAgent {
    # Phase 1: Validation (required)
    must validate input
    cannot proceed if invalid
    
    # Phase 2: Processing (capability)
    can process data when validated
    should optimize processing
    
    # Phase 3: Persistence (requirement)
    must save results
    must log completion
    
    # Phase 4: Notification (commitment)
    will notify success
    should send summary_email
    
    # Permissions
    may trigger downstream_process if configured
}
✨ Edit in Studio

Best Practices

Choose the Right Verb

  1. Use must for:

    • Security requirements
    • Compliance needs
    • Critical business logic
  2. Use can for:

    • Standard operations
    • Conditional actions
    • Feature capabilities
  3. Use should for:

    • Best practices
    • Optimizations
    • Recommendations
  4. Use cannot for:

    • Security restrictions
    • Business rules
    • Error prevention

Verb Hierarchy

From strongest to weakest obligation:

must / shall (required)
    ↓
will (committed)
    ↓
should (recommended)
    ↓
can (able)
    ↓
may (permitted)
    ↓
cannot (prohibited)

Example Pattern

agent WellDesignedAgent {
    # 1. Required validations
    must validate input
    cannot proceed if invalid
    
    # 2. Core processing
    can process data
    should optimize processing
    
    # 3. Required outputs
    must save results
    will notify completion
    
    # 4. Optional enhancements
    may export results if requested
}
✨ Edit in Studio

Conditional Usage

All verbs can be combined with conditions:

when Conditions

agent ConditionalAgent {
    can process when ready
    must validate when receiving_input
    should cache when frequently_accessed
    cannot modify when locked
}
✨ Edit in Studio

if Conditions

agent LogicalAgent {
    can approve if criteria_met
    must reject if policy_violated
    should warn if threshold_exceeded
    may proceed if authorized
}
✨ Edit in Studio

Integration Examples

With Workflows

workflow OrderFlow {
    state pending -> processing
    state processing -> completed
}

agent OrderAgent {
    must validate when pending
    can process when validated
    will update_status to completed
    cannot cancel when completed
}
✨ Edit in Studio

With Roles

role AdminRole {
    permission system {
        manage
    }
}

agent SystemAdmin: AdminRole {
    can configure system
    must backup before_changes
    should test configuration
    cannot expose credentials
}
✨ Edit in Studio

Summary

Capability verbs provide precise control over agent behavior:

  • Obligations: must, shall - Required actions
  • Capabilities: can - What agent can do
  • Recommendations: should - Best practices
  • Permissions: may - Optional with permission
  • Commitments: will - Guaranteed actions
  • Prohibitions: cannot - Explicit restrictions

Choose verbs carefully to clearly express your intent and requirements.


Related Keywords


Next Steps