docs: specify forward compatibility for unknown call template types, unknown keys and x- extensions
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
httptool and one tool with an unregistered
call_template_typeregisters zero tools.
CallTemplateSerializer.validate_dictraisesValueError("Invalid call template type: ...")for the one tool, and that failure propagates out of
UtcpManual.validate_toolsand takes the valid tool with it. - A manual carrying the
infokey — the key this repository's own
docs/implementation.mdputs 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 anhttpcall 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