Skip to main content

sdac-explain-validation-error

Purpose​

Provides human-readable explanations, rule references, and correction steps for validation errors.

Tool type​

Deterministic (rule-based)

Tool ID​

sdac-explain-validation-error

Inputs​

  • rule_id (string)
  • record_id (number, optional)
  • report_id (string, optional)

Outputs​

  • Explanation text
  • Guideline references
  • Suggested corrections

Example output​

{
  "rule_id": "SOURCE_CODE_FEDERAL_CLAIMED",
  "explanation": "Rows funded only with source code 4 are federally funded and cannot be claimed unless the state/local percentage backs the cost out.",
  "guideline_references": [
    "SDAC source code review step 7.b"
  ],
  "suggested_corrections": [
    "Set claimable salary and fringe to 0 or adjust the state/local percentage so federal costs are excluded."
  ]
}

Functional details​

  • Maps rule IDs to predefined explanations and fix steps.
  • Returns examples of correct vs incorrect values.
  • Provides a consistent narrative used across SDAC agents.

Implementation details​

  • Uses a static rule explanation map with guideline references.
  • Returns structured examples and correction steps per rule.
  • Shared by multiple SDAC agents for consistent error narratives.
  • Rule mappings are embedded directly in the tool for deterministic output.

Code Location: packages/domain-sdac/src/tools/explain-validation-error.tool.ts