Skip to content

Gate tools/list on 'handler overrode this method' — stop not_supported defaults from polluting the advertised surface #220

Description

@bokelley

Summary

ADCPHandler auto-registers all ~57 AdCP tools on every server started via create_mcp_server() / create_a2a_server(), including ones where the subclass inherits the base class's not_supported default. The result: an agent that implements get_products and 2-3 other tools still advertises all 57 in tools/list. With Pydantic-generated schemas averaging 300-600 tokens each after $defs resolution, that's 20-30K tokens of tool metadata shipped to every client on connect.

Noted by @agentic-product-architect in the PR #219 review:

Today this is tolerable because AdCP agents are called by other agents with 200K+ windows. In 12 months, when AdCP agents get consumed by lighter-weight orchestrators (ChatGPT app, Claude skill, mobile agent), advertising the full surface will look profligate.

Proposed fix

Add a registration-time filter: only advertise tools whose handler method was actually overridden by the subclass. The information is knowable:

# In adcp.server.mcp_tools.get_tools_for_handler():
handler_cls = type(handler)
for tool_def in ADCP_TOOL_DEFINITIONS:
    method_name = tool_def["name"]
    own_method = getattr(handler_cls, method_name, None)
    base_method = getattr(ADCPHandler, method_name, None)
    if own_method is base_method:
        continue  # subclass inherited the not-supported stub; skip advertising
    tools.append(tool_def)

Knobs to consider:

  • Escape hatch for agents that want to advertise a spec-mandated tool even though they haven't implemented it (e.g. get_adcp_capabilities is the handshake and must always be present — it's a special case already).
  • Per-protocol handler classes (GovernanceHandler, ContentStandardsHandler, etc.) — the override check should walk the MRO stopping at the SDK-provided base.
  • advertised: bool class attribute on base methods as an opt-in override.

Tradeoffs

  • Subclasses that intentionally want to expose a not_supported tool (to declare "this agent knows about X but can't do it") lose that ability unless we add the opt-in escape hatch.
  • Spec-compliance tests that call every tool and expect either a real response or not_supported need to adapt — the tool simply won't be listed.
  • Docs need to say "override the method = advertise the tool."

Context

Tracked from PR #219 expert review. Not breaking for existing downstreams at registration-time (the same handler still works), but observably changes tools/list output, so ship with a CHANGELOG entry.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions