sdac-read-feedback

Purpose

Reads aggregated user feedback for a given SDAC agent, including rating statistics, category distribution, and a sample of recent feedback items with response previews. Primarily used by the Prompt Tuner agent to identify patterns before generating a prompt improvement.

Tool type

Deterministic (read-only)

Tool ID

sdac-read-feedback

Inputs

• agent_id (string, required) -- Agent ID to read feedback for
• days_back (number, optional, default: 30) -- How many days of feedback to include (1-90)
• min_count (number, optional, default: 5) -- Minimum feedback count required to proceed with tuning
• unprocessed_only (boolean, optional, default: false) -- If true, only include feedback not yet consumed by prompt tuning

Outputs

• agent_id (string)
• total_count (number) -- Total feedback records in the window
• avg_rating (number) -- Average numeric rating (1-5 scale)
• rating_distribution (object) -- Count per rating value keyed by rating string
• category_breakdown (object) -- Count per category keyed by category name
• recent_feedback (array) -- Up to 20 most recent feedback items
  • rating (number | null)
  • category (string | null)
  • comment (string | null)
  • feedback_scope (response | conversation)
  • turn_content_preview (string)
  • created_at (string) -- ISO 8601
• sufficient_data (boolean) -- Whether total_count meets the min_count threshold

Example output

{
  "agent_id": "sdac-coordinator-release",
  "total_count": 12,
  "avg_rating": 4.25,
  "rating_distribution": {
    "3": 3,
    "4": 2,
    "5": 7
  },
  "category_breakdown": {
    "accuracy": 6,
    "completeness": 4,
    "tone": 2
  },
  "recent_feedback": [
    {
      "rating": 5,
      "category": "accuracy",
      "comment": "Fringe answer matched reviewer expectations.",
      "feedback_scope": "response",
      "turn_content_preview": "The fringe increase appears proportional...",
      "created_at": "2026-05-08T13:00:00.000Z"
    }
  ],
  "sufficient_data": true
}

Functional details

• Fetches stats and recent items in parallel using getFeedbackStats and getFeedbackForAgent.
• sufficient_data: false signals that the prompt tuner should wait for more feedback before making changes.
• Up to 20 recent items are returned regardless of days_back.

Usage notes

• Check sufficient_data before using results for prompt tuning decisions.
• Use unprocessed_only: true to retrieve only feedback that has not yet been factored into a prompt update.

Implementation details

• Reads from SDAC.fact_UserFeedback via helpers in packages/domain-sdac/src/tools/feedback/.

Code Location: packages/domain-sdac/src/tools/read-feedback.tool.ts