server: generated MCP inputSchema for the 13 media-buy seller tools is 13.7 MB / 3.45M tokens on 8.0.0b15 (5.1 MB / 1.27M on 7.0.2); update_media_buy alone exceeds a 1M-token context window

[chinmoyacharjee]

Summary

The inputSchema documents that adcp.server.mcp_tools._generate_pydantic_schemas()
produces for tools/list are too large for a buyer agent to load into a model.
Measured with tiktoken (o200k_base):

adcp	13 media-buy tools*	4 booking tools**	update_media_buy alone	Max depth
8.0.0b15 (latest beta, spec 3.2.0-rc.3)	13.69 MB / 3,450,166 tok	13.09 MB / 3,299,659 tok	6.31 MB / 1,592,130 tok	60
7.0.2 (latest stable, spec 3.1)	5.08 MB / 1,268,487 tok	4.69 MB / 1,174,016 tok	2.29 MB / 573,547 tok	47
6.4.0 (what we run)	8.85 MB / 2,211,285 tok	8.47 MB / 2,117,319 tok	4.18 MB / 1,045,276 tok	49

* The tools a media-buy sales agent registers: get_products, list_creative_formats,
sync_creatives, list_creatives, create_media_buy, update_media_buy, get_media_buy_delivery,
get_media_buys, get_signals, list_accounts, sync_accounts, provide_performance_feedback,
get_adcp_capabilities.
** get_products, create_media_buy, sync_creatives, update_media_buy.

Current frontier models document context windows of about one million tokens
(Anthropic 1M, OpenAI 1.05M, Google "1 million or more"). On every release the
four tools needed for one booking exceed that before the buyer has sent a
brief. On the current beta a single tool, update_media_buy, is 1.59M tokens
on its own, and the thirteen together are 3.4 windows.

A buyer that forwards tools/list to its model, which is what a generic
MCP-to-LLM bridge does, cannot use a publisher running this SDK. It fails on
request size, truncates the tool list, or hand-curates schemas per publisher,
which defeats discovery.

Where the bytes come from

The generator has two forms of the same schema. model_json_schema() gives a
deduplicated document with shared objects under $defs; _inline_refs() then
pastes every referenced definition into every use site. On 8.0.0b15:

Tool	Deduplicated ($defs)	Inlined, as served	Expansion
update_media_buy	414,799 B, 408 defs	6,313,940 B	15.2x
create_media_buy	414,997 B, 414 defs	3,339,785 B	8.0x
sync_creatives	227,241 B, 202 defs	2,878,101 B	12.7x
get_products	231,496 B, 264 defs	555,326 B	2.4x
all 13 tools	1,678,465 B	13,693,312 B	8.2x

In inlined create_media_buy the Agent Url definition appears 371 times,
Provider 360, Feature Id 240, Embedded At 240. The docstring on
_inline_refs gives the reason: some MCP clients do not resolve $ref and
would see an empty parameter list. MCP itself defines inputSchema as JSON
Schema and does not forbid $ref/$defs.

A second generator behaviour adds bytes and depth: every Optional[X] is
emitted as anyOf: [X, {"type": "null"}]. The spec has none of these; inlined
8.0.0b15 output has 26,044 across the thirteen tools (11,967 in
update_media_buy alone). Each is two extra nesting levels, and they sit
inside the shared definitions, so inlining multiplies them too.

The spec's shared objects (creative-asset, brand-reference) are large in
their own right; that is a separate issue in adcontextprotocol/adcp. The
8x is the SDK's.

Per-tool, adcp 8.0.0b15

Tool	Deduplicated (B)	Served (B)	Tokens	Depth	Nullable anyOf
update_media_buy	414,799	6,313,940	1,592,130	60	11,967
create_media_buy	414,997	3,339,785	841,367	60	6,345
sync_creatives	227,241	2,878,101	726,716	53	5,543
get_products	231,496	555,326	139,446	49	999
sync_accounts	97,493	215,678	52,931	43	375
provide_performance_feedback	42,296	93,222	23,390	40	208
get_media_buy_delivery	68,315	79,110	19,916	38	157
list_creatives	47,399	74,226	18,505	45	168
get_signals	57,381	54,849	13,471	38	93
get_media_buys	38,669	36,862	9,170	38	76
list_accounts	35,543	33,738	8,434	38	74
list_creative_formats		15,839	3,998	10	34
get_adcp_capabilities	2,836	2,636	692	7	5
Total	1,678,465	13,693,312	3,450,166		26,044

