How to ask: Knowledge query best practices

A Knowledge search returns the best answer it has for your question. How you phrase each item in queries decides whether that answer is sharp or vague. Four rules cover almost every case.

1. Natural language, not keywords

Ask the way you would in a chat. Full, natural questions return the precise passage; loose keywords miss the meaning and come back weak.

A good test: imagine the question a documentation heading would answer, and ask that.

2. Keep every question focused

A focused question gets the sharpest answer. Open-ended prompts like “tell me everything” come back vague. If you need broader coverage, send several focused questions in one queries array (up to 5) - the engine searches each independently and merges the results.

3. Split compound questions

A question that bundles two topics matches neither well. Give each topic its own item in the queries array - one call, one merged result set - then feed the answers back to your AI as context so it can assemble the final reply.

If you let an AI agent drive the search, have it decompose compound questions into separate queries items automatically before each call.

4. Tune project and results

Two request fields shape what comes back:

• project picks which documentation set to search. With the demo key, that is vscode-docs. Always pass it - a search is only as relevant as the project it runs against.
• results sizes the response (1-50, default 10). A higher number returns more related passages; set it to fit your use case - small for a single sharp answer, larger when you want your AI to pick from several.