updated descriptions by jonathanMLDev · Pull Request #81 · cppalliance/pinecone-read-only-mcp-typescript

jonathanMLDev · 2026-05-13T23:51:43Z

MCP description updates

src/server/tools/query-tool.ts — query, query_fast, and query_detailed now include: Requires suggest_query_params to be called first for the target namespace.
src/server/tools/query-documents-tool.ts — Same sentence for query_documents.
src/server/tools/keyword-search-tool.ts — Does not require suggest_query_params (with a trailing period on the sentence).
src/server/tools/guided-query-tool.ts — Opens with: Combines namespace routing, suggestion, and query into a single call — no prerequisite tools needed. (em dash as in the issue), then the existing orchestrator / decision_trace text.

JSDoc pointers

Each of the four register*Tool functions now has a short block comment pointing at "Retrieval tool decision matrix" in README.md.

README

New README.md subsection Retrieval tool decision matrix (before ### suggest_query_params) with the two-line decision guide and bullets for query / query_fast / query_detailed, query_documents, keyword_search, guided_query, and count.

Verification

npm run build completed successfully.
Grep confirms the required phrases appear in the intended tool files.
No new linter issues on the edited .ts files.

close #80

Summary by CodeRabbit

Documentation
- Added a retrieval tool decision matrix to README, providing guidance on selecting the appropriate retrieval tool based on search type, scope, and execution flow.
- Enhanced tool descriptions across the retrieval tool suite to clarify capabilities and prerequisite requirements.

coderabbitai · 2026-05-13T23:51:53Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4e0104ef-bca6-4629-90ef-38d30f395613

📥 Commits

Reviewing files that changed from the base of the PR and between b40d520 and 00754e5.

📒 Files selected for processing (2)

src/server/tools/guided-query-tool.ts
src/server/tools/query-tool.ts

✅ Files skipped from review due to trivial changes (2)

src/server/tools/guided-query-tool.ts
src/server/tools/query-tool.ts

📝 Walkthrough

Walkthrough

The PR clarifies flow-constraint documentation for retrieval tools by adding a decision matrix to the README and updating tool descriptions and JSDoc blocks to explicitly state whether suggest_query_params is a prerequisite, making flow-gate requirements visible to AI clients.

Changes

Retrieval Tool Flow Constraints Documentation

Layer / File(s)	Summary
Decision matrix: README guidance `README.md`	Inserts a "Retrieval tool decision matrix" classifying tools by semantic vs lexical search, chunk vs document retrieval, one-shot vs gated flows, and specify prerequisites.
Query tools requiring suggest_query_params `src/server/tools/query-tool.ts`, `src/server/tools/query-documents-tool.ts`	`query` and `query_documents` descriptions explicitly state that `suggest_query_params` must be called first for the target namespace; JSDoc blocks added with README cross-references.
Keyword search ungated description `src/server/tools/keyword-search-tool.ts`	`keyword_search` description clarified to state it does not require `suggest_query_params`; JSDoc block added with decision-matrix reference.
Guided query orchestrator description `src/server/tools/guided-query-tool.ts`	`guided_query` reframed as a single orchestrator combining routing, suggestion, and execution with no prerequisite tools; flow text updated to reflect the all-in-one design.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

cppalliance/pinecone-read-only-mcp-typescript#31: Implements registerKeywordSearchTool and tool schema/behavior; this PR updates the tool's description to align with the decision matrix by clarifying that suggest_query_params is not required.

Suggested labels

enhancement

Suggested reviewers

wpak-ai

Poem

🐰 A guide map drawn in code and prose,
Tools speak their truth now—who requires what flows!
Query gates and free-form searches align,
While guided orchestration orchestrates just fine. ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title "updated descriptions" is vague and generic; it does not clearly convey what descriptions were updated or why.	Consider a more specific title like "Add retrieval tool decision matrix and clarify suggest_query_params requirements" to better reflect the core changes.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	All acceptance criteria from issue `#80` are met: tool descriptions explicitly state suggest_query_params requirements, decision matrix added to README, and all specified phrase requirements are satisfied.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue `#80`: updating tool descriptions, adding JSDoc pointers, and creating the decision matrix documentation as required.

_{✏️ 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

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

…thanMLDev/pinecone-read-only-mcp-typescript into bugfix/hidden-flow-document # Conflicts: # src/server/tools/query-tool.ts

codecov · 2026-05-14T00:15:17Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@c07279f). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #81   +/-   ##
=======================================
  Coverage        ?   52.68%           
=======================================
  Files           ?       30           
  Lines           ?     1118           
  Branches        ?      346           
=======================================
  Hits            ?      589           
  Misses          ?      529           
  Partials        ?        0

☔ View full report in Codecov by Sentry.
📢 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 · 2026-05-14T02:44:58Z

@coderabbitai full review

coderabbitai · 2026-05-14T02:45:03Z

✅ Actions performed

Full review triggered.

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.gitignore:
- Line 8: Remove the redundant "data/" entry in .gitignore so the directory is
ignored exactly once; locate the duplicate "data/" line (the extra occurrence)
and delete it, leaving the single existing "data/" ignore entry intact.

In `@src/server/tools/guided-query-tool.ts`:
- Around line 37-39: Update the guided flow description string in
guided-query-tool to reference the full/query path: change the phrase that lists
executed paths from "count/query_fast/query_detailed" to include "query" (e.g.,
"count/query_fast/query_detailed/query (full)") so the docstring accurately
reflects that the tool may execute the full "query" path; edit the module's
top-level description string where the concatenated sentences are defined (the
same string shown in the diff) to include this wording.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b9439ef1-dbd7-4623-ae21-8ab8b314bb84

📥 Commits

Reviewing files that changed from the base of the PR and between c07279f and b40d520.

📒 Files selected for processing (6)

.gitignore
README.md
src/server/tools/guided-query-tool.ts
src/server/tools/keyword-search-tool.ts
src/server/tools/query-documents-tool.ts
src/server/tools/query-tool.ts

updated descriptions

496cfe9

jonathanMLDev self-assigned this May 13, 2026

jonathanMLDev and others added 3 commits May 14, 2026 08:02

Merge branch 'main' into bugfix/hidden-flow-document

f854ae7

fixed typecheck errors

c07411b

Merge branch 'bugfix/hidden-flow-document' of https://github.com/jona…

b40d520

…thanMLDev/pinecone-read-only-mcp-typescript into bugfix/hidden-flow-document # Conflicts: # src/server/tools/query-tool.ts

coderabbitai Bot reviewed May 14, 2026

View reviewed changes

Comment thread .gitignore Outdated

Comment thread src/server/tools/guided-query-tool.ts

zho added 2 commits May 14, 2026 11:02

addressed ai review results

78e4472

fixed test error

00754e5

jonathanMLDev requested a review from wpak-ai May 14, 2026 15:38

wpak-ai approved these changes May 14, 2026

View reviewed changes

wpak-ai merged commit d2723d7 into cppalliance:main May 14, 2026
12 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

updated descriptions#81

updated descriptions#81
wpak-ai merged 6 commits into
cppalliance:mainfrom
jonathanMLDev:bugfix/hidden-flow-document

jonathanMLDev commented May 13, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 13, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

❌ Failed checks (1 warning, 1 inconclusive)

Uh oh!

codecov Bot commented May 14, 2026 •

edited

Loading

Uh oh!

jonathanMLDev commented May 14, 2026

Uh oh!

coderabbitai Bot commented May 14, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jonathanMLDev commented May 13, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

MCP description updates

JSDoc pointers

README

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

❌ Failed checks (1 warning, 1 inconclusive)

Uh oh!

codecov Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jonathanMLDev commented May 14, 2026

Uh oh!

coderabbitai Bot commented May 14, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jonathanMLDev commented May 13, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 13, 2026 •

edited

Loading

codecov Bot commented May 14, 2026 •

edited

Loading