[DOC] - Document and Clarify SWAIG Actions in Documentation

[briankwest]

Document and Clarify SWAIG Actions in Documentation

Description

Several SWAIG actions are already documented, but we need to ensure clarity and consistency across all action descriptions. Some actions require additional details, and a few need refinements to match actual implementation behavior.

Tasks

• Review Existing Documentation

  • Ensure that all actions are documented correctly with proper JSON structures.
  • Clarify descriptions for actions where the behavior is ambiguous.

• Clarify the Following Actions

  • context_switch: Explain when to use full_reset vs. consolidate.
  • playback_bg: Clarify wait parameter behavior.
  • wait_for_user: Define "answer_first" behavior clearly.
  • back_to_back_functions: Specify how "forever" works.
  • functions_on_speaker_timeout: Define use cases.

• Improve Example Usage

  • Add a combined action example with explanations.
  • Provide more real-world function return samples.

• Document Processing Order

  • Specify the execution order of actions when multiple are combined in a response.

• Confirm Permissions and Variable Expansion

  • Ensure all actions that require special permissions are marked accordingly.
  • Clearly describe variable expansion using ${variable_name} syntax.

Deliverables

• Updated documentation with clarified examples and explanations.
• Review and approval from the team before merging.

Priority

📌 High – Required for accurate developer reference.

[briankwest]

https://docs.google.com/document/d/1QGDLEQ6e1uBYJKmuYEMwcl4P3-iS0LmxG5wjCb-mGqc/edit?usp=sharing