fix(schema): close oneOf type-check bypass and render SEP-2106 Tool examples - #3185

This addresses an issue where the find_resource example distinguished its oneOf branches with branch-local properties. Failing a branch on a type error is exactly what makes oneOf succeed, so a wrongly-typed value in the inactive branch was accepted, eg:

{"id": "r1", "name": 123}    validated
{"id": 123, "name": "alpha"} validated

This means that the mutual exclusivity the example is meant to demonstrate was bypassable by supplying both fields and malforming one, and neither field was type-checked while it was the non-selected branch.

This change hoists properties to the schema root and reduces oneOf to the exclusivity assertion. Verified against ajv (2020-12):

Tradeoff

The original pattern exercised composition harder: a client that ignores oneOf entirely would render no fields at all. The corrected version degrades gracefully, since a naive client shows id and name as two optional strings. This seems like better authoring guidance.

Also in this PR: the authoring guidance that was missing

The inputSchema documentation already grants composition keywords (oneOf, anyOf, allOf, not) but never said how to use them safely, which is how the original example came to be written the way it was. Two sentences are added to that same paragraph, so the caveat arrives with the permission:

When using composition keywords, declare properties at the schema root and keep the branches to presence assertions such as required. A subschema that fails on a type error is indistinguishable from one that does not apply, so type constraints placed inside oneOf branches are not enforced for whichever branch does not match.

Also in this PR: wiring up the SEP-2106 Tool examples

tool-with-composition-input-schema.json and tool-with-array-output-schema.json shipped with SEP-2106 as files, but neither was referenced by an @includeCode, so neither appeared on the rendered Tool page. Both are now wired into schema/draft/schema.ts and schema/2026-07-28/schema.ts, with schema.mdx regenerated for both revisions.

Non-goal: SEP-2106 itself

SEP-2106 contains the same bypassable pattern in two places. It is deliberately left alone: the SEP is Final and carries the historical-record notice added in #3166, so it is preserved as the design as accepted rather than corrected in place. The spec examples are the authoritative reference, which is part of why rendering them matters.

🦉 AI assistance disclosure

Developed with Claude Code (Opus 5). It reviewed the original fix, then authored the 2026-07-28 example wiring, the inputSchema guidance paragraph, the regenerated artifacts, and this description. The oneOf behaviour in the table above was verified by running both schema variants through ajv rather than by inspection, and the generated files were checked against the repo's own generator output. I reviewed and directed each step, and understand and stand behind the changes.

Per AI_POLICY.md.