diff --git a/data/llm_descriptions.yml b/data/llm_descriptions.yml index 547bfb18ac6..d4242e7b863 100644 --- a/data/llm_descriptions.yml +++ b/data/llm_descriptions.yml @@ -431,7 +431,7 @@ apis/rest-api/agents: "REST endpoints to list, get, stop, pause, and resume agents." apis/rest-api/annotations: "REST endpoints to list and create Markdown annotations on builds." apis/rest-api/artifacts: "REST endpoints to list and download build artifacts by build or job." - apis/rest-api/builds: "Full Builds REST API reference: the distinction between build number and build ID, the build and job data models, timestamp attributes, and endpoints to list all builds, list builds for an organization or a pipeline, get a build, create a build, cancel a build, rebuild a build, and retry failed jobs for a build, with filtering options." + apis/rest-api/builds: "Full Builds REST API reference: use exclude_jobs=true for build state and metadata requests, including polling, branch, commit, creator, and timestamps; use exclude_pipeline=true when expanded pipeline information is unnecessary; fetch embedded jobs only when job information is needed. Covers build and job data models, timestamps, list and get endpoints, build creation and cancellation, rebuilds, and retries." apis/rest-api/clusters: "REST endpoints to create, list, get, update, and delete clusters." apis/rest-api/clusters/queues: "REST endpoints to create, list, get, update, pause, resume, and delete cluster queues." apis/rest-api/clusters/agent-tokens: "REST endpoints to create, list, get, update, and revoke cluster agent tokens." @@ -472,7 +472,7 @@ apis/graphql/portals/user-invoked-portals: "Allowing org members to execute portal operations under their own identity and permissions." apis/graphql/graphql-resource-limits: "GraphQL query complexity limits, cost calculation, pagination guidance, and rate limiting." apis/mcp-server: "Overview of the Buildkite MCP server (remote and local) for AI tool integration with Buildkite data." - apis/mcp-server/tools: "List of available MCP tools organized by category: pipelines, builds, jobs, agents, test engine, and more." + apis/mcp-server/tools: "List of available MCP tools organized by category. The list_builds and get_build tools return build metadata without jobs or expanded pipeline information; use list_jobs and get_job for job details. Covers pipelines, builds, jobs, agents, Test Engine, and more." apis/mcp-server/tools/toolsets: "Configuring MCP server toolsets to selectively enable categories of tools for AI agents." apis/mcp-server/remote/configuring-ai-tools: "Configuring Amp, Claude, Cursor, VS Code, Windsurf, and other AI tools with the remote MCP server." apis/mcp-server/remote/rate-limits: "Rate limits for REST API requests made through the remote Buildkite MCP server, which are tracked under a separate per-user limit of 50 requests per minute, independent of the organization's REST API rate limit. Covers checking rate limit details through response headers and handling exceeded limits." diff --git a/pages/apis/mcp_server/tools.md b/pages/apis/mcp_server/tools.md index dd28202f35a..2afac5c7579 100644 --- a/pages/apis/mcp_server/tools.md +++ b/pages/apis/mcp_server/tools.md @@ -262,12 +262,12 @@ These MCP tools are used to retrieve details about existing [builds](/docs/apis/ <% [ { "tool": "list_builds", - "description": "Uses the [List all builds](/docs/apis/rest-api/builds#list-all-builds) REST API endpoint to list all builds for a pipeline with their status, commit information, and metadata.", + "description": "Uses the [List builds for a pipeline](/docs/apis/rest-api/builds#list-builds-for-a-pipeline) REST API endpoint to list build summaries with state, commit information, and metadata. The summaries exclude jobs and expanded pipeline information. Use `list_jobs` when you need job information.", "scope": "read_builds" }, { "tool": "get_build", - "description": "Uses the [Get a build](/docs/apis/rest-api/builds#get-a-build) REST API endpoint to retrieve detailed information about a specific build including its jobs, timing, and execution details.", + "description": "Uses the [Get a build](/docs/apis/rest-api/builds#get-a-build) REST API endpoint to retrieve metadata for a specific build without jobs or expanded pipeline information. Use `list_jobs` or `get_job` when you need job information.", "scope": "read_builds" }, { @@ -322,6 +322,16 @@ These MCP tools are used to retrieve details about [jobs](/docs/apis/rest-api/jo <% [ + { + "tool": "list_jobs", + "description": "Uses the [List jobs](/docs/apis/rest-api/jobs#list-jobs) REST API endpoint to list jobs for a build.", + "scope": "read_builds" + }, + { + "tool": "get_job", + "description": "Uses the [Get a job](/docs/apis/rest-api/jobs#get-a-job) REST API endpoint to retrieve information about a specific job in a build.", + "scope": "read_builds" + }, { "tool": "unblock_job", "description": "Uses the [Unblock a job](/docs/apis/rest-api/jobs#unblock-a-job) REST API endpoint to unblock a blocked job in a Buildkite build to allow it to continue execution.", diff --git a/pages/apis/mcp_server/tools/toolsets.md b/pages/apis/mcp_server/tools/toolsets.md index 4dbaaa31d71..53aed75322e 100644 --- a/pages/apis/mcp_server/tools/toolsets.md +++ b/pages/apis/mcp_server/tools/toolsets.md @@ -41,7 +41,7 @@ Also, see [Recommended toolset configurations](#recommended-toolset-configuratio { "toolset": "builds", "description": "[Builds](/docs/apis/mcp-server/tools#available-mcp-tools-builds) operations", - "tools": "list_builds, get_build, get_build_test_engine_runs, create_build, cancel_build, rebuild_build, unblock_job, retry_job, get_job_env" + "tools": "list_builds, get_build, get_build_test_engine_runs, create_build, cancel_build, rebuild_build, list_jobs, get_job, unblock_job, retry_job, get_job_env" }, { "toolset": "logs", diff --git a/pages/apis/rest_api/_builds_list_query_strings.md b/pages/apis/rest_api/_builds_list_query_strings.md index b5f6d8fa0df..250f4c4c4cf 100644 --- a/pages/apis/rest_api/_builds_list_query_strings.md +++ b/pages/apis/rest_api/_builds_list_query_strings.md @@ -27,9 +27,14 @@ exclude_jobs - Excludes the list of jobs from each build's details + Excludes the list of jobs from each build's details. Use this for state, polling, branch, commit, creator, and timestamp requests. Fetch embedded jobs only when you need job information.

Example: ?exclude_jobs=true

+ + exclude_pipeline + Excludes expanded pipeline information from each build's details. Use this when you do not need pipeline information. +

Example: ?exclude_pipeline=true

+ finished_from Filters the results by builds finished on or after the given time (in ISO 8601 format) diff --git a/pages/apis/rest_api/_pipeline_builds_list_query_strings.md b/pages/apis/rest_api/_pipeline_builds_list_query_strings.md index 974de91d468..c604aa5e33e 100644 --- a/pages/apis/rest_api/_pipeline_builds_list_query_strings.md +++ b/pages/apis/rest_api/_pipeline_builds_list_query_strings.md @@ -27,12 +27,12 @@ exclude_jobs - Exclude the list of jobs from each build's details. + Excludes the list of jobs from each build's details. Use this for state, polling, branch, commit, creator, and timestamp requests. Fetch embedded jobs only when you need job information.

Example: ?exclude_jobs=true

exclude_pipeline - Exclude the pipeline details from each build's details. + Excludes expanded pipeline information from each build's details. Use this when you do not need pipeline information.

Example: ?exclude_pipeline=true

diff --git a/pages/apis/rest_api/builds.md b/pages/apis/rest_api/builds.md index 3001257be59..3cc507a1aaf 100644 --- a/pages/apis/rest_api/builds.md +++ b/pages/apis/rest_api/builds.md @@ -348,9 +348,11 @@ Returns a [paginated list](<%= paginated_resource_docs_url %>) of all builds acr If using token-based authentication the list of builds will be for the authorized organizations only. Builds are listed in the order they were created (newest first). +Use `exclude_jobs=true` when retrieving build state or metadata, including branch, commit, creator, and timestamp information. Fetch embedded jobs only when you need job information. You can also use `exclude_pipeline=true` when you do not need expanded pipeline information. + ```bash curl -H "Authorization: Bearer $TOKEN" \ - -X GET "https://api.buildkite.com/v2/builds" + -X GET "https://api.buildkite.com/v2/builds?exclude_jobs=true" ``` Optional [query string parameters](/docs/api#query-string-parameters): @@ -377,9 +379,11 @@ Error responses: Returns a [paginated list](<%= paginated_resource_docs_url %>) of an organization's builds across all of an organization's pipelines. Builds are listed in the order they were created (newest first). +Use `exclude_jobs=true` when retrieving build state or metadata, including branch, commit, creator, and timestamp information. Fetch embedded jobs only when you need job information. You can also use `exclude_pipeline=true` when you do not need expanded pipeline information. + ```bash curl -H "Authorization: Bearer $TOKEN" \ - -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/builds" + -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/builds?exclude_jobs=true" ``` Optional [query string parameters](/docs/api#query-string-parameters): @@ -406,11 +410,15 @@ Error responses: Returns a [paginated list](<%= paginated_resource_docs_url %>) of a pipeline's builds. Builds are listed in the order they were created (newest first). +Use `exclude_jobs=true` when retrieving build state or metadata, including branch, commit, creator, and timestamp information. Fetch embedded jobs only when you need job information. You can also use `exclude_pipeline=true` when you do not need expanded pipeline information. + ```bash curl -H "Authorization: Bearer $TOKEN" \ - -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds" + -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds?exclude_jobs=true" ``` +The following response shows the embedded jobs returned when you omit `exclude_jobs=true`. + ```json [ { @@ -564,13 +572,17 @@ Error responses: ## Get a build +Use `exclude_jobs=true` when retrieving build state or metadata, including branch, commit, creator, and timestamp information. Fetch embedded jobs only when you need job information. You can also use `exclude_pipeline=true` when you do not need expanded pipeline information. + ```bash curl -H "Authorization: Bearer $TOKEN" \ - -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{number}" + -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{number}?exclude_jobs=true" ``` <%= render_markdown partial: 'apis/rest_api/build_number_vs_build_id' %> +The following response shows the embedded jobs returned when you omit `exclude_jobs=true`. + ```json { "id": "f62a1b4d-10f9-4790-bc1c-e2c3a0c80983", @@ -746,6 +758,11 @@ Optional [query string parameters](/docs/api#query-string-parameters): Exclude the list of jobs from the build's details.

Example: ?exclude_jobs=true

+ + exclude_pipeline + Exclude the expanded pipeline information from the build's details.

+ Example: ?exclude_pipeline=true

+ include_retried_jobs Include all retried job executions in each build's jobs list. Without this parameter, you'll see only the most recently run job for each step.