MCP outputSchema is sent to Gemini unbounded, exceeding the token limit #7690

🔴 Required Information

Describe the Bug:

On the Gemini path, McpTool._build_declaration() sends the MCP tool's outputSchema to the model as FunctionDeclaration.response_json_schema, verbatim and with no size limit. This happens whenever JSON_SCHEMA_FOR_FUNC_DECL is enabled, which is the default. McpToolset has no option to opt out per tool or per toolset.

As a result, Google Cloud's own remote MCP servers (https://{logging,monitoring,cloudtrace,clouderrorreporting}.googleapis.com/mcp) cannot be used with ADK as-is. Their proto-derived output schemas push every request over Gemini's 1,048,576-token input limit.

ADK already handles this elsewhere:

• The LiteLLM path (fca7b88, fix(models): forward tool output schema on the LiteLLM path #6815) drops the output schema if it would push the description past 1024 characters.
• The Anthropic path does not send it at all.

Other MCP clients don't send outputSchema to the model by default either (details below).

Steps to Reproduce:

1. Run the code below with uv run --with 'google-adk[mcp]==2.12.0' --with 'mcp<2' python repro.py <vertex-project>. tools/list on these endpoints needs no credentials; only the generate_content calls need a Vertex AI project.
2. Observe the 400 error when all tools are sent, and the per-tool prompt tokens.

Expected Behavior:

Tool declarations should fit within the model's input limit, and there should be a way to control whether output schemas are sent to the model. For example:

• a McpToolset / McpTool option to skip outputSchema (similar to tool_filter), and/or
• a size limit on the Gemini path, like the one the LiteLLM path has.

Observed Behavior:

Sending all 18 declarations (prompt "hello", max_output_tokens=16) fails on gemini-3.5-flash, gemini-3.8-flash and gemini-4-argon alike:

400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'The input token count exceeds the maximum number of tokens allowed 1048576.', 'status': 'INVALID_ARGUMENT'}}

Without response_json_schema, the same 18 declarations use only 14,754 prompt tokens. Prompt tokens per tool on gemini-3.8-flash (largest first):

tool                   ADK default   without response_json_schema
get_dashboard              494,684   151
list_dashboards            494,800   192
list_alert_policies         18,764   375
get_alert_policy            18,380   111
list_timeseries             12,410   8,525
...
get_alert                    1,176   112

The cost is much larger than the JSON size suggests because Gemini counts a schema as if every $ref were inlined. get_dashboard's output schema is 79,181 characters as JSON (61 $defs, 90 $refs), but about 2.06M characters once inlined.

logging              get_bucket               params=   571 response=  7488
logging              get_view                 params=   366 response=  1282
logging              list_buckets             params=  1175 response=  7953
logging              list_log_entries         params=  3734 response= 22385
logging              list_log_names           params=  1648 response=   578
logging              list_views               params=   863 response=  1748
monitoring           get_alert                params=   313 response=  6285
monitoring           get_alert_policy         params=   289 response= 53749
monitoring           get_dashboard            params=   357 response= 79181
monitoring           list_alert_policies      params=  1608 response= 54449
monitoring           list_alerts              params=  1350 response=  6989
monitoring           list_dashboards          params=   702 response= 79649
monitoring           list_metric_descriptors  params=  2041 response= 13805
monitoring           list_timeseries          params= 20411 response= 21798
monitoring           query_range              params=  1909 response=   730
cloudtrace           get_trace                params=   340 response=  3165
cloudtrace           list_traces              params=  2421 response=  3645
clouderrorreporting  list_group_stats         params=  6435 response= 12488
TOTAL params=46533 response=377367

tool                       ADK default  without response_json_schema
get_bucket                       1,669      168
get_view                           369      119
list_buckets                     1,855      280
list_log_entries                 5,457      885
list_log_names                     533      414
list_views                         530      207
get_alert                        1,176      112
get_alert_policy                18,380      111
get_dashboard                  494,684      151
list_alert_policies             18,764      375
list_alerts                      1,513      332
list_dashboards                494,800      192
list_metric_descriptors          3,696      459
list_timeseries                 12,410    8,525
query_range                        470      358
get_trace                          804      137
list_traces                      1,300      565
list_group_stats                 3,595    1,381

N= 1  $ref    json_chars=4206  prompt_tokens=768    | inline  json_chars=4161   prompt_tokens=768
N= 5  $ref    json_chars=4334  prompt_tokens=3760   | inline  json_chars=20669  prompt_tokens=3760
N=20  $ref    json_chars=4824  prompt_tokens=14990  | inline  json_chars=82584  prompt_tokens=14990

ADK_DISABLE_JSON_SCHEMA_FOR_FUNC_DECL=1 is not a practical workaround:

• It is global. Every FunctionTool and MCP tool switches to the legacy _to_gemini_schema path for parameters (see [legacy path] Nested pydantic model tool parameter fails under VERTEX_AI when the function also has a fallback-parsed parameter — only with JSON_SCHEMA_FOR_FUNC_DECL disabled #6984).
• The flag was promoted to stable on main in ea298d4 (not yet released), and graduated flags may be removed.

Environment Details:

• ADK Library Version (pip show google-adk): 2.12.0 (same code path in 2.11.0)
• Desktop OS: macOS
• Python Version (python -V): 3.12

Model Information:

• Are you using LiteLLM: No
• Which model is being used: gemini-3.8-flash (also gemini-3.5-flash, gemini-4-argon)

🟡 Optional Information

Regression:

This started when MCP output schemas began to be propagated to FunctionDeclaration. It was added in c8e5340 for #2828, reverted in 92a7d19, and reintroduced behind JSON_SCHEMA_FOR_FUNC_DECL in 1dd97f5.

Additional Context:

#2828 asked for the output schema so the model could describe a small tool's result. That is reasonable for small schemas, but I think the decision of whether, and how much, of outputSchema to send to the model belongs to ADK as the client:

• The MCP spec defines outputSchema "for validation of structured results".
• It is unlikely to be fixed on the server side or in the ecosystem (details below).

Current workaround: subclass McpTool, or strip response_json_schema in a before_model_callback.

Minimal Reproduction Code:

import asyncio
import sys

from google import genai
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.genai import types

# tools/list on these endpoints does not require credentials
SERVICES = ["logging", "monitoring", "cloudtrace", "clouderrorreporting"]
MODEL = "gemini-3.8-flash"


async def declarations():
    decls = []
    for service in SERVICES:
        toolset = McpToolset(
            connection_params=StreamableHTTPConnectionParams(url=f"https://{service}.googleapis.com/mcp")
        )
        try:
            decls += [tool._get_declaration() for tool in await toolset.get_tools()]
        finally:
            await toolset.close()
    return decls


def prompt_tokens(client, decls):
    try:
        response = client.models.generate_content(
            model=MODEL,
            contents="hello",
            config=types.GenerateContentConfig(
                tools=[types.Tool(function_declarations=decls)], max_output_tokens=16
            ),
        )
        return response.usage_metadata.prompt_token_count
    except Exception as e:
        return f"error: {e}"


async def main():
    client = genai.Client(vertexai=True, project=sys.argv[1], location="global")
    decls = await declarations()
    stripped = [d.model_copy(update={"response_json_schema": None}) for d in decls]
    print("all tools:", prompt_tokens(client, decls))
    print("all tools without response_json_schema:", prompt_tokens(client, stripped))
    for d, s in zip(decls, stripped):
        print(f"{d.name:26} {prompt_tokens(client, [d])!s:>10} {prompt_tokens(client, [s])!s:>8}")


asyncio.run(main())

How often has this issue occurred?:

• Always (100%)