Skip to content

docs: enhance query descriptions for clarity and specificity#2868

Open
enesgules wants to merge 4 commits into
masterfrom
improve-docs-prompt
Open

docs: enhance query descriptions for clarity and specificity#2868
enesgules wants to merge 4 commits into
masterfrom
improve-docs-prompt

Conversation

@enesgules

Copy link
Copy Markdown
Collaborator

No description provided.

@fahreddinozcan

Copy link
Copy Markdown
Contributor

A few consistency gaps found while reviewing, all about surfaces that didn't get the new single-concept guidance or that now diverge from it:

  1. skills/context7-cli/references/docs.md:81-90 - Missed copy. The "Writing good queries" section here is a near-verbatim twin of the one updated in skills/find-docs/SKILL.md: it still lacks the single-concept rule and the "Bad (too broad)" table row, and line 90 still says "Use the user's full question as the query when possible" with no caveat. Agents using the context7-cli skill keep the old behavior.

  2. packages/pi/skills/context7-docs/SKILL.md:36 - Missed copy inside a bumped package. Step 2 still says "Call query-docs with the chosen library ID and the user's question" with no split-per-concept guidance. Since pi's package.json publishes skills/, the same @upstash/context7-pi patch release ships the new tool description alongside stale skill instructions.

  3. docs/agentic-tools/ai-sdk/tools/query-docs.mdx:66 - The public AI SDK docs page still shows the old query description verbatim, so the published docs no longer match the updated .describe() string in packages/tools-ai-sdk.

  4. plugins/claude/context7/agents/docs-researcher.md:37 - The retained bullet "Pass the user's full question as the query parameter" is left unqualified directly above the new split-per-concept bullet, so the two adjacent guidelines contradict each other for multi-topic questions. The CLI rule files solved this by merging the caveat into the same sentence ("...but keep each query to a single concept"); the docs-researcher agents (claude, copilot, cursor variants) and the SKILL.md "Be specific" bullets didn't get the same treatment.

  5. Dash-style inconsistency - The three TypeScript description strings (packages/mcp/src/index.ts:268, packages/pi/lib/prompts.ts, packages/tools-ai-sdk/src/tools/query-docs.ts) and skills/find-docs/SKILL.md write the new clause with an em dash ("one topic — if..."), while the identical sentence in templates.ts, rules/context7-cli.md, and rules/context7-mcp.md uses --, which is the existing convention in those files. These copies are hand-synced with no parity check, so mixed styles will create noise on the next sync.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants