feat(tool/conversational-analytics-list-accessible-data-agents): return all data agents and support manual paging (#4066)

## Description

list_data_agents issued a single dataAgents:listAccessible request and
returned the raw response, so projects with more agents than one page
silently received a truncated list plus a nextPageToken the caller had
no parameter to act on.

- Add optional page_size and page_token parameters; when either is set
the tool returns that single page unchanged.
- When both are omitted, drain every page and return the merged list,
bounded by 1000 agents / 100 pages / 5 minutes. A nextPageToken is
returned only when a bound stopped the drain early.
- Preserve extra top-level fields (e.g. unreachable) by concatenating
their JSON arrays across pages, and stop when the API repeats a page
token.
- Propagate ctx into every request and surface a paging hint on drain
timeout.
- Update the prebuilt config description and tool docs.

## PR Checklist

> Thank you for opening a Pull Request! Before submitting your PR, there
are a
> few things you can do to make sure it goes smoothly:

- [ ] Make sure you reviewed

[CONTRIBUTING.md](https://github.com/googleapis/mcp-toolbox/blob/main/CONTRIBUTING.md)
- [ ] Make sure to open an issue as a

[bug/issue](https://github.com/googleapis/mcp-toolbox/issues/new/choose)
  before writing your code! That way we can discuss the change, evaluate
  designs, and agree on the general idea
- [ ] Ensure you have manually reviewed the entire diff before
requesting a
  review
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)
- [ ] Make sure to add `!` if this involve a breaking change

🛠️ Fixes #

Author: Genesis929

docs/en/integrations/cloudgda/tools/conversational-analytics-list-accessible-data-agents.md

@@ -13,11 +13,19 @@ aliases:
 A `conversational-analytics-list-accessible-data-agents` tool allows you to list
 data agents that are accessible.
 
+The Conversational Analytics API returns accessible data agents one page at a
+time. By default this tool hides that: it follows every page itself and returns
+all accessible data agents in a single response. Set `page_size` or `page_token`
+to take over pagination and receive one page at a time instead.
+
 It's compatible with the following sources:
 
 - cloud-gemini-data-analytics
 
-`conversational-analytics-list-accessible-data-agents` does not accept any parameters.
+`conversational-analytics-list-accessible-data-agents` accepts the following parameters:
+
+- **`page_size`** (optional): The maximum number of data agents to return in this call. Must be a positive integer. Only set this to page through the results manually; when both `page_size` and `page_token` are omitted, every page is fetched automatically.
+- **`page_token`** (optional): A `nextPageToken` returned by a previous call, used to fetch the next page. Only set this to page through the results manually.
 
 ## Example
 
@@ -31,6 +39,34 @@ description: |
   Use this tool to list available data agents.
 ```
 
+## Output Format
+
+```json
+{
+  "dataAgents": [
+    {
+      "name": "projects/my-project/locations/global/dataAgents/my-agent",
+      "displayName": "My Agent",
+      "createTime": "2026-01-01T00:00:00.000000Z",
+      "updateTime": "2026-01-01T00:00:00.000000Z"
+    }
+  ]
+}
+```
+
+`nextPageToken` is only included when more data agents remain:
+
+- **Without pagination parameters**, the response has no `nextPageToken`,
+  because every page was already fetched. If the automatic fetch reaches its
+  safety limit (100 pages or around 1000 data agents), it returns everything
+  collected so far along with the `nextPageToken` it stopped at, so you can pass
+  that token back as `page_token` to step through the rest. If a page fails or
+  the automatic fetch exceeds its 5 minute budget, the call returns an error
+  rather than a partial list.
+- **With `page_size` or `page_token`**, the response is the API's own page and
+  carries a `nextPageToken` whenever more data agents are available. Pass it
+  back as `page_token` to fetch the next page.
+
 ## Reference
 
 | **field**   | **type** | **required** | **description**                                    |

internal/prebuiltconfigs/tools/conversational-analytics-with-data-agent.yaml

@@ -25,7 +25,10 @@ source: conversational-analytics-source
 location: ${CLOUD_GDA_LOCATION:global}
 description: |
   List all available Data Agents that can be used for
-  conversational analytics in the current project.
+  conversational analytics in the current project. Every page is fetched
+  automatically, so a single call returns all of them. Only if the response
+  contains a `nextPageToken` are there more: pass that value back as
+  `page_token` to step through the remaining pages one page at a time.
 ---
 kind: tool
 name: get_data_agent_info

internal/tools/conversationalanalytics/conversationalanalyticslistaccessibledataagents/conversationalanalyticslistaccessibledataagents.go

@@ -17,9 +17,12 @@ package conversationalanalyticslistaccessibledataagents
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
+	"strconv"
 	"time"
 
 	yaml "github.com/goccy/go-yaml"
@@ -34,6 +37,14 @@ import (
 
 const resourceType string = "conversational-analytics-list-accessible-data-agents"
 
+const (
+	minPageSize       = 1
+	maxAutoDataAgents = 1000
+	maxAutoPages      = 100
+	// maxAutoDuration bounds the total time an automatic drain may spend.
+	maxAutoDuration = 5 * time.Minute
+)
+
 func init() {
 	if !tools.Register(resourceType, newConfig) {
 		panic(fmt.Sprintf("tool type %q already registered", resourceType))
@@ -80,7 +91,20 @@ func (cfg Config) Initialize(context.Context) (tools.Tool, error) {
 		cfg.Location = "global"
 	}
 
-	params := parameters.Parameters{}
+	minPageSizeValue := minPageSize
+	params := parameters.Parameters{
+		parameters.NewIntParameter(
+			"page_size",
+			"Optional. The maximum number of data agents to return in this call. Must be a positive integer. Only set this to page through the results manually: when both `page_size` and `page_token` are omitted, every page is fetched automatically and all accessible data agents are returned.",
+			parameters.WithIntRequired(false),
+			parameters.WithIntMinValue(&minPageSizeValue),
+		),
+		parameters.NewStringParameter(
+			"page_token",
+			"Optional. A page token returned as `nextPageToken` by a previous call, used to fetch the next page. Only set this to page through the results manually; omit it to fetch all accessible data agents at once.",
+			parameters.WithStringRequired(false),
+		),
+	}
 
 	// finish tool setup
 	return Tool{
@@ -121,6 +145,12 @@ func (t Tool) Invoke(ctx context.Context, s sources.Source, params parameters.Pa
 	if !ok {
 		return nil, util.NewClientServerError("source used is not compatible with the tool", http.StatusInternalServerError, nil)
 	}
+
+	pageSize, pageToken, tErr := parsePaginationParams(params)
+	if tErr != nil {
+		return nil, tErr
+	}
+
 	var tokenSource oauth2.TokenSource
 	var err error
 	// Get credentials for the API call
@@ -147,38 +177,212 @@ func (t Tool) Invoke(ctx context.Context, s sources.Source, params parameters.Pa
 		}
 	}
 
-	// Construct URL
-	projectID := source.GetProjectID()
-	caURL := fmt.Sprintf("%s/v1/projects/%s/locations/%s/dataAgents:listAccessible", util.GetGDAEndpoint(), projectID, t.Cfg.Location)
+	client, err := util.NewGDAClient(ctx, option.WithTokenSource(tokenSource))
+	if err != nil {
+		return nil, util.NewClientServerError("failed to create GDA client", http.StatusInternalServerError, err)
+	}
+	client.Timeout = 30 * time.Second
+
+	return listAccessibleDataAgents(ctx, client, util.GetGDAEndpoint(), source.GetProjectID(), t.Cfg.Location, pageSize, pageToken)
+}
+
+// parsePaginationParams extracts optional page_size and page_token parameters.
+func parsePaginationParams(params parameters.ParamValues) (*int, string, util.ToolboxError) {
+	paramsMap := params.AsMap()
+
+	var pageSize *int
+	if ps, ok := paramsMap["page_size"]; ok && ps != nil {
+		size, ok := ps.(int)
+		if !ok {
+			return nil, "", util.NewAgentError(fmt.Sprintf("error casting 'page_size' parameter: %v", ps), nil)
+		}
+		if size < minPageSize {
+			return nil, "", util.NewAgentError(fmt.Sprintf("'page_size' must be positive, got %d", size), nil)
+		}
+		pageSize = &size
+	}
+
+	var pageToken string
+	if pt, ok := paramsMap["page_token"]; ok && pt != nil {
+		s, ok := pt.(string)
+		if !ok {
+			return nil, "", util.NewAgentError(fmt.Sprintf("error casting 'page_token' parameter: %v", pt), nil)
+		}
+		pageToken = s
+	}
+	return pageSize, pageToken, nil
+}
+
+// listAccessibleDataAgents returns a single page when pagination parameters are provided, or all pages by default.
+func listAccessibleDataAgents(ctx context.Context, client *http.Client, endpoint, projectID, location string, pageSize *int, pageToken string) (any, util.ToolboxError) {
+	if pageSize != nil || pageToken != "" {
+		body, tErr := listAccessibleDataAgentsPage(ctx, client, endpoint, projectID, location, pageSize, pageToken)
+		if tErr != nil {
+			return nil, tErr
+		}
+		var result any
+		if err := json.Unmarshal(body, &result); err != nil {
+			return nil, util.NewClientServerError("failed to decode response", http.StatusInternalServerError, err)
+		}
+		return result, nil
+	}
+	return listAllAccessibleDataAgents(ctx, client, endpoint, projectID, location, maxAutoDuration)
+}
+
+// parseDataAgentsPage splits a page into its data agents, its page token, and
+// any other top-level fields, which are kept as raw JSON.
+func parseDataAgentsPage(body []byte) ([]json.RawMessage, string, map[string]json.RawMessage, error) {
+	var page map[string]json.RawMessage
+	if err := json.Unmarshal(body, &page); err != nil {
+		return nil, "", nil, err
+	}
+	if page == nil {
+		return nil, "", nil, fmt.Errorf("response is not a JSON object")
+	}
+
+	var dataAgents []json.RawMessage
+	if raw, ok := page["dataAgents"]; ok {
+		if err := json.Unmarshal(raw, &dataAgents); err != nil {
+			return nil, "", nil, fmt.Errorf("invalid 'dataAgents' field: %w", err)
+		}
+	}
+
+	var nextPageToken string
+	if raw, ok := page["nextPageToken"]; ok {
+		if err := json.Unmarshal(raw, &nextPageToken); err != nil {
+			return nil, "", nil, fmt.Errorf("invalid 'nextPageToken' field: %w", err)
+		}
+	}
+
+	delete(page, "dataAgents")
+	delete(page, "nextPageToken")
+	return dataAgents, nextPageToken, page, nil
+}
+
+// mergeExtras folds a page's extra top-level fields into the ones collected so
+// far, concatenating JSON arrays so lists such as `unreachable` keep every page.
+func mergeExtras(extras, pageExtras map[string]json.RawMessage) {
+	for field, value := range pageExtras {
+		extras[field] = concatJSONArrays(extras[field], value)
+	}
+}
 
-	req, err := http.NewRequest("GET", caURL, nil)
+// concatJSONArrays joins two JSON arrays. When the values cannot be merged it
+// keeps whichever side holds real data: a non-array `prev` is overwritten by
+// `next` (last page wins for scalars), while an unmergeable `next` leaves the
+// already aggregated `prev` untouched so earlier pages are never dropped.
+func concatJSONArrays(prev, next json.RawMessage) json.RawMessage {
+	if len(prev) == 0 {
+		return next
+	}
+	if len(next) == 0 {
+		return prev
+	}
+	var prevItems, nextItems []json.RawMessage
+	if json.Unmarshal(prev, &prevItems) != nil || prevItems == nil {
+		return next
+	}
+	if json.Unmarshal(next, &nextItems) != nil || nextItems == nil {
+		// Keep what was aggregated so far instead of discarding earlier pages.
+		return prev
+	}
+	merged, err := json.Marshal(append(prevItems, nextItems...))
 	if err != nil {
-		return nil, util.NewClientServerError("failed to create request", http.StatusInternalServerError, err)
+		return prev
 	}
-	req.Header.Set("X-Goog-API-Client", util.GDAClientID)
+	return merged
+}
 
-	client, err := util.NewGDAClient(ctx, option.WithTokenSource(tokenSource))
+// drainResult assembles a drained response. `nextPageToken` is omitted once the
+// drain reached the end of the list.
+func drainResult(extras map[string]json.RawMessage, dataAgents []json.RawMessage, pageToken string) map[string]any {
+	result := make(map[string]any, len(extras)+2)
+	for field, value := range extras {
+		result[field] = value
+	}
+	result["dataAgents"] = dataAgents
+	if pageToken != "" {
+		result["nextPageToken"] = pageToken
+	}
+	return result
+}
+
+// listAllAccessibleDataAgents fetches pages until completion or safety limits.
+// budget caps the total time spent draining pages; callers pass maxAutoDuration.
+func listAllAccessibleDataAgents(ctx context.Context, client *http.Client, endpoint, projectID, location string, budget time.Duration) (any, util.ToolboxError) {
+	drainCtx, cancel := context.WithTimeout(ctx, budget)
+	defer cancel()
+
+	dataAgents := []json.RawMessage{}
+	pageToken := ""
+	extras := map[string]json.RawMessage{}
+
+	for page := 0; page < maxAutoPages; page++ {
+		body, tErr := listAccessibleDataAgentsPage(drainCtx, client, endpoint, projectID, location, nil, pageToken)
+		if tErr != nil {
+			if ctx.Err() == nil && errors.Is(tErr, context.DeadlineExceeded) {
+				return nil, util.NewAgentError("timed out while fetching accessible data agents; set 'page_size' and 'page_token' to page through them instead", tErr)
+			}
+			return nil, tErr
+		}
+
+		pageAgents, nextPageToken, pageExtras, err := parseDataAgentsPage(body)
+		if err != nil {
+			return nil, util.NewClientServerError("failed to decode response", http.StatusInternalServerError, err)
+		}
+
+		dataAgents = append(dataAgents, pageAgents...)
+		mergeExtras(extras, pageExtras)
+
+		// A repeated token means the API is not advancing; stop rather than loop.
+		if nextPageToken == pageToken {
+			nextPageToken = ""
+		}
+		pageToken = nextPageToken
+
+		if pageToken == "" || len(dataAgents) >= maxAutoDataAgents {
+			break
+		}
+	}
+
+	return drainResult(extras, dataAgents, pageToken), nil
+}
+
+// listAccessibleDataAgentsPage sends a GET request for a single page of data agents.
+func listAccessibleDataAgentsPage(ctx context.Context, client *http.Client, endpoint, projectID, location string, pageSize *int, pageToken string) ([]byte, util.ToolboxError) {
+	caURL := fmt.Sprintf("%s/v1/projects/%s/locations/%s/dataAgents:listAccessible", endpoint, projectID, location)
+
+	query := url.Values{}
+	if pageSize != nil {
+		query.Set("pageSize", strconv.Itoa(*pageSize))
+	}
+	if pageToken != "" {
+		query.Set("pageToken", pageToken)
+	}
+	if len(query) > 0 {
+		caURL += "?" + query.Encode()
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, caURL, nil)
 	if err != nil {
-		return nil, util.NewClientServerError("failed to create GDA client", http.StatusInternalServerError, err)
+		return nil, util.NewClientServerError("failed to create request", http.StatusInternalServerError, err)
 	}
-	client.Timeout = 30 * time.Second
+	req.Header.Set("X-Goog-API-Client", util.GDAClientID)
+
 	resp, err := client.Do(req)
 	if err != nil {
 		return nil, util.NewClientServerError("failed to send request", http.StatusInternalServerError, err)
 	}
 	defer resp.Body.Close()
 
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, util.NewClientServerError("failed to read response", http.StatusInternalServerError, err)
+	}
 	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(resp.Body)
 		return nil, util.NewAgentError(fmt.Sprintf("API returned non-200 status: %d %s", resp.StatusCode, string(body)), nil)
 	}
-
-	var result any
-	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-		return nil, util.NewClientServerError("failed to decode response", http.StatusInternalServerError, err)
-	}
-
-	return result, nil
+	return body, nil
 }
 
 func (t Tool) RequiresClientAuthorization(source sources.Source) (bool, error) {