feat: Zod-validated tool responses and stable/experimental field taxonomy

[jonathanMLDev]

Summary

MCP success payloads now separate stable fields from experimental diagnostics under experimental, and all nine tools validate responses with Zod before return. Schemas and helpers are exported from the package root for client-side validation.

Related Issue

• Close Stable vs experimental response field boundary #139
• Close Informal response shape → Zod-validated contracts #140

Changes

• response-schemas.ts — 9 per-tool Zod schemas + shared queryResultRowSchema; QueryResponse / QueryResultRowShape derived via z.infer
• validatedJsonResponse() — runtime .parse() on success path (mirrors toolErrorSchema on errors)
• query, query_documents, guided_query — degradation fields and decision_trace moved to experimental (omitted when empty)
• buildQueryExperimental / buildGuidedQueryExperimental helpers
• Docs: TOOLS.md stability table, deprecation-policy.md promotion process, MIGRATION.md before/after, CHANGELOG.md breaking entry
• Tests: response-schemas.test.ts + schema alignment in all 9 *.context.test.ts files

Acceptance criteria

• Stable vs experimental boundary documented; promotion guard in CONTRIBUTING
• Zod schemas for all 9 tool responses; handlers call validatedJsonResponse
• Schemas exported from @will-cppa/pinecone-read-only-mcp
• npm run ci green (246 tests)

Test plan

• npm run ci
• response-schemas.test.ts — valid fixtures + rejection cases
• Per-tool expectMatchesResponseSchema in context tests
• CI green on PR

Notes for reviewers

• Breaking (MCP): clients reading top-level degraded / decision_trace must switch to experimental.* (pre-1.0, documented in MIGRATION).
• guided_query.result uses z.union([countBranch, queryResponse]) — no shared discriminant key.
• KeywordSearchResponse re-export from keyword-search-tool.ts kept @deprecated for one minor cycle.

Summary by CodeRabbit

Release Notes

• Breaking Changes

  • Experimental MCP response fields (e.g., degraded, degradation_reason, hybrid_leg_failed, decision_trace) are now nested under an experimental object in success payloads

• New Features

  • Zod schemas for all nine MCP tool success responses are now exported for client-side runtime validation
  • Response field stability taxonomy defining stable vs. experimental fields

• Documentation

  • Added deprecation policy documenting response field classification and promotion workflow
  • Updated migration guide detailing experimental field nesting changes
  • Added field stability matrix to tool documentation

[coderabbitai]

Warning

Review limit reached

@jonathanMLDev, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 3 minutes and 47 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9d504702-352b-482a-b783-d73b10c6b226

📥 Commits

Reviewing files that changed from the base of the PR and between 97cfaf7 and e51e74d.

📒 Files selected for processing (11)

• README.md
• docs/CONFIGURATION.md
• docs/MIGRATION.md
• examples/alliance/README.md
• examples/alliance/guided-query-demo.ts
• src/core/index.ts
• src/core/server/response-schemas.test.ts
• src/core/server/response-schemas.ts
• src/core/server/tool-response.test.ts
• src/core/server/tools/keyword-search-tool.ts
• src/core/server/tools/query-tool.ts

📝 Walkthrough

Walkthrough

This PR implements stable vs experimental response field classification and Zod-backed runtime validation for all MCP tool success responses. Experimental fields (degradation diagnostics, decision traces, rerank status) are nested under an experimental key. Documentation defines the taxonomy and promotion workflow. Zod schemas validate all responses at runtime.

Changes

Documentation & Deprecation Policy Foundation

Layer / File(s)	Summary
Stable/experimental field taxonomy and promotion policy docs/deprecation-policy.md, docs/CONTRIBUTING.md, docs/MIGRATION.md, CHANGELOG.md	Establish the definition of stable vs experimental fields, where they appear in JSON, current experimental field inventory, promotion workflow (CHANGELOG → TOOLS.md → schema → tests), and the default rule that new pre-1.0.0 fields start experimental. Migration guide documents the breaking change with before/after examples.

Zod Response Schema Infrastructure

Layer / File(s)	Summary
Response schema definitions, builders, and exports src/core/server/response-schemas.ts, src/core/index.ts, src/types.ts, src/core/server/format-query-result.ts	Define Zod schemas for all nine tool success responses with inferred TypeScript types. Implement buildQueryExperimental and buildGuidedQueryExperimental helpers that conditionally construct the experimental envelope only when fields are present. Move QueryResponse and QueryResultRowShape to centralized response-schemas module and re-export from src/types.ts to guarantee single source of truth.
Runtime validation and test helpers src/core/server/tool-response.ts, src/core/server/tools/test-helpers.ts, src/core/server/response-schemas.test.ts	Add validatedJsonResponse helper that parses payloads against Zod schemas before returning responses (logs and returns error on failure). Add expectMatchesResponseSchema test helper. Comprehensive test suite verifies schema acceptance/rejection for all nine tools, including nested experimental field validation and negative cases (missing required fields, missing aliases).

