From 7b11c6bb47037a663e849b475f3a4fa304a26ee6 Mon Sep 17 00:00:00 2001 From: Mitch Smith <37649155+mitchbne@users.noreply.github.com> Date: Tue, 14 Jul 2026 14:20:48 +1000 Subject: [PATCH 1/2] Recommend job-free build metadata lookups --- data/llm_descriptions.yml | 4 +-- pages/apis/mcp_server/tools.md | 14 +++++++++-- .../rest_api/_builds_list_query_strings.md | 7 +++++- .../_pipeline_builds_list_query_strings.md | 4 +-- pages/apis/rest_api/builds.md | 25 ++++++++++++++++--- 5 files changed, 43 insertions(+), 11 deletions(-) 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/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.

From 5953cb04c8074451fb7d8af06bd2dcd9a23f689d Mon Sep 17 00:00:00 2001 From: Mitch Smith <37649155+mitchbne@users.noreply.github.com> Date: Tue, 14 Jul 2026 14:31:55 +1000 Subject: [PATCH 2/2] Document MCP job tools in toolset --- pages/apis/mcp_server/tools/toolsets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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",