@@ -30,6 +30,19 @@
 
 ### Bug fixes
 
+* **server:** MCP ``outputSchema`` now honours ``schema_mode`` instead of
+  always inlining every ``$ref``. Inlining expands each shared subtree once
+  per reference, so ``ListCreativesResponse`` was advertised at 4.8 MB where
+  its compact form is 25 KB — and ``examples/seller_agent.py`` served a
+  22 MiB ``tools/list`` for 13 tools, which a buyer applying the new 4 MiB
+  response budget rejects outright. Output schemas are now compact by
+  default, matching input schemas, which have shipped local ``$ref``/``$defs``
+  since they were introduced; the reference seller's discovery payload drops
+  to 1.29 MiB. Adopters serving clients that do not resolve references keep
+  the old shape with ``schema_mode="inline"``. The server also logs its
+  ``tools/list`` size at startup and warns past half the buyer budget, and
+  ``examples/seller_agent.py`` declares ``advertised_tools``. Refs #1505.
+
 * **signing:** The webhook receiver's `WWW-Authenticate` challenge now carries
   `webhook_target_uri_malformed` instead of rewriting it to
   `webhook_signature_invalid`. A JWKS host that fails DNS resolution in
 
@@ -55,25 +55,49 @@ Pass ``advertise_all=True`` to ``serve()`` / ``create_mcp_server()`` /
 storyboards, agents that deliberately signal
 ``not_supported`` on specific tools).
 
-### MCP input-schema migration
+### MCP schema modes
 
 The default MCP ``schema_mode="compact"`` keeps ``tools/list`` responses
-small by using local JSON Schema ``$ref`` entries and ``$defs``. MCP clients
-must resolve those references before inspecting nested input fields. If a
-client does not resolve local JSON Schema references, use the compatibility
-escape hatch when constructing the MCP server:
+small by using local JSON Schema ``$ref`` entries and ``$defs``. It applies
+to **both** ``inputSchema`` and ``outputSchema``. MCP clients must resolve
+those references before inspecting nested fields. If a client does not
+resolve local JSON Schema references, use the compatibility escape hatch when
+constructing the MCP server:
 
 ```python
 from adcp.server import create_mcp_server
 
 mcp = create_mcp_server(MyAgent(), schema_mode="inline")
 ```
 
-``schema_mode="inline"`` restores the historical, reference-free input
-schema at the cost of a substantially larger ``tools/list`` response.
+``schema_mode="inline"`` restores the historical, reference-free schema at
+the cost of a substantially larger ``tools/list`` response — inlining
+expands every shared subtree once per reference, so a response model whose
+compact form is 25 KB can go out at 4.8 MB. Measure before shipping it:
+a buyer applying the AdCP default 4 MiB response budget rejects an oversized
+``tools/list`` outright, and the agent then looks unreachable rather than
+verbose. The SDK logs the payload size at startup and warns past half the
+budget.
+
 ``schema_mode="defs"`` is also available when a client resolves references
 and needs the complete, unpruned Pydantic schema graph.
 
