docs: specify forward compatibility for unknown call template types, unknown keys and x- extensions

NI
2mo ago
+53-0

The specification does not say what a client must do with content it does not
recognise. docs/implementation.md tells providers how to add a custom protocol
("Define Call Template, Implement Communication Handler, Register Protocol") but
never says what happens on the reading side when the plugin is absent. This PR
fills that gap with three rules: skip the unloadable tool, ignore unknown keys,
and reserve x- for implementations.

Why this matters more than a documentation tidy-up. The reference client
currently reads that silence as "reject everything". Measured against
python-utcp at 89a9832 (utcp 1.1.3, utcp-http 1.1.11, utcp-text 1.1.0):

  • A manual holding one http tool and one tool with an unregistered
    call_template_type registers zero tools.
    CallTemplateSerializer.validate_dict raises ValueError("Invalid call template type: ...") for the one tool, and that failure propagates out of
    UtcpManual.validate_tools and takes the valid tool with it.
  • A manual carrying the info key — the key this repository's own
    docs/implementation.md puts in its first example manual, lines 31–34
    —
    fails to load: TypeError: UtcpManual.__init__() got an unexpected keyword argument 'info'. The documented example is not loadable by the reference
    implementation.
  • An x- key on an http call template loads, but is dropped. A client that
    reads and rewrites a manual erases the extension.

The consequence for the ecosystem is a flag day: a provider who adds one tool on
a new protocol withdraws every tool it already published from every client that
has not installed that plugin yet. Providers therefore cannot adopt a new
protocol incrementally, which is the opposite of what the plugin architecture is
for.

The spec change

Adds ### Forward Compatibility to docs/implementation.md (under Core
Concepts, after Variable Substitution) and one cross-reference from the existing
"Custom Protocol Plugins" section. Only docs/ is touched; versioned_docs/ are
frozen snapshots of released versions.

Companion implementation

A companion PR against python-utcp implements these rules and adds tests:
universal-tool-calling-protocol/python-utcp#99

Happy to adjust the wording, or to take this to Discord first if the maintainers
would rather settle the rule there.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H9PKfvS16TzzLUHi3xPUV4