Skip to content

title: Regnify Tool: create_incident_declaration

Regnify Tool: create_incident_declaration

Back to Regnify Product Docs

| Document Type | Regnify Internal | | Status | current | | Last Updated | 2026-05-05 |

Previous Next

Purpose

create_incident_declaration files a new Incident Disclosure declaration (formType = DECLARATION_INCIDENT_DISCLOSURE) for a representative. It calls the NestJS createDeclaration GraphQL mutation with the incident details captured in formData, then enters the declaration into the normal workflow approval chain. No LLM call -- this is a structured write-through to the persistence layer.

Critical distinction: This tool ONLY files a declaration in Regnify. It does NOT automatically notify MAS. Filing with MAS is a separate regulatory obligation with its own deadlines and submission process. Always inform the user of this distinction when they file an incident.

Signature

create_incident_declaration(ctx, rep: RepProfileRef, incident_type: str, narrative: str) -> dict

Parameters

Parameter Type Required Description
rep {"kind": "rep_profile", "id": <int>} Yes Tagged rep-profile reference. id must be the numeric rep_profile_id. Get from get_rep_register if you have a UUID. The tool resolves the linked Keycloak user and rep number internally.
incident_type str Yes Closed-enum incident category. Must be one of five values (see below). Validated server-side with frozenset.__contains__ -- structural enum check, CLAUDE.md section 10-clean.
narrative str Yes Free-text description of the incident. Surfaced verbatim into formData.narrative. Not mutated, not summarized.

Incident Type Enum

gift_received       -- Rep received a gift, entertainment, or hospitality
client_complaint    -- Client filed a formal complaint against the rep
third_party_report  -- Third party (regulator, exchange, etc.) reported misconduct
conflict_of_interest -- Rep has a conflict of interest (personal, financial, relational)
other               -- Any incident not fitting the above categories

The enum is closed -- any other value causes ValueError with a message listing the five valid options.

Narrative Requirements

The narrative string is stored verbatim. For a well-formed incident record, the narrative should include:

  • Who: The representative and any other parties involved.
  • What: The specific incident -- type, nature, scope.
  • When: Date/time or timeframe of the incident.
  • Where: Context (client meeting, branch office, external event, etc.).
  • Product involved: If relevant, which financial product or service.
  • Regulatory implications: Which regulation or MAS rule may be triggered.

The tool itself does NOT validate narrative completeness -- it stores whatever is provided. Guide the user to include these elements when they dictate an incident.

Internal Resolution Flow

  1. Rep profile lookup: Tool resolves rep.normalised_id -> repProfile(id) query -> extracts userId.
  2. User profile lookup: Tool resolves userId -> user(id) query -> extracts username (used as repId) and name (used as repName).
  3. Mutation call: createDeclaration with: 
    {
  "repId": "<username or REP-{id} fallback>",
  "userId": <int>,
  "repName": "<name or null>",
  "repProfileId": <int>,
  "formType": "DECLARATION_INCIDENT_DISCLOSURE",
  "formData": {
    "incidentType": "<incident_type>",
    "narrative": "<narrative>",
    "reportedAt": "<ISO 8601 UTC timestamp>"
  }
}
  4. The reportedAt timestamp is set server-side to datetime.now(UTC).isoformat() at call time -- no need for the user to specify it.

Return Shape (Success)

{
  "declaration_id": <int>,
  "form_type": "DECLARATION_INCIDENT_DISCLOSURE",
  "status": "<string, e.g. 'Draft'>",
  "workflow_instance_id": <int or null>
}
  • declaration_id: The new Declaration row ID. Use this for follow-up queries via get_declaration.
  • form_type: Always "DECLARATION_INCIDENT_DISCLOSURE" for this tool.
  • status: Initial declaration status (typically "Draft"). The declaration enters the normal workflow approval chain from this state.
  • workflow_instance_id: The workflow instance ID if an approval chain was created. null if no workflow was triggered at creation time.

Return Shape (Errors)

The tool wraps exceptions in {"error": str}:

Error Condition error Message Pattern
incident_type not in enum ValueError: "create_incident_declaration: incident_type=... is not in ['client_complaint', 'conflict_of_interest', 'gift_received', 'other', 'third_party_report']"
rep_profile_id not found "create_incident_declaration: rep_profile_id=... not found. Verify the rep profile exists..."
user not found "create_incident_declaration: user_id=... linked to rep_profile_id=... not found."
Mutation returned empty "create_incident_declaration: mutation returned empty payload. The backend may have rejected..."

Dual Function: Query Existing Incidents

While create_incident_declaration is primarily a creation tool, the chatbot can also use it to help users understand existing incident records. To query existing incidents for a rep, use get_declaration with individual declaration IDs, or look at the rep's audit log entries from detect_attestation_anomaly which surfaces recent audit activity.

There is no separate "query incidents" tool -- the incident declarations are regular Declaration rows and are queryable through the standard declaration and workflow tools.

MAS Reporting Deadlines (Knowledge Context)

Filing an incident in Regnify does NOT auto-notify MAS. The user must separately report to MAS within these statutory deadlines:

Regulation Deadline Trigger
FAA-N14 5 business days Criminal misconduct by a representative
FAA-N14 14 business days Suspected contravention of FAA or regulations
SFA 04-N11 14 calendar days Misconduct of CMS representatives

When a user files an incident, remind them of the applicable MAS reporting obligation. The chatbot can retrieve the exact notice text via search_mas_knowledge with queries like "FAA-N14 misconduct reporting deadlines" or "SFA 04-N11 representative misconduct notification timeline".

Important Rules

  1. Only call when the user intends to file: If the user is asking "what counts as an incident?" or "when must we report?", answer from the knowledge base via search_mas_knowledge -- do NOT call this tool.
  2. incident_type must be from the closed enum: Do not invent new categories. If the user's incident doesn't fit the five types, use "other" and capture details in the narrative.
  3. Narrative is stored verbatim: Ensure the user has provided sufficient detail before calling.
  4. Always remind about MAS notification: Filing in Regnify is internal record-keeping. The rep's FI still bears the statutory obligation to notify MAS.

Previous Next

Back to Regnify Product Docs