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

[nightscape]

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

[Copilot]

🟢 Approval recommended

The changes are documentation-only and the remaining feedback is limited to minor clarity/spelling consistency.

Pull request overview

This PR updates the UTCP implementation documentation to explicitly define forward-compatibility behavior so clients can load manuals that include unknown protocol call templates, unknown keys, and implementation-specific x- extensions.

Changes:

• Adds a new “Forward Compatibility” section specifying required client behavior for unknown call_template_type values (skip tool, warn, continue loading others).
• Defines how clients should handle unknown keys (ignore for behavior, preserve on round-trip where possible).
• Reserves x- keys for implementation extensions and adds guidance on when to use x- vs a custom call_template_type, plus a cross-reference from the custom protocol section.

File summaries

File	Description
docs/implementation.md	Documents forward-compatibility rules for unknown protocol handlers, unknown keys, and x- extension keys; adds cross-reference from custom protocol guidance.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cubic-dev-ai]

2 issues found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/implementation.md">

<violation number="1" location="docs/implementation.md:184">
P3: Clarify the two cases covered by this requirement by naming unsupported protocols and keys introduced by later specification versions.</violation>

<violation number="2" location="docs/implementation.md:193">
P3: Use the document's established American-English spelling: change `unrecognised` to `unrecognized`.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Clarify the two cases covered by this requirement by naming unsupported protocols and keys introduced by later specification versions.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/implementation.md, line 184:

<comment>Clarify the two cases covered by this requirement by naming unsupported protocols and keys introduced by later specification versions.</comment>

<file context>
@@ -178,6 +178,54 @@ Variables in call templates are replaced with actual values using two different
+### Forward Compatibility
+
+A manual outlives the client that reads it. Providers add tools on new protocols, and
+later specification versions add keys. A client MUST keep a manual usable when it meets
+either.
+
</file context>

[cubic-dev-ai]

P3: Use the document's established American-English spelling: change unrecognised to unrecognized.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/implementation.md, line 193:

<comment>Use the document's established American-English spelling: change `unrecognised` to `unrecognized`.</comment>

<file context>
@@ -178,6 +178,54 @@ Variables in call templates are replaced with actual values using two different
+handler for, the client MUST:
+
+1. **Skip that tool** — do not register it and do not offer it to the agent.
+2. **Warn**, naming the tool and the unrecognised type.
+3. **Register every other tool** in the manual normally.
+
</file context>

Suggested change

	2. **Warn**, naming the tool and the unrecognised type.
	2. **Warn**, naming the tool and the unrecognized type.