docs(spec): tool.json's parameters note records the post-#13317 reality

[os-project-manager]

Fixes#13345

What was stale

packages/spec/liveness/tool.json's _note on the parameters entry asserted, in substance, that registerToolFromDefinition registered every bridged tool with noinputSchema — "so this key never reaches an MCP client" — citing that as the asymmetry with name / description, and pointing at #13271 as evidence.

#13271 is now closed, by the PR that made that sentence false: PR #13317 (e29fc212, merged 2026-08-30T04:42:09Z) converts AIToolDefinition.parameters through zod@4's fromJSONSchema and forwards it as the SDK inputSchema — the SDK converts it straight back to JSON Schema for tools/list, so the key now reaches MCP clients too.

What changed

Only the parameters entry's _note sentence. Grade unchanged — parameters was live before this PR and stays live; the cloud LLM path (vercel-adapter.ts#buildVercelOptions) has read it all along and is what the verdict has always rested on. This closes an asymmetry between two consumers, not a liveness-status change. No other entry, no ledger mechanism, touched.

The replacement wording keeps the nuance the original note called out: the pre-#13317 behaviour was not "no schema" — the SDK synthesised EMPTY_OBJECT_JSON_SCHEMA ({"type":"object","properties":{}}) for a schema-less registration, a positive claim that the tool takes no arguments, which is a stronger misstatement than silence would have been.

Evidence now points at the current implementation with real anchors: packages/mcp/src/mcp-server-runtime.ts#toolInputSchema (L223-242, the fromJSONSchema conversion) and #registerToolFromDefinition (L998, the inputSchema: toolInputSchema(tool, logger) forward at L1005).

Note text — before

LLM function schema. Re-closed 2026-08-29 against cloud @15f55df. ⚠ Deliberately NOT co-cited to the framework MCP bridge, and the asymmetry with name / description is the finding: registerToolFromDefinition registers each bridged tool with NO inputSchema, and the annotations it does pass carry only destructiveHint / readOnlyHint / openWorldHint — so this key never reaches an MCP client, while its own docblock claims the JSON Schema is passed as annotations metadata. Filed as #13271. The verdict rests on the cloud LLM path alone, where it is unambiguously live.

Note text — after

