PagerDuty MCP Server

get_oncalls

Lists current on-call entries, or every entry within a date range, for schedules, escalation policies, and users. Use it to see who is on call now or across a span of time.

Instructions

List on-call entries for schedules, policies, or time ranges.

Behavior varies by time parameters:

Without since/until: Returns current on-calls Example: get_oncalls(current_user_context=False, schedule_ids=["PSCHED123"])
With since/until: Returns all on-calls in range Example: get_oncalls(current_user_context=False, schedule_ids=["PSCHED123"], since="2024-03-20T00:00:00Z", until="2024-03-27T00:00:00Z")

Input Schema

Name	Required	Description
`limit`	No	Max results (optional)
`since`	No	Start of query range in ISO8601 format (default: current datetime)
`until`	No	End of query range in ISO8601 format (default: current datetime, max range: 90 days in the future). Cannot be before `since`.
`include`	No	List of fields to include in the response. If specified, only these fields will be returned for each on-call entry
`earliest`	No	Only earliest on-call per policy/level/user combo (optional)
`user_ids`	No	Filter by users (optional, excludes current_user_context)
`schedule_ids`	No	Filter by schedules (optional)
`current_user_context`	No	Use escalation policies the current user is a target of (default: True); errors if the current user is a target of no escalation policy and no schedule_ids are given.
`escalation_policy_ids`	No	Filter by policies (optional, excludes current_user_context)

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv4.0.7Oct 27, 2026

changedInput schema / properties / current_user_context / description

Previous value: -"Use current user's team policies (default: True)"New value: +"Use escalation policies the current user is a target of (default: True); errors if the current user is a target of no escalation policy and no schedule_ids are given."

changedInput schema / properties / escalation_policy_ids / description

Previous value: -"Filter by policies (optional)"New value: +"Filter by policies (optional, excludes current_user_context)"

Changed1 schema field changedv4.0.1May 12, 2026

addedInput schema / properties / include

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "List of fields to include in the response. If specified, only these fields will be returned for each on-call entry"
+}

Changed18 schema fields changedv3.1.4May 8, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
- addedInput schema / properties / current_user_context / description
```
Added value: +"Use current user's team policies (default: True)"
```
- removedInput schema / properties / current_user_context / title
```
Removed value: -"Current User Context"
```
- addedInput schema / properties / earliest / description
```
Added value: +"Only earliest on-call per policy/level/user combo (optional)"
```
- removedInput schema / properties / earliest / title
```
Removed value: -"Earliest"
```
- addedInput schema / properties / escalation_policy_ids / description
```
Added value: +"Filter by policies (optional)"
```
- removedInput schema / properties / escalation_policy_ids / title
```
Removed value: -"Escalation Policy Ids"
```
- addedInput schema / properties / limit / description
```
Added value: +"Max results (optional)"
```
- removedInput schema / properties / limit / title
```
Removed value: -"Limit"
```
- addedInput schema / properties / schedule_ids / description
```
Added value: +"Filter by schedules (optional)"
```
- removedInput schema / properties / schedule_ids / title
```
Removed value: -"Schedule Ids"
```
- addedInput schema / properties / since / description
```
Added value: +"Start of query range in ISO8601 format (default: current datetime)"
```
- removedInput schema / properties / since / title
```
Removed value: -"Since"
```
- addedInput schema / properties / until / description
```
Added value: +"End of query range in ISO8601 format (default: current datetime, max range: 90 days in the future). Cannot be before `since`."
```
- removedInput schema / properties / until / title
```
Removed value: -"Until"
```
- addedInput schema / properties / user_ids / description
```
Added value: +"Filter by users (optional, excludes current_user_context)"
```
- removedInput schema / properties / user_ids / title
```
Removed value: -"User Ids"
```
- changedOutput schema / (root)
```
Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "type": "object"
+}
```
First observedv1.0.0Aug 18, 2025

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the behavioral burden. It discloses the important time-parameter branching and provides examples, but it does not mention permission requirements, rate limits, or other operational constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then uses a compact numbered list to explain the two behavioral modes. The examples are directly tied to the branches and do not add unnecessary prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of a full input schema, an output schema, and 100% parameter description coverage, the description is largely complete. It covers the key behavioral variation by time range, though it leaves filter-specific semantics to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description adds meaning beyond the schema by explaining that omitting since/until changes the result from a range query to current on-calls. The examples also demonstrate relevant parameter combinations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: "List on-call entries" for schedules, policies, or time ranges. It is clear what the tool returns, but it does not explicitly differentiate itself from the sibling list_users_oncall tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear conditional usage: without since/until it returns current on-calls, and with since/until it returns all on-calls in the range. It does not name sibling alternatives or state when not to use this tool, so it stops short of full alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server