Tool-by-Tool Schema Integration & Experimental Field Relocation

Layer / File(s)	Summary
Query and query documents tools src/core/server/tools/query-tool.ts, src/core/server/tools/query-tool.context.test.ts, src/core/server/tools/query-tool.test.ts, src/core/server/tools/query-documents-tool.ts, src/core/server/tools/query-documents-tool.context.test.ts, src/core/server/redaction.test.ts	Query tool uses buildQueryExperimental and validatedJsonResponse to return validated responses. Moves degradation_reason, rerank_skipped_reason, and hybrid_leg_failed under experimental envelope. Query documents tool applies the same pattern for its result set. Tests updated to assert schema conformance and read experimental fields from nested location.
Guided query tool src/alliance/tools/guided-query-tool.ts, src/alliance/tools/guided-query-tool.context.test.ts, src/alliance/tools/guided-query-tool.test.ts	Introduces enrichUrls variable to default enrich_urls when undefined and thread through tracing and row formatting. Uses buildGuidedQueryExperimental to wrap decision_trace and buildQueryExperimental for nested result degradation. Both count and query paths return validated responses. Tests updated to extract decision_trace from body.experimental and degradation fields from result.experimental.
Remaining tools (count, suggest params, keyword search, list namespaces, namespace router, generate URLs) src/core/server/tools/count-tool.ts, src/core/server/tools/count-tool.context.test.ts, src/alliance/tools/suggest-query-params-tool.ts, src/alliance/tools/suggest-query-params-tool.context.test.ts, src/core/server/tools/keyword-search-tool.ts, src/core/server/tools/keyword-search-tool.context.test.ts, src/core/server/tools/list-namespaces-tool.ts, src/core/server/tools/list-namespaces-tool.context.test.ts, src/core/server/tools/namespace-router-tool.ts, src/core/server/tools/namespace-router-tool.context.test.ts, src/core/server/tools/generate-urls-tool.ts, src/core/server/tools/generate-urls-tool.context.test.ts	Each tool replaces unvalidated jsonResponse with schema-validated validatedJsonResponse. Keyword search moves its local KeywordSearchResponse type to centralized response-schemas and re-exports with deprecation notice. All tool tests add schema conformance assertions via expectMatchesResponseSchema.
Constants and documentation references src/constants.ts, docs/TOOLS.md	Update ALLIANCE_INSTRUCTIONS_APPENDIX to reference experimental.decision_trace. Update TOOLS.md with field stability matrix, nested experimental structure, and rerank/hybrid degradation behavior guidance.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• cppalliance/pinecone-read-only-mcp-typescript#142: Modifies guided-query-tool.ts and the formatQueryResultRows call site to change threading of options; overlaps with main PR's experimental response construction and enrichUrls handling.
• cppalliance/pinecone-read-only-mcp-typescript#109: Related to guided_query decision_trace and rerank_status shaping via guidedRerankStatus; overlaps with main PR's experimental field nesting in guided_query responses.

Suggested labels

enhancement

Suggested reviewers

• AuraMindNest
• wpak-ai
• leostar0412

Poem

🐰 Experimental fields find their rest,
Nested safely in the experimental nest,
Zod schemas guard the contract tight,
Validation runs both day and night,
Stable roads lead onward bright! 🎯

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: Zod-validated tool responses and stable/experimental field taxonomy' clearly and concisely summarizes the two main objectives: implementing Zod-validated responses and introducing the stable/experimental field separation.
Linked Issues check	✅ Passed	The PR comprehensively addresses both linked issues: #139 (stable/experimental boundary via nested experimental object) and #140 (Zod schemas for all 9 tools with runtime validation).
Out of Scope Changes check	✅ Passed	All changes directly support the two core objectives: response schema definitions, field reorganization, builder utilities, documentation updates, and test coverage. No unrelated refactoring or feature additions detected.
Docstring Coverage	✅ Passed	Docstring coverage is 88.89% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 98.48485% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@61605dd). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/core/server/tools/namespace-router-tool.ts	50.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #151   +/-   ##
=======================================
  Coverage        ?   87.27%           
=======================================
  Files           ?       40           
  Lines           ?     1634           
  Branches        ?      544           
=======================================
  Hits            ?     1426           
  Misses          ?      208           
  Partials        ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jonathanMLDev]

@coderabbitai full review again

[coderabbitai]

@jonathanMLDev Sure! I'll kick off a full review of the PR now.

✅ Action performed

Full review finished.

[leostar0412]

examples/alliance/guided-query-demo.ts and examples/alliance/README.md are stale: they still reference top-level decision_trace, which moved to experimental.decision_trace.