diff --git a/buildkite/data_source_team.go b/buildkite/data_source_team.go
index 647faefb..b96b65ba 100644
--- a/buildkite/data_source_team.go
+++ b/buildkite/data_source_team.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/datasource/schema"
@@ -46,10 +47,13 @@ func (t *teamDatasource) Metadata(ctx context.Context, req datasource.MetadataRe
 
 func (t *teamDatasource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "This datasource allows you to get a team from Buildkite.",
+		MarkdownDescription: heredoc.Doc(`
+			Use this data source to retrieve a team by slug or id. You can find out more about clusters in the Buildkite
+			[documentation](https://buildkite.com/docs/pipelines/permissions).
+		`),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				MarkdownDescription: "The ID of the team.",
+				MarkdownDescription: "The ID of the team to find. Use either ID or slug.",
 				Optional:            true,
 				Computed:            true,
 				Validators: []validator.String{
@@ -64,7 +68,7 @@ func (t *teamDatasource) Schema(ctx context.Context, req datasource.SchemaReques
 				Computed:            true,
 			},
 			"slug": schema.StringAttribute{
-				MarkdownDescription: "The slug of the team.",
+				MarkdownDescription: "The slug of the team to find. Use either ID or slug.",
 				Computed:            true,
 				Optional:            true,
 			},
@@ -73,7 +77,7 @@ func (t *teamDatasource) Schema(ctx context.Context, req datasource.SchemaReques
 				Computed:            true,
 			},
 			"privacy": schema.StringAttribute{
-				MarkdownDescription: "The privacy of the team.",
+				MarkdownDescription: "The privacy setting of the team.",
 				Computed:            true,
 			},
 			"description": schema.StringAttribute{
diff --git a/docs/data-sources/team.md b/docs/data-sources/team.md
index 34f2d0d0..6774948c 100644
--- a/docs/data-sources/team.md
+++ b/docs/data-sources/team.md
@@ -1,34 +1,39 @@
-# Data Source: team
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "buildkite_team Data Source - terraform-provider-buildkite"
+subcategory: ""
+description: |-
+  Use this data source to retrieve a team by slug or id. You can find out more about clusters in the Buildkite
+  documentation https://buildkite.com/docs/pipelines/permissions.
+---
 
-Use this data source to look up properties of a team. This can be used to
-validate that a team exists before setting the team slug on a pipeline.
+# buildkite_team (Data Source)
 
-Buildkite documentation: https://buildkite.com/docs/pipelines/permissions
+Use this data source to retrieve a team by slug or id. You can find out more about clusters in the Buildkite
+[documentation](https://buildkite.com/docs/pipelines/permissions).
 
 ## Example Usage
 
-```hcl
-data "buildkite_team" "my_team_data" {
-    id = "<team id>"
+```terraform
+data "buildkite_team" "team" {
+  id = "Everyone"
 }
 ```
 
-## Argument Reference
+<!-- schema generated by tfplugindocs -->
+## Schema
 
-One of:
-* `id` - The GraphQL ID of the team, available in the Settings page for the team.
-* `slug` - The slug of the team. Available in the URL of the team on buildkite.com; in the format
-  "<organizaton/team-name>"
+### Optional
 
-The `team` data-source supports **either** the use of `id` or `slug` for lookup of a team.
+- `id` (String) The ID of the team to find. Use either ID or slug.
+- `slug` (String) The slug of the team to find. Use either ID or slug.
 
-## Attribute Reference
+### Read-Only
 
-* `id` - The GraphQL ID of the team
-* `uuid` - The UUID of the team
-* `name` - The name of the team
-* `privacy` - Whether the team is visible to org members outside this team
-* `description` - A description of the team
-* `default_team` - Whether new org members will be automatically added to this team
-* `default_member_role` - Default role to assign to a team member
-* `members_can_create_pipelines` - Whether team members can create new pipelines and add them to the team
+- `default_member_role` (String) The default member role of the team.
+- `default_team` (Boolean) Whether the team is the default team.
+- `description` (String) The description of the team.
+- `members_can_create_pipelines` (Boolean) Whether members can create pipelines.
+- `name` (String) The name of the team.
+- `privacy` (String) The privacy setting of the team.
+- `uuid` (String) The UUID of the team.
diff --git a/examples/data-sources/buildkite_team/data-source.tf b/examples/data-sources/buildkite_team/data-source.tf
new file mode 100644
index 00000000..3428e149
--- /dev/null
+++ b/examples/data-sources/buildkite_team/data-source.tf
@@ -0,0 +1,3 @@
+data "buildkite_team" "team" {
+  id = "Everyone"
+}