LLM function schema. Re-closed 2026-08-29 against cloud @15f55df. The verdict itself never moved — this row was live throughout on the cloud LLM path alone (vercel-adapter.ts#buildVercelOptions), which is what the asymmetry below was measured against. ⚠ 2026-08-30 (#13345): the asymmetry this note used to record — registerToolFromDefinition registered each bridged tool with NO inputSchema, so this key reached the cloud LLM but not an MCP client, contradicting its own docblock — is CLOSED, by #13317 (e29fc212, merged 2026-08-30T04:42:09Z, filed as #13271). packages/mcp/src/mcp-server-runtime.ts#toolInputSchema (L223-242) now converts AIToolDefinition.parameters through zod@4's fromJSONSchema, and registerToolFromDefinition (L998) forwards the result as the SDK inputSchema (L1005), which the SDK converts straight back to JSON Schema for tools/list — the key reaches MCP clients too, now on both consumers. The pre-fix behaviour was NOT silence, and the replaced wording overstated it as such: a schema-less registration made the SDK synthesise EMPTY_OBJECT_JSON_SCHEMA ({"type":"object","properties":{}}) — a positive claim that the tool takes NO arguments, sharper than an absent key would have been. #13317 closes the asymmetry, not the grade.

Changeset

Followed the #13275 / #13309 precedent for ledger-note-only fixes: liveness/ is in @objectstack/spec's files array, so these ledgers ship in the npm tarball and are published data — a patch changeset is owed even though nothing schema/runtime/authoring-facing moved. .changeset/tool-liveness-parameters-note-post-13317.md.

Tests

• node -e "JSON.parse(...)" on tool.json — parses.
• pnpm --filter @objectstack/spec run check:liveness — green: ✓ every governed-type property ... classified ... every 'live' / 'planned' / 'experimental' entry's repo-local evidence path resolves ... (exit 0).
• pnpm --filter @objectstack/spec run check:empty-state / check:strictness-ledger / check:variant-docs — green.
• dispatch-gates.mjs-derived local family for this diff — every matched gate run and green: check:nul-bytes, check:merge-driver, check:page-declaration-shape, check:slot-lookup, check:test-source-alias, check:type-source-resolution, check:published-files, check:comment-mask-adoption, check-dev-prereqs.mjs --self-test (the CI-run form; lint.yml runs --self-test only per the script's own docblock), check-plugin-teardown-shape.mjs, check-undeclared-dep-imports.mjs, check-keyed-text-bounds.mjs, check-empty-changeset.mjs, check-changeset-no-major.mjs, check-adr-0087-registration.mjs, check:changeset-gate-self-tests, check:pm-half-states, check:objectui-changeset, docs-audit/check-affected-docs.mjs, docs-audit/check-drift-comment.mjs.
• Not run locally: check:dual-build-cjs-loads (requires a full pnpm build of all 78 workspace packages; matched only via the packages/** CI job path filter, and this diff touches no code or build artifact — left to CI's "Build Core" job, per the local-verification-scope rule that whole-farm scans are CI's territory).

HEAD at push: 378e7cb8.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/spec/liveness/tool.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/liveness/tool.json) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 126 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 56c5b1dbe7501b37a61c3ff26e8a0d9a490b808b → packageMentionDocs.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 33298382178 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (5/6) — 失败步骤: Run this shard's tests

  @objectstack/rest:test: FAIL src/ui-view-route-tenancy.measurement.test.ts > [#13214] §3 what the crossed response actually contains > ⚠️ `hidden` is NOT a uniform floor on the crossed path — measur
  ↳ 失败原因: @objectstack/rest:test: AssertionError: expected [ 'name', 'created_at', …(1) ] to include 'status'
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

跨 PR 相同签名（24h，按失败测试文件聚合）：

• src/ui-view-route-tenancy.measurement.test.ts — 24h 内已弹出 3 个 PR（test(rest): drive the tenancy axis of GET /ui/view/:object/:type — an anonymous caller can name another environment and receive its UI view #13258、fix(driver-memory): a no-value row satisfies $nin / $notContains in the reference matcher (#13166) #13356、docs(spec): tool.json's parameters note records the post-#13317 reality #13359），分属 2 条投机栈 ⇒ 2 次独立命中。汇总 issue：Queue-flake anchor: src/ui-view-route-tenancy.measurement.test.ts #13374（已刷新）
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 12 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[claude]

Queue-failure disposition (PR owner seat, session session_01KX8wnyjStaZcuMyAMNsy3N) — case 2 of the triage checklist: not this PR's failure; ⛔ not re-queuing until the anchor moves.

• Failing check: merge-queue full-suite run 33298382178, Test Core (5/6), packages/rest/src/ui-view-route-tenancy.measurement.test.ts (AssertionError: expected field list to include 'status').
• Why it is not this PR's, measured rather than asserted: this diff is one prose _note in packages/spec/liveness/tool.json plus a changeset — no code path, no schema, no rest package input. A liveness-ledger sentence cannot reach a rest tenancy measurement.
• The same signature hit 3 PRs / 2 independent speculative stacks in 24h (test(rest): drive the tenancy axis of GET /ui/view/:object/:type — an anonymous caller can name another environment and receive its UI view #13258, fix(driver-memory): a no-value row satisfies $nin / $notContains in the reference matcher (#13166) #13356, this one) per the triage bot's ledger — environment/order-dependence confirmed by independence, and the anchor issue is Queue-flake anchor: src/ui-view-route-tenancy.measurement.test.ts #13374. No fix exists yet to port (the test file is untouched on main since the hits began; a robustness fix belongs to the rest lane via Queue-flake anchor: src/ui-view-route-tenancy.measurement.test.ts #13374, not to this docs PR).
• Standing plan: auto-merge stays OFF; this seat re-arms once after Queue-flake anchor: src/ui-view-route-tenancy.measurement.test.ts #13374 records a fix or the anchor quiets. Tracked by the seat patrol chain.

---

Generated by Claude Code