layer: universal
description: |
  Cross-cutting use cases that apply to providers across every category. Kept
  intentionally small (3 entries) so it adds signal without flooding every API
  entry with low-value matches. Empirical analysis across 296 Falcon connectors
  showed these are the patterns with both high adoption AND clear, generalizable
  semantics. Weight is the LOWEST of any layer (0.5) — these tag useful patterns
  but should not dominate the priority score.
use_cases:
  - id: entity_search
    name: Entity Search
    description: Search for entities by query, distinct from a plain list endpoint
    mapping_hints:
      action_pattern: ^(search|query|find)_
      path_pattern: (search|query|find)
      method_pattern: ^(GET|POST)$
    example_apis:
      - search_users
      - search_contacts
      - search_deals
      - search_messages

  - id: get_authenticated_user
    name: Get Authenticated User Context
    description: Return the currently authenticated user identity ("who am I")
    mapping_hints:
      action_pattern: ^(get_current_user|get_me|whoami|get_authenticated_user|get_my_(profile|account|user)|get_self)$
      path_pattern: ^(me|users/me|account|current_user|user/me)$
      method_pattern: ^GET$
    example_apis:
      - get_current_user
      - get_me
      - get_authenticated_user
      - get_my_profile

  - id: tags_management
    name: Tags Management
    description: Create, list, update, or delete tags / labels applied to entities
    mapping_hints:
      action_pattern: ^(list|get|create|update|delete)_tag(s)?$
      path_pattern: ^tags?$
      method_pattern: ^(GET|POST|PUT|PATCH|DELETE)$
    example_apis:
      - list_tags
      - create_tag
      - delete_tag