Skip to main content
Tool Name: add_note_to_incidentCategory: IncidentsMode: Write (requires --enable-write-tools flag)

​
Overview

The add_note_to_incident tool allows you to add notes to an incident to document investigation progress, findings, remediation steps, or any other relevant information. Notes are visible to all responders and stakeholders following the incident.
This tool requires write mode to be enabled. See Write Mode Configuration for details.

​
Parameters

​
incident_id
string
required
The ID of the incident to add a note to.Example: "Q1234567890ABCDE"
​
note
string
required
The note text to be added. Can include markdown formatting.Example: "Identified root cause: Database connection pool exhausted due to long-running queries. Increasing pool size from 10 to 20."

​
Usage Examples

​
Add an investigation update

{
  "incident_id": "Q1234567890ABCDE",
  "note": "Investigation started. Checking application logs and database performance metrics."
}

​
Document root cause

{
  "incident_id": "Q1234567890ABCDE",
  "note": "Root cause identified: Memory leak in caching layer causing OOM errors. Deployed hotfix v2.3.1 to production at 14:35 UTC."
}

​
Add remediation steps

{
  "incident_id": "Q1234567890ABCDE",
  "note": "Remediation steps taken:\n1. Restarted affected services\n2. Cleared cache\n3. Verified traffic is routing correctly\n4. Monitoring for 15 minutes before resolving"
}

​
Add a status update

{
  "incident_id": "Q1234567890ABCDE",
  "note": "Update: Error rate has dropped from 25% to 2%. Continuing to monitor."
}

​
Response Format

Returns an IncidentNote object representing the created note.
​
id
string
The unique ID of the note.
​
content
string
The content of the note that was added.
​
created_at
datetime
The timestamp when the note was created.
​
user
UserReference
The user who created the note.
​
id
string
User ID
​
type
string
Always “user_reference”

​
Common Errors

Write mode not enabled
Write operations are disabled. Enable with --enable-write-tools flag.
Solution: Restart the MCP server with the --enable-write-tools flag.
Incident not found
404 Not Found: Incident not found
Solution: Verify the incident ID is correct and you have access to it.
Empty note
Validation Error: note cannot be empty
Solution: Provide note text content.

​
Best Practices

Effective incident notes should:
  • Be timely - Add notes as you investigate, not just at the end
  • Be specific - Include timestamps, metrics, and concrete observations
  • Be actionable - Document what you tried and what worked/didn’t work
  • Be clear - Write for other responders who may not have full context
  • Include evidence - Link to logs, dashboards, or other resources
  • Track decisions - Document why certain approaches were chosen
Example of a good note:
14:32 UTC - Identified high CPU usage on db-primary-01 (95% avg over 5min).
Checked slow query log: UPDATE users query running for 300s+.
Killed query PID 12345. CPU dropped to 40%.
Next: Investigate why that query is slow.

​
Viewing Notes

To view existing notes on an incident, use the list_incident_notes tool: 
{
  "incident_id": "Q1234567890ABCDE"
}
You can also include notes when retrieving an incident with get_incident: 
{
  "incident_id": "Q1234567890ABCDE",
  "include": ["notes"]
}

list_incident_notes

View all notes on an incident

get_incident

Get incident details

manage_incidents

Update incident status

add_responders

Request additional responders

​
list_incident_notes

Tool Name: list_incident_notesCategory: IncidentsMode: Read-only

​
Overview

The list_incident_notes tool retrieves all notes that have been added to a specific incident.

​
Parameters

​
incident_id
string
required
The ID of the incident to retrieve notes from.Example: "Q1234567890ABCDE"

​
Response Format

Returns a ListResponseModel[IncidentNote] containing all notes.
​
response
list[IncidentNote]
List of notes for the incident.
​
id
string
The unique ID of the note.
​
content
string
The content of the note.
​
created_at
datetime
When the note was created.
​
user
UserReference
The user who created the note.

​
Source Reference

Functions:
  • add_note_to_incident in pagerduty_mcp/tools/incidents.py:223
  • list_incident_notes in pagerduty_mcp/tools/incidents.py:202
Models: IncidentNote in pagerduty_mcp/models/incidents.py

Build docs developers (and LLMs) love

Get started for freeTalk to us