+**Keeping discovery small.** The two levers are the number of tools you
+advertise (declare ``advertised_tools``; avoid ``advertise_all=True`` unless
+you mean it) and the schema mode. Both are visible in the startup line:
+
+```
+mcp server advertising 13 of 13 tools
+mcp server tools/list payload: 1351670 bytes across 13 tools
+```
+
+**Declaring ``advertised_tools`` makes that class a discovery base.** Once
+declared, the framework measures *subclasses* of that class against it, so a
+subclass advertises only what it overrides itself — a subclass of a concrete
+seller that adds nothing advertises nothing. Declare the set on the class your
+adopters subclass, not on a leaf, and subclass ``ADCPHandler`` with your own
+declaration rather than extending someone else's concrete handler.
+
 **Custom handler bases — declare ``advertised_tools``.** The override
 filter works perfectly for direct ``ADCPHandler`` subclasses and the
 specialized bases (``GovernanceHandler``, ``ContentStandardsHandler``,
 
@@ -22,7 +22,7 @@
 from copy import deepcopy
 from datetime import datetime, timedelta, timezone
 from decimal import ROUND_DOWN, Decimal
-from typing import Any
+from typing import Any, ClassVar
 
 from adcp import (
     ActionAvailabilityStatus,
@@ -926,6 +926,35 @@ def _narrow_metrics(metrics: dict[str, Any], requested: list[str] | None) -> dic
 
 
 class DemoSeller(ADCPHandler):
+    #: The tools this seller actually serves. Without it, a handler that
+    #: subclasses ``ADCPHandler`` directly inherits the full 78-tool universe
+    #: and relies on the framework's override detection to narrow it — which
+    #: works, but leaves the declared surface implicit and warns at startup.
+    #: Declaring it registers the class with the tool-discovery registry, so
+    #: ``tools/list`` is a statement of intent rather than a byproduct of
+    #: which methods happen to exist. The framework adds the always-on
+    #: protocol/discovery tools (``get_adcp_capabilities``) on top.
+    #:
+    #: One consequence worth knowing before copying this: declaring it also
+    #: registers ``DemoSeller`` as a tool-discovery base, so a subclass of
+    #: *this* class is measured against it and advertises only what it
+    #: overrides itself. Subclass ``ADCPHandler`` and declare your own set
+    #: rather than subclassing a concrete seller.
+    advertised_tools: ClassVar[set[str]] = {
+        "control_media_buy",
+        "create_media_buy",
+        "get_media_buy_delivery",
+        "get_media_buys",
+        "get_products",
+        "list_creative_formats",
+        "list_creatives",
+        "list_products",
+        "sync_accounts",
+        "sync_creatives",
+        "sync_governance",
+        "update_media_buy",
+    }
+
     legacy_format_converter = staticmethod(_legacy_format_converter)
     canonical_format_legacy_resolver = staticmethod(_canonical_format_legacy_resolver)
 
 
@@ -144,7 +144,7 @@ async def durable(self) -> bool:
             or projection._escalation != getattr(self.store, "escalation", None)
             or not projection._consumer_status_enabled
             or "get_reporting_status"
-            not in {t["name"] for t in get_tools_for_handler(self.handler)}
+            not in {t["name"] for t in get_tools_for_handler(self.handler, _include_schemas=False)}
         ):
             return False
         return all([await self.account_ready(account_id=a) for a in sorted(set(self.account_ids))])
@@ -183,7 +183,7 @@ async def validate_status_claims(
     from adcp.server.mcp_tools import get_tools_for_handler
 
     assert support.handler is not None
-    mounted = {t["name"] for t in get_tools_for_handler(support.handler)}
+    mounted = {t["name"] for t in get_tools_for_handler(support.handler, _include_schemas=False)}
     for field, task in block.items():
         if field.endswith("_task") and isinstance(task, str) and task not in mounted:
             raise ReportingNotificationError("reporting_capability_requires_mounted_task")
@@ -1101,7 +1101,11 @@ def _build_agent_card(
     1.0 clients see the transport they expect on
     ``/.well-known/agent-card.json``.
     """
-    tool_defs = get_tools_for_handler(handler, advertise_all=advertise_all)
+    # Names and descriptions only. An A2A skill carries neither schema, and
+    # this runs per request on the pre-auth ``/.well-known/agent-card.json``
+    # route — building the full Pydantic schema graph there is ~400x the work
+    # for a result immediately discarded.
+    tool_defs = get_tools_for_handler(handler, advertise_all=advertise_all, _include_schemas=False)
     extra_ids = {s.id for s in extra_skills} if extra_skills else set()
 
     skills = [
 
@@ -183,10 +183,29 @@ def _widen_media_buy_output_schema_for_legacy_statuses(
     """
     if tool_name not in {"create_media_buy", "update_media_buy"}:
         return
+    defs = schema.get("$defs")
+    defs = defs if isinstance(defs, dict) else {}
     variants = schema.get("anyOf") or schema.get("oneOf") or []
     for variant in variants:
         if not isinstance(variant, dict):
             continue
+        # Outside ``schema_mode="inline"`` a union arm is a local reference.
+        # Widen a *copy* under a new definition name and repoint this arm at
+        # it: a `$defs` entry may be referenced from more than one site, and
+        # loosening a status constraint somewhere else is not what this is
+        # for. Today each arm's definition has exactly one reference, so the
+        # copy is free — it is the invariant that is worth not depending on.
+        ref = variant.get("$ref")
+        if isinstance(ref, str) and ref.startswith("#/$defs/"):
+            source_name = ref[len("#/$defs/") :]
+            target = defs.get(source_name)
+            if not isinstance(target, dict):
+                continue
+            widened_name = f"{source_name}LegacyStatus"
+            widened = copy.deepcopy(target)
+            defs[widened_name] = widened
+            variant["$ref"] = f"#/$defs/{widened_name}"
+            variant = widened
         required = variant.get("required")
         properties = variant.get("properties")
         if not isinstance(required, list) or not isinstance(properties, dict):
@@ -1762,9 +1781,11 @@ def _prune_to_required_fields(
     nested objects required properties, scalar optionals, and protected
     mutation-discovery fields remain. Protected fields keep their complete
     referenced Pydantic model graph. When optional properties are omitted from
-    an object that otherwise rejects unknown fields, the compact discovery
-    shape is opened with ``additionalProperties: true`` so it remains a
-    permissive description of payloads accepted by the runtime model.
+    an object that otherwise rejects unknown fields, each omitted name is
+    re-admitted with the permissive boolean schema ``true`` rather than the
+    object being opened with ``additionalProperties: true`` — the compact
+    shape stays a permissive description of what the runtime model accepts
+    *and* keeps rejecting what it rejects.
 
     The transform operates only on Pydantic's JSON Schema output; it never
     substitutes hand-written tool shapes.
@@ -1833,8 +1854,28 @@ def _prune_to_required_fields(
             protected_defs=_protected_defs,
         )
 
-    if dropped_optional_properties and result.get("additionalProperties") is False:
-        result["additionalProperties"] = True
+    if dropped_optional_properties:
+        # Re-admit every dropped name with the permissive boolean schema
+        # ``true`` rather than deleting it. Two things follow, both of which
+        # the previous "open the object with additionalProperties: true"
+        # approach lost:
+        #
+        # * The object stays closed if it was closed. Opening it would make
+        #   the compact shape accept keys the model rejects — on an
+        #   outputSchema that is the only check a buyer has against a seller
+        #   smuggling extra fields into a payload it feeds to a model.
+        # * The field inventory survives. A reader still learns that
+        #   ``errors`` and ``ext`` exist on a task envelope; only their
+        #   subtrees are gone, which is the size that made compaction
+        #   necessary.
+        #
+        # The cost is the length of each dropped name, not its subtree.
+        pruned_properties = result.get("properties")
+        if isinstance(pruned_properties, dict) and isinstance(properties, dict):
+            for name in properties:
+                pruned_properties.setdefault(name, True)
+        elif result.get("additionalProperties") is False:
+            result["additionalProperties"] = True
     return result
 
 
@@ -2174,6 +2215,8 @@ def _generate_pydantic_schemas(
 
 def _generate_pydantic_output_schemas(
     tool_names: Iterable[str] | None = None,
+    *,
+    schema_mode: SchemaMode = "compact",
 ) -> dict[str, dict[str, Any]]:
     """Generate JSON schemas from Pydantic response models.
 
@@ -2191,6 +2234,15 @@ def _generate_pydantic_output_schemas(
     Unlike input schemas, root-level ``anyOf`` is allowed — discriminated
     response unions are valid JSON Schema and clients that consume
     ``outputSchema`` already handle them.
+
+    ``schema_mode`` matches the input side, and for the same reason. Inlining
+    every ``$ref`` expands a response model's shared subtrees once per
+    reference: ``ListCreativesResponse`` is 25 KB compact, 418 KB with local
+    ``$defs``, and 4.8 MB inlined. A handful of tools in that last shape is a
+    multi-megabyte ``tools/list`` that a buyer with a response-size budget
+    rejects outright. Compact stays a permissive description — dropping an
+    optional nested property reopens ``additionalProperties`` — so a real
+    response still validates against it.
     """
     try:
         from adcp.types import (
@@ -2384,7 +2436,9 @@ def _generate_pydantic_output_schemas(
     for tool_name, response_type in _tool_to_response.items():
         if selected is not None and tool_name not in selected:
             continue
-        schema = _model_to_json_schema(response_type, allow_root_union=True)
+        schema = _model_to_json_schema(
+            response_type, allow_root_union=True, schema_mode=schema_mode
+        )
         if schema is None:
             logger.debug(
                 "Pydantic output-schema generation failed for %s",
@@ -2630,7 +2684,10 @@ def get_tools_for_handler(
             (default) keeps every root request field, required nested fields,
             scalar optionals, and protected mutation surfaces; ``"defs"``
             keeps the complete schema with local references, and ``"inline"``
-            preserves the historical fully expanded schema.
+            preserves the historical fully expanded schema. Both non-default
+            modes regenerate input *and* output schemas on every call with no
+            memoization — seconds per construction for a 13-tool handler —
+            where ``"compact"`` reads the memoized registry.
             Version-pinned handlers continue to advertise their exact bundled
             wire schemas.
 
@@ -2706,14 +2763,19 @@ def get_tools_for_handler(
         # mutable JSON values, matching the pre-memoization behavior.
         definitions = [_copy_json_without_aliases(tool) for tool in selected]
         if schema_mode != "compact":
-            alternate_inputs = _generate_pydantic_schemas(
-                (definition["name"] for definition in definitions),
-                schema_mode=schema_mode,
-            )
+            names = [definition["name"] for definition in definitions]
+            alternate_inputs = _generate_pydantic_schemas(names, schema_mode=schema_mode)
+            # Outputs follow the same mode. They used to be inlined
+            # unconditionally, which is what made a 13-tool seller advertise a
+            # 24 MB tools/list while its input schemas were 15 KB each.
+            alternate_outputs = _generate_pydantic_output_schemas(names, schema_mode=schema_mode)
             for definition in definitions:
                 alternate = alternate_inputs.get(definition["name"])
                 if alternate is not None:
                     definition["inputSchema"] = alternate
+                alternate_output = alternate_outputs.get(definition["name"])
+                if alternate_output is not None:
+                    definition["outputSchema"] = alternate_output
         for definition in definitions:
             if definition["name"] == "sync_reporting_receipts":
                 from adcp.reporting.receipts.wire import receipt_schema
@@ -3745,6 +3807,15 @@ def __init__(
             adcp_version=resolved_adcp_version,
             schema_mode=schema_mode,
         )
+        # Adopters who wire ``tool_definitions`` into their own
+        # ``@server.list_tools()`` never reach ``create_mcp_server``, so this
+        # is their only size signal.
+        from adcp.server.serve import warn_if_discovery_payload_is_oversized
+
+        warn_if_discovery_payload_is_oversized(
+            tool_defs=self._filtered_definitions,
+            advertise_all=advertise_all,
+        )
         self._tools: dict[str, Callable[..., Any]] = {}
 
         # Create tool callers only for filtered tools