LearnNewsExamplesServices
Frontmatter
id7672
titleRefactor: Refine Query Tool Documentation in openapi.yaml
stateClosed
labels
documentationenhancementai
assigneestobiu
createdAtOct 27, 2025, 10:05 AM
updatedAtOct 27, 2025, 10:14 AM
githubUrlhttps://github.com/neomjs/neo/issues/7672
authortobiu
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtOct 27, 2025, 10:14 AM

Refactor: Refine Query Tool Documentation in openapi.yaml

Closed v11.0.0 documentationenhancementai
tobiu
tobiu commented on Oct 27, 2025, 10:05 AM

This ticket is a follow-up to #7669 and is based on feedback from Sonnet 4.5. The goal is to further refine the documentation for the query_documents tool within ai/mcp/server/knowledge-base/openapi.yaml.

This ticket covers the following changes:

1. Reframe "When Queries Fail" for Collaboration

Update the section on handling empty query results to be more collaborative instead of a hard stop.

New Text for the description of /documents/query:

      ## When Queries Return No Results
      
      If queries consistently return no relevant results for your task:

      **Pause and document the gap:**
      - Clearly describe what you were trying to accomplish
      - List the queries you attempted (show your work)
      - Explain why existing results were insufficient
      - Consult with the user about next steps

      **Before implementing based on assumptions:**
      - Explain the knowledge gap you've identified
      - Propose your approach and its basis (general software patterns, analogous Neo.mjs patterns, etc.)
      - Get explicit user approval to proceed

2. Consolidate Query Strategies

Refactor the query strategies into a single, more concise "Discovery Pattern".

New Text for the description of /documents/query:

      ## Query Strategies

      ### The Discovery Pattern: Broad to Narrow
      When learning about a new concept or feature area:

      1.  **Start Broad:** Query foundational concepts first.
          - For high-level questions, consult `learn/tree.json` to identify key concepts.
          - Use terms like `"benefits"`, `"architecture"`, `"fundamentals"`.
          - Prioritize reading guides from top-level directories.

      2.  **Narrow to Specifics:** Use broad results to formulate targeted queries.
          - `query_documents(query='Button component examples')`
          - `query_documents(query='what is Neo.component.Base?')`

      3.  **Filter by Type:** Use the `type` parameter for focused results.
          - Conceptual: `type='guide'`
          - Usage examples: `type='example'`
          - Implementation: `type='src'`

3. Remove Redundant "Do NOT" List

The Do NOT list at the end of the "When Queries Fail" section is redundant with the Anti-Hallucination Policy and should be removed from the openapi.yaml description.

tobiu added the documentation label on Oct 27, 2025, 10:05 AM
tobiu added the enhancement label on Oct 27, 2025, 10:05 AM
tobiu added the ai label on Oct 27, 2025, 10:06 AM
tobiu assigned to @tobiu on Oct 27, 2025, 10:06 AM
tobiu referenced in commit 599c2fc - "Refactor: Refine Query Tool Documentation in openapi.yaml #7672" on Oct 27, 2025, 10:13 AM
tobiu closed this issue on Oct 27, 2025, 10:14 AM