Skip to main content

​
Overview

Updates an existing team’s name, description, or default role for new members.
This is a write tool that modifies resources in your PagerDuty account. It requires the --enable-write-tools flag to be enabled.

​
Parameters

​
team_id
string
required
The ID of the team to update.
​
name
string
required
The updated name for the team.
​
description
string
Updated description for the team. Set to null or empty string to remove the description.
​
default_role
string
Updated default role for new team members:
  • manager - New members get manager permissions by default
  • none - No default role (must be specified when adding members)

​
Response

Returns the updated team object with all modified fields.

​
Example Usage

​
Update team name

Rename team P4B2Z3G to "Platform Engineering"

​
Update description

Update the Backend Services team description to "Owns all backend APIs and services"

​
Change default role

Change the default role for the Support team to "none"

​
Update multiple fields

Update team P4B2Z3G: rename to "DevOps" and change description to "Infrastructure and deployment"

​
Impact of Team Updates

​
Name Changes

Updating a team’s name affects:
  • How the team appears in the PagerDuty UI
  • Team references in services, schedules, and escalation policies (they update automatically)
  • Team search and filtering
Changing a team’s name does not affect its ID. All existing references using the team ID remain valid.

​
Default Role Changes

Changing default_role only affects future member additions:
  • Existing team members keep their current roles
  • Future add_team_member calls will use the new default role if no role is specified

​
Description Changes

Descriptions are for documentation purposes and don’t affect team functionality.

​
Common Use Cases

  • Team renaming - Update names when teams reorganize or change focus
  • Documentation updates - Keep team descriptions current
  • Permission model changes - Adjust default roles as team structure evolves
  • Standardization - Enforce naming conventions across teams
  • Clarification - Add or improve descriptions for better understanding

​
Important Notes

Team updates require all fields. Unlike some other update operations, you must provide the complete team configuration including unchanged fields.

​
Best Practice Workflow

  1. Get current configuration - Use get_team to retrieve existing team details
  2. Modify as needed - Make your changes to the team data
  3. Update the team - Call update_team with the modified configuration
  4. Verify changes - Use get_team again to confirm the updates

get_team

Get current team configuration

list_teams

View all teams

delete_team

Delete a team (write mode)

manage_members

Manage team membership

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us