The four booking tools are 96% of the bytes. For comparison, the hand-written
schemas we serve for them total 13.9 KB (about 3,500 tokens), cover every
required field plus the optionals seen in real traffic, and runtime validation
still runs on the full model.

Secondary effect: depth breaks function-calling APIs

Depth here is JSON nesting (each object or array is one level). The wrappers
push served schemas to 38 to 60 levels. Gemini's function-calling API
(google-genai 2.5.0, gemini-3.6-flash) rejects declarations deeper than
about 20 with a bare 400 INVALID_ARGUMENT that does not name the tool.
Observed on 6.4.0: list_accounts, get_media_buys, get_media_buy_delivery,
get_signals, list_creatives, sync_accounts rejected as generated; the same
list_accounts schema capped at depth 20 accepted, at 30 rejected; removing
only the nullable wrappers brings it from depth 40 to 24. Every tool the API
accepted is depth 13 or less. On 8.0.0b15 provide_performance_feedback has
gone from 4 KB / depth 6 (7.0.2) to 93 KB / depth 40, so tools that were safe
cross the line as the spec grows.

Reproduction (SDK only)

import json, tiktoken
from adcp.server.mcp_tools import _generate_pydantic_schemas

enc = tiktoken.get_encoding("o200k_base")
def depth(n, d=0):
    if isinstance(n, dict): return max([d] + [depth(v, d + 1) for v in n.values()])
    if isinstance(n, list): return max([d] + [depth(v, d + 1) for v in n])
    return d

tools = ["get_products", "list_creative_formats", "sync_creatives", "list_creatives",
         "create_media_buy", "update_media_buy", "get_media_buy_delivery", "get_media_buys",
         "get_signals", "list_accounts", "sync_accounts", "provide_performance_feedback",
         "get_adcp_capabilities"]
schemas = _generate_pydantic_schemas()
tb = tt = 0
for name in tools:
    txt = json.dumps(schemas[name]); b, t = len(txt), len(enc.encode(txt)); tb += b; tt += t
    print(f"{name:30} {b:>10,} B {t:>10,} tok  depth {depth(schemas[name])}")
print(f"{'TOTAL':30} {tb:>10,} B {tt:>10,} tok")

Last line on adcp 8.0.0b15 (Python 3.13.3, pydantic 2.13.5):

TOTAL                          13,693,312 B  3,450,166 tok

and on 7.0.2: 5,075,294 B 1,268,487 tok.

Spec-side note

The spec's shared objects are large too: creative-asset is embedded wherever
a creative may appear, and core/account-ref.json pulls brand_kit_override
into plain list filters (list_accounts resolves to depth 24 on 3.1 via
account -> brand -> brand_kit_override -> logo -> provenance -> disclosure -> jurisdictions -> render_guidance -> positions).
Filed separately in adcontextprotocol/adcp: .

[bokelley]

Triage

Classification: Bug
Bucket(s): handlers (no handlers label in this repo — gap noted)
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: $defs-based schemas are spec-valid MCP; major clients (Claude Desktop, Cursor, mcp-inspector) resolve $ref via ajv today; recommends $defs-by-default with schema_mode="inline" opt-in; considers it non-breaking per spec, minor semver bump.
• code-reviewer: Recommends a 64 KB size guard in _model_to_json_schema after _inline_refs — return None for oversized schemas so the hand-crafted stub stays in place; ~20 lines prod + ~15 test; flags $defs-by-default as breaking for non-spec-compliant bridges.

My take: The size-cap fix is the clearly non-breaking path — the 4 problem tools each produce ~6 MB inlined while their hand-crafted stubs total 13.9 KB and are already proven in production. The $defs-by-default direction is spec-correct long-term but is a behavior change for non-spec-compliant bridges and needs explicit authorization.

Implementation scope:

• src/adcp/server/mcp_tools.py ~line 1657: after _inline_refs returns, add if len(json.dumps(result)) > 65_536: return None; oversized tools fall back to their hand-crafted stubs in ADCP_TOOL_DEFINITIONS.
• tests/test_mcp_schema_drift.py: update test_every_tool_has_pydantic_generated_schema to assert stub validity (type: object, non-empty) for size-capped tools rather than failing on absent Pydantic schema.
• Add regression test: assert max(len(json.dumps(t["inputSchema"])) for t in ADCP_TOOL_DEFINITIONS) < 65_536.
• Non-breaking: size guard is an additional None-return condition on the existing fallback path; _inline_refs and runtime Pydantic validation are untouched.
• Follow-on (separate authorization needed): schema_mode="defs" default + "inline" opt-in on create_mcp_server.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01VueZdEUkY5hZadNH772FSN

---

Generated by Claude Code

[chinmoyacharjee]

Thanks for the quick triage. One thing needs correcting before the size-cap fix goes ahead.

The "hand-crafted stubs totalling 13.9 KB, proven in production" mentioned in the triage are not in the SDK. That figure comes from my issue text and refers to slim schemas we wrote ourselves, inside our own sales agent, and swap into ADCP_TOOL_DEFINITIONS at startup. The SDK does not ship anything like them.

What the SDK does ship, and what a 64 KB cap would fall back to, are the pre-Pydantic placeholder entries in ADCP_TOOL_DEFINITIONS. They are 36 to 229 bytes each. This is the whole one for create_media_buy:

{"type": "object", "properties": {"packages": {"type": "array"}, "proposal_id": {"type": "string"}}}

The real request model has 31 properties and requires idempotency_key, account, brand, start_time and end_time. None of those five appear in the placeholder. get_products is similar: its placeholder does not list buying_mode, which is its only required field.

On 8.0.0b15, 8 of the 13 media-buy tools are over 64 KB inlined, so all 8 would be served as placeholders. A buyer would read them, send the two fields shown, and get rejected by Pydantic validation on every call, with no way to learn the real shape from tools/list. The current 6 MB schema is too big, but it is correct. The placeholder is small and wrong.

A size cap is fine if the fallback is a real compact schema: every required field with its actual type, plus the commonly used optionals, generated from the request model so it cannot drift. We are happy to contribute our slim schemas for the four booking tools as a starting point.

On $defs by default: agree it is the right long-term direction, and good to know Claude Desktop, Cursor and mcp-inspector already resolve $ref. Two notes for that follow-on. $defs cuts size about 8x but not depth, because the anyOf: [X, null] wrappers sit inside the definitions, so the nullable collapse is needed alongside it. And create_media_buy is still about 415 KB in $defs form, so the compact fallback is needed for the heavy tools either way.

[bokelley]

Triage

Classification: Bug
Bucket(s): handlers
Status: ready-to-implement (corrected brief — prior fallback assumption was wrong)

What the experts said:

• code-reviewer: None-return + stub fallback breaks test_required_fields_advertised and test_spot_check_real_fields_reach_clients; safe path is _prune_to_required_fields(schema) — compact but Pydantic-derived — so _PYDANTIC_SCHEMAS stays fully populated; $defs-by-default is separately blocked by test_no_dollar_ref_in_any_advertised_schema.
• ad-tech-protocol-expert: stub fallback confirmed blocker — all five required fields (idempotency_key, account, brand, start_time, end_time) absent from create_media_buy stub (confirmed in v31.pyi and v32.pyi); contributor hand-crafted schemas not acceptable (no drift guard); $defs-by-default viable with schema_mode escape hatch as a separate step.

My take: @chinmoyacharjee's correction is confirmed by both experts and the existing test suite. The placeholder stubs are incomplete; the prior fallback would break every buyer call while silently appearing to work.

Corrected implementation scope:

• src/adcp/server/mcp_tools.py ~line 1657: add _prune_to_required_fields(schema) keeping type, required, and only properties entries matching required; in _model_to_json_schema replace the return None path with return _prune_to_required_fields(result) when len(json.dumps(result)) > _SCHEMA_SIZE_LIMIT; choose _SCHEMA_SIZE_LIMIT empirically (measure pruned schemas for the 8 heavy tools; 256 KB is a suggested starting point).
• tests/test_mcp_schema_drift.py ~line 229: narrow test_spot_check_real_fields_reach_clients to check only required fields for size-capped tools (optional packages may be absent from a pruned schema).
• Non-breaking: _PYDANTIC_SCHEMAS stays fully populated; no stub is ever served; no public API changes.
• Deferred (separate authorization): schema_mode: Literal["defs", "inline"] = "defs" on create_mcp_server() + nullable anyOf collapse — requires relaxing test_no_dollar_ref_in_any_advertised_schema and an explicit client-compat decision; $defs still leaves heavy tools at ~415 KB so the pruner is needed regardless.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01BnjaSEbTs7Yzck5naDHe3n

---

Generated by Claude Code