Refactor: Enhance OpenAPI spec for Knowledge Base Server

This ticket is part of Epic #7668.

The goal is to update ai/mcp/server/knowledge-base/openapi.yaml to make the query_documents tool self-documenting. This involves moving detailed usage instructions from AGENTS.md into the description of the /documents/query path and its associated schema.

Proposed Changes to openapi.yaml

1. Expand /documents/query Description

Update the description for the POST /documents/query operation with the following content:

description: |
  Performs a semantic search on the knowledge base using a natural language query.
  Returns a scored and ranked list of the most relevant source files.

  ## How to Use This Tool
  
  **Input:**
  - `query`: Natural language search query (1-10 words work best)
  - `type`: Optional filter by content type (all, blog, guide, src, example, ticket, release)
  
  **Output:**
  A ranked list of file paths with relevance scores. Example:

Most relevant source files (by weighted score):

• /path/to/relevant/file1.mjs (Score: 350)
• /path/to/relevant/file2.md (Score: 210)
• /path/to/relevant/file3.mjs (Score: 150)

Top result: /path/to/relevant/file1.mjs

  

How to Interpret Results

Start with the top result: Always read the highest-scoring file first.
Scan the next 5-10 results: Check both file types and scores.
Balance source and guides: Read top 1-2 source files (.mjs) AND top 1-2 guides (.md).

.mjs files: Implementation details, actual code
.md files: Conceptual context, architectural rationale


Prioritize content types:

guide and src: Current best practices and implementation
blog: Historical context (code examples may be outdated)
example: Concrete usage patterns
ticket: Historical decisions and problem-solving context



Query Strategies
Strategy 1: Broad to Narrow (Discovery Pattern)
  When learning about a new concept:

Start broad: "benefits", "architecture", "fundamentals"
Read results from learn/benefits/ or top-level .md files.
Narrow down: "Button component examples", "afterSet hook"
Find patterns: "form validation patterns", "store implementation"

Strategy 2: High-Level Conceptual Questions
  For architectural or "big picture" questions:

Check learn/tree.json for content structure.
Use top-level categories: "Benefits", "Fundamentals".
Query using those concepts first.
Drill down into specific implementations.

Strategy 3: Targeted Content-Type Searching
  Use the type parameter to focus results:

Conceptual understanding: type='guide'
Usage examples: type='example'
Implementation details: type='src'
Historical context: type='ticket' or type='blog'

  Pro tip: If a broad query returns too many source files and not enough guides, re-run with type='guide'. If you need implementation after reading guides, re-run with type='src'.
When Queries Return No Results
  If systematic querying still yields no relevant information, STOP and document the gap:

Clearly describe what you were trying to accomplish.
List the queries you attempted.
Explain why existing results were insufficient.
Suggest what type of documentation would help (e.g., a guide, an example, or an architectural explanation).

Handling Failures
  If this tool fails or throws an error:

Run the healthcheck tool to diagnose the issue.
If unhealthy, consult .github/AI_QUICK_START.md for setup guidance.

2. Enhance QueryRequest Schema

Update the description for the properties within the QueryRequest schema:

QueryRequest:
  type: object
  required:
    - query
  properties:
    query:
      type: string
      description: |
        Natural language search query. Best practices:
        - Keep queries concise (1-10 words)
        - Use specific technical terms when known
        - Start broad, then narrow based on results
        - Example good queries: "Button component", "state management patterns", 
          "afterSet hook implementation", "multi-window architecture"
      example: "How do I use the Tab Container component?"
    type:
      type: string
      description: |
        Filter results by content type:
        - `all`: Search all content (default)
        - `guide`: Conceptual explanations and architectural docs
        - `src`: Source code implementation
        - `example`: Working examples and demos
        - `blog`: Historical context and evolution (code may be outdated)
        - `ticket`: Past issues, decisions, and problem-solving
        - `release`: Release notes and changelogs
      enum: [all, blog, guide, src, example, ticket, release]
      default: all