Repository navigation
Description
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: .
Activity
bokelley commentedon Sep 23, 2026
Triage
Classification: Bug
Bucket(s): handlers (no
handlerslabel in this repo — gap noted)Status: ready-to-implement
What the experts said:
$defs-based schemas are spec-valid MCP; major clients (Claude Desktop, Cursor, mcp-inspector) resolve$refvia ajv today; recommends$defs-by-default withschema_mode="inline"opt-in; considers it non-breaking per spec, minor semver bump._model_to_json_schemaafter_inline_refs— returnNonefor 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_refsreturns, addif len(json.dumps(result)) > 65_536: return None; oversized tools fall back to their hand-crafted stubs inADCP_TOOL_DEFINITIONS.tests/test_mcp_schema_drift.py: updatetest_every_tool_has_pydantic_generated_schemato assert stub validity (type: object, non-empty) for size-capped tools rather than failing on absent Pydantic schema.assert max(len(json.dumps(t["inputSchema"])) for t in ADCP_TOOL_DEFINITIONS) < 65_536.None-return condition on the existing fallback path;_inline_refsand runtime Pydantic validation are untouched.schema_mode="defs"default +"inline"opt-in oncreate_mcp_server.Triaged by Claude Code. Session: https://claude.ai/code/session_01VueZdEUkY5hZadNH772FSN
Generated by Claude Code
chinmoyacharjee commentedon Sep 23, 2026
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_DEFINITIONSat 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 forcreate_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_timeandend_time. None of those five appear in the placeholder.get_productsis similar: its placeholder does not listbuying_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
$defsby 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.$defscuts size about 8x but not depth, because theanyOf: [X, null]wrappers sit inside the definitions, so the nullable collapse is needed alongside it. Andcreate_media_buyis still about 415 KB in$defsform, so the compact fallback is needed for the heavy tools either way.bokelley commentedon Sep 23, 2026
Triage
Classification: Bug
Bucket(s): handlers
Status: ready-to-implement (corrected brief — prior fallback assumption was wrong)
What the experts said:
None-return + stub fallback breakstest_required_fields_advertisedandtest_spot_check_real_fields_reach_clients; safe path is_prune_to_required_fields(schema)— compact but Pydantic-derived — so_PYDANTIC_SCHEMASstays fully populated;$defs-by-default is separately blocked bytest_no_dollar_ref_in_any_advertised_schema.idempotency_key,account,brand,start_time,end_time) absent fromcreate_media_buystub (confirmed inv31.pyiandv32.pyi); contributor hand-crafted schemas not acceptable (no drift guard);$defs-by-default viable withschema_modeescape 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)keepingtype,required, and onlypropertiesentries matchingrequired; in_model_to_json_schemareplace thereturn Nonepath withreturn _prune_to_required_fields(result)whenlen(json.dumps(result)) > _SCHEMA_SIZE_LIMIT; choose_SCHEMA_SIZE_LIMITempirically (measure pruned schemas for the 8 heavy tools; 256 KB is a suggested starting point).tests/test_mcp_schema_drift.py~line 229: narrowtest_spot_check_real_fields_reach_clientsto check onlyrequiredfields for size-capped tools (optionalpackagesmay be absent from a pruned schema)._PYDANTIC_SCHEMASstays fully populated; no stub is ever served; no public API changes.schema_mode: Literal["defs", "inline"] = "defs"oncreate_mcp_server()+ nullableanyOfcollapse — requires relaxingtest_no_dollar_ref_in_any_advertised_schemaand an explicit client-compat decision;$defsstill 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