Provides tools for managing PagerDuty incidents, including listing, acknowledging, resolving incidents, adding notes, viewing alerts and timelines, and checking on-call schedules.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PagerDuty MCP Server Who is on-call right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol server for PagerDuty incident management
Integrate PagerDuty with AI assistants (Claude Desktop, Claude Code) for intelligent incident management and on-call support.
list_incidents - List incidents with filters (status, urgency, team)
get_incident - Get detailed incident information
get_my_incidents - Get incidents assigned to you
acknowledge_incident - Mark incident as acknowledged
resolve_incident - Resolve incident with notes
add_incident_note - Add investigation notes
get_incident_alerts - Get all alerts for an incident
get_incident_timeline - View incident activity history
get_oncall - Check current on-call schedules
List, query, and analyze incidents
View alerts and timelines
Check on-call schedules
Acknowledge/resolve incidents (requires confirmation)
Add investigation notes
Secure: Uses From-email header for audit trail
Related MCP server: Opsgenie MCP Server
Python 3.10+
PagerDuty account with API access
Claude Desktop or Claude Code
Login to PagerDuty: https://your-company.pagerduty.com
User Icon ā My Profile
User Settings ā API Access
Click "Create API User Token"
Description: MCP-Integration
Copy token (starts with u+ or y1_)
cd pagerduty-mcp-server
# Using uv (recommended)
uv sync
# Or using pip
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -e .# Linux/macOS
export PAGERDUTY_API_TOKEN="u+your-token-here"
# Or add to ~/.bashrc
echo 'export PAGERDUTY_API_TOKEN="u+your-token-here"' >> ~/.bashrc
source ~/.bashrc# Run server (stdio mode)
uv run python main.py
# Or with pip
python main.pyConfig file: ~/.config/mcp/mcpServers.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
{
"mcpServers": {
"pagerduty": {
"command": "uv",
"args": [
"--directory",
"/path/to/pagerduty-mcp-server",
"run",
"python",
"main.py"
],
"env": {
"PAGERDUTY_API_TOKEN": "${PAGERDUTY_API_TOKEN}"
}
}
}
}Config file: ~/.config/Code/User/mcp.json
{
"mcpServers": {
"pagerduty": {
"command": "uv",
"args": [
"--directory",
"/path/to/pagerduty-mcp-server",
"run",
"python",
"main.py"
],
"env": {
"PAGERDUTY_API_TOKEN": "${PAGERDUTY_API_TOKEN}"
}
}
}
}Restart Claude Desktop/Code after config changes.
"List all triggered PagerDuty incidents"Claude will use: list_incidents(status="triggered")
"Show me my assigned PagerDuty incidents"Claude will use: get_my_incidents()
"Get details for PagerDuty incident Q26N8MQQHA6R0P"Claude will use: get_incident(incident_id="Q26N8MQQHA6R0P")
"Show all alerts for this incident"Claude will use: get_incident_alerts(incident_id="...")
"Acknowledge incident Q26N8MQQHA6R0P with note: Investigating database slowdown"Claude will use: acknowledge_incident(incident_id="...", note="Investigating database slowdown")
"Who is on-call right now?"Claude will use: get_oncall()
Variable | Required | Description |
| Yes | API User Token from PagerDuty |
| No | Set to |
# List high-urgency triggered incidents
list_incidents(status="triggered", urgency="high", limit=50)
# List incidents for specific team
list_incidents(team_ids=["P5KZERF"], status="acknowledged")pagerduty-mcp-server/
āāā main.py # Entry point
āāā src/
ā āāā server_mcp.py # MCP server with 9 tools
ā āāā helpers/
ā āāā pagerduty_client.py # Async API client
ā āāā utils.py # Formatting utilities
ā āāā constants.py # API constants
āāā pyproject.toml
āāā uv.lock
āāā README.mdImplement in src/server_mcp.py
Add helper functions to src/helpers/ if needed
Test with Claude
triggered - New incident, not acknowledged
acknowledged - Someone is working on it
resolved - Incident fixed
high - High urgency (pages on-call)
low - Low urgency (notification only)
incident_id - PagerDuty incident ID (e.g., Q26N8MQQHA6R0P)
incident_number - Human-readable number (e.g., 2914407)
service - Affected service
assigned_to - List of assigned users
html_url - Link to incident in PagerDuty web UI
ā Store token in environment variable (NOT in code)
ā
Use .gitignore to prevent token commits
ā Token has same permissions as your PagerDuty user
ā Audit trail: All actions logged with your email
Safe to use without confirmation:
list_incidents
get_incident
get_my_incidents
get_incident_alerts
get_incident_timeline
get_oncall
acknowledge_incident - Marks incident as acknowledged
resolve_incident - Closes incident
add_incident_note - Adds investigation notes
# Check environment variable
echo $PAGERDUTY_API_TOKEN
# If empty, set it
export PAGERDUTY_API_TOKEN="u+your-token-here"
source ~/.bashrcToken expired or invalid
Get new token from PagerDuty User Settings
Verify token starts with u+ or y1_
Check filters (status, urgency)
Verify you have access to incidents
Try without filters: list_incidents(limit=10)
Restart Claude Desktop/Code
Check config file path
Verify uv is installed: uv --version
Check logs: tail -f ~/.config/Claude/logs/mcp*.log
"Show me all active PagerDuty incidents from the last 24 hours""Who is currently on-call? Show all open incidents.""Get incident Q26N8MQQHA6R0P details, alerts, and timeline""Show all alerts for incident XYZ and summarize the root cause""List all triggered incidents for my team"Planned feature: Create ServiceNow incidents from PagerDuty alerts
PagerDuty Incident
ā
Claude AI (parses alert)
ā
ServiceNow MCP (create incident)
ā
Link PagerDuty ā ServiceNowSee CONTRIBUTING.md.
Apache License 2.0 - see LICENSE file.
Last updated: 2026-03-11
Acknowledge an incident (mark as working on it).
Args: incident_id: PagerDuty incident ID note: Optional acknowledgement note
Returns: Dict: Updated incident information
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| incident_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the primary effect (mark as working on it) and the return value ('Dict: Updated incident information'), which is useful. However, it does not mention side effects such as notifications, permissions, or reversibility, so the behavioral transparency is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: a one-sentence purpose followed by a compact args list and a return line. Every phrase contributes, and there is no filler. It is front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with two parameters and an output schema, and the description covers purpose, parameters, and return type. It does not elaborate on prerequisites or state transitions, but given the tool's complexity, the information is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description's parameter explanations are essential. It provides basic meaning for both parameters: incident_id is a 'PagerDuty incident ID' and note is an 'Optional acknowledgement note'. While these are helpful, they are not deeply detailed and partially echo the schema titles, so they add modest value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Acknowledge' and the resource 'an incident', with the parenthetical 'mark as working on it' providing the semantic effect. This distinguishes it from sibling tools like resolve_incident, which marks an incident as resolved. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool ('mark as working on it') but does not explicitly contrast it with alternatives like resolve_incident or add_incident_note. It provides no explicit 'when to use' or 'when not to use' guidance, leaving the context implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a note to an incident (for investigation updates, findings, etc.).
Args: incident_id: PagerDuty incident ID note: Note content
Returns: Dict: Created note information
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| incident_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the operation ('Add'), the return type ('Dict: Created note information'), and some usage context. However, it does not disclose potential side effects, permissions, or restrictions (e.g., whether notes can be added to resolved incidents).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line summary followed by clearly labeled Args and Returns sections. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers the core functionality and return value. It lacks edge-case details like permissions or failure conditions, but given the simplicity and presence of an output schema, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides minimal but useful clarification: 'incident_id: PagerDuty incident ID' adds format context, while 'note: Note content' is largely redundant with the schema. The compensation is partial, not fully detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add a note to an incident' with a specific verb and resource. It also provides the purpose ('for investigation updates, findings, etc.'), which distinguishes it from sibling tools like get_incident or resolve_incident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context for when to use the tool ('for investigation updates, findings, etc.'), which is helpful. However, it does not explicitly mention alternatives or exclusions, though the sibling set makes it clear this is the only note-adding tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific incident.
Args: incident_id: PagerDuty incident ID (e.g., 'Q26N8MQQHA6R0P')
Returns: Dict: Full incident details including description, timeline, alerts
| Name | Required | Description | Default |
|---|---|---|---|
| incident_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return type and content ('Dict: Full incident details including description, timeline, alerts'), and the verb 'Get' implies a read-only operation. It does not mention permissions, error handling, or rate limits, but for a simple retrieval tool this is acceptable yet not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear one-line summary, an Args section, and a Returns section. Every sentence provides value, with no redundant or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter retrieval tool, the description is largely complete: it specifies the required input and the type of output. An output schema exists, so the exact return structure is covered there. The main gap is the lack of guidance on how this tool relates to more specific sibling tools (e.g., get_incident_timeline), but this is not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only provides the parameter name and type (string), with no description. The tool description adds essential semantics by explaining 'incident_id: PagerDuty incident ID' and providing a concrete example ('Q26N8MQQHA6R0P'), fully compensating for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get detailed information about a specific incident' with a specific verb and resource. It does not explicitly distinguish from sibling tools like get_incident_alerts or get_incident_timeline, but the mention of 'including description, timeline, alerts' positions it as the comprehensive variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'a specific incident' implies the user needs an incident ID, providing clear context for when to use this tool. However, it does not explicitly state when not to use it or offer alternatives such as list_incidents for general queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all alerts associated with an incident.
Args: incident_id: PagerDuty incident ID
Returns: Dict with keys: - alerts: List of alert details - total: Count of alerts
| Name | Required | Description | Default |
|---|---|---|---|
| incident_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the tool is read-only, what permissions are required, or whether it involves pagination or rate limits. It only describes the return structure, which is helpful but insufficient for a complete behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and organized with clear 'Args' and 'Returns' sections. Every sentence adds value, and there is no redundant or filler content. It is easy to parse and exactly as long as needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, simple list output) and the presence of an output schema (per context signals), the description is adequately complete. It covers the essential input and output structure, though it omits potential error conditions or edge cases like invalid incident IDs or empty alert lists. This is a minor gap for such a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds a minimal clarification that incident_id is a 'PagerDuty incident ID', which is more meaningful than the bare string type in the schema. However, it offers no format, example, or constraints, so it does not fully compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('all alerts associated with an incident'), clearly distinguishing it from siblings like get_incident (gets incident details) or get_incident_timeline (gets timeline). The scope is unambiguous and aligns perfectly with the tool's name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to fetch alerts for a given incident, but it does not explicitly state when to use it versus alternatives like get_incident or list_incidents. There is no mention of complementary tools or exclusions, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get incident activity timeline (all status changes, notes, acknowledgements).
Args: incident_id: PagerDuty incident ID
Returns: Dict with keys: - timeline: List of log entries (chronological) - total: Count of entries
| Name | Required | Description | Default |
|---|---|---|---|
| incident_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the output structure (timeline as a chronological list and a total count) and names the specific event types included. However, it does not explicitly confirm this is a read-only operation, nor does it mention authentication, rate limits, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with structured Args and Returns sections. Every line serves a purpose, the main action is front-loaded, and there is no redundant or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a single-parameter read tool with a described output schema, and the description covers purpose, parameter, and return format. It omits contextual details like pagination, ordering behavior beyond 'chronological', or potential error cases, but the tool is simple enough that these are not critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a type and title for incident_id with 0% description coverage. The description compensates by defining the parameter as 'PagerDuty incident ID', adding essential semantic meaning beyond the bare schema, though it does not elaborate on format or required constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource 'incident activity timeline' and lists the included event types (status changes, notes, acknowledgements). This clearly distinguishes it from sibling tools like get_incident and get_incident_alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage for retrieving the full activity history of an incident, and the scope is evident from the first sentence. However, it does not explicitly state when to use this tool over alternatives or provide exclusions, though no ambiguity exists given the differentiated purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get incidents assigned to the current user.
Returns: Dict with keys: - incidents: List of assigned incidents - total: Count of assigned incidents - user_email: Current user email
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses the return structure and indicates a read-only operation, but does not mention authentication requirements, pagination, or error behavior. This is acceptable for a simple retrieval tool but leaves some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear 'Returns' section that adds value without filler. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters, and the description provides a complete output structure. Given the presence of an output schema, the description suffices for an agent to understand when and what it will return.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema has no properties, so the description does not need to explain parameter behavior. The baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get incidents assigned to the current user,' providing a specific verb and resource scope that distinguishes it from sibling tools like list_incidents (which likely returns all incidents) and get_incident (a single incident).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you need the current user's incidents) but does not provide explicit guidance on when to use alternatives or any exclusion criteria. It could benefit from noting that list_incidents covers all incidents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current on-call schedules.
Returns: Dict with keys: - oncalls: List of current on-call assignments - total: Count of on-call entries
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It adds the return dict structure (oncalls, total) and 'current' scope, but does not disclose whether the operation requires authentication, rate limits, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of a single purpose statement and a clear return breakdown. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool, the description is nearly complete: it explains what and what format is returned. Minor ambiguity about 'current' (e.g., timezone) is not critical, but prevents a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so no parameter explanation is needed. The schema coverage is trivially 100%, and the description correctly omits parameter details. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get current on-call schedules' with a specific verb and resource. It distinguishes from sibling incident-focused tools by explicitly mentioning 'on-call schedules'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The sibling tools are all incident-related, implying this is for on-call, but no explicit when/when-not or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List PagerDuty incidents with optional filters.
Args: status: Filter by status (triggered, acknowledged, resolved) urgency: Filter by urgency (high, low) limit: Maximum number of incidents to return (default: 25, max: 100)
Returns: Dict with keys: - incidents: List of incident summaries - total: Total count - statuses_available: Valid status values - urgencies_available: Valid urgency values
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| status | No | ||
| urgency | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should carry the full behavioral burden. It discloses the return structure, valid filter values, and limit behavior, which is helpful. However, it omits potential error conditions, authentication requirements, and pagination semantics, making it adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with clear Args and Returns sections. The opening sentence front-loads the purpose, and every subsequent line contributes useful parameter or return-shape information without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with three optional parameters, the description covers purpose, parameters, and return structure comprehensively, and an output schema exists to formalize returns. The primary gap is the lack of explicit usage guidance relative to sibling tools, so it is nearly complete but not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining each parameter's purpose, valid values (status: triggered/acknowledged/resolved; urgency: high/low), and limit's default/max. This adds substantial meaning beyond the bare schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence 'List PagerDuty incidents with optional filters' uses a specific verb and resource, clearly conveying the tool's scope. It also distinguishes itself from siblings like get_incident (single incident) and get_my_incidents (personal incidents) through the generic 'List PagerDuty incidents' framing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a general listing use case with optional filters, but it does not explicitly state when to prefer this tool over get_my_incidents or get_incident, nor does it mention any exclusions. The usage context is clear but not fully differentiated from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve an incident with resolution notes.
Args: incident_id: PagerDuty incident ID resolution: Resolution notes explaining how the incident was fixed
Returns: Dict: Updated incident information
| Name | Required | Description | Default |
|---|---|---|---|
| resolution | Yes | ||
| incident_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Resolve' and returns 'Updated incident information', but does not explain side effects, whether the incident must be acknowledged first, permission requirements, or the meaning of 'resolved' in PagerDuty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the main purpose. The Args and Returns sections are mostly redundant with the schema, but there is no fluff or wasted words, so conciseness is decent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations. The output schema exists, so return values are covered indirectly, but the description lacks critical context: when to resolve versus acknowledge, expected incident state, potential side effects, and any prerequisites. The simple one-line purpose is not enough for this action-oriented tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, but the description adds minimal value by defining incident_id as 'PagerDuty incident ID' and resolution as 'notes explaining how the incident was fixed'. This is slightly more informative than the schema's plain type/title fields but still lacks examples or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Resolve' and the resource 'incident', with a mention of resolution notes. However, it does not explicitly differentiate from the sibling tool 'acknowledge_incident', so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when this tool should be used instead of alternatives like 'acknowledge_incident' or 'add_incident_note', nor any prerequisites or preconditions for resolving an incident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0acknowledge_incidentadd_incident_noteget_incidentget_incident_alertsget_incident_timelineget_my_incidentsget_oncalllist_incidentsresolve_incidentScored across 9 tools
Each tool targets a distinct resource and action: specific incident retrieval, user-specific incident listing, general listing, and incident lifecycle actions (acknowledge, resolve, note) are clearly separated. Specialized views like alerts and timeline also have unique purposes with no overlap.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_incident, resolve_incident, list_incidents). The only slight deviation is get_my_incidents and get_oncall, but they still fit the verb_noun convention clearly.
With 9 tools, the server is well-scoped for incident management and on-call visibility. Each tool serves a distinct purpose without redundancy or unnecessary bloat.
The server covers the core incident lifecycle: list, view, acknowledge, resolve, add notes, plus related context (alerts, timeline, on-call). However, it lacks the ability to create or reassign incidents, which are common operational actions, representing a minor gap.
Manage incidents and on-call: list/create/update incidents, who is on call, on-call overrides.
Give AI agents secure access to RevDesk calling, SMS, phone numbers, caller IDs, and usage.
Read incidents, services, teams, on-call schedules; acknowledge, resolve and note incidents.
Give your AI agents the tools to build, manage, and run automation workflows.
