Context (A2A — Antigravity, Claude Opus 4.6)
#9893 successfully promoted ask_knowledge_base across AGENTS.md (§2.1 tool hierarchy table) and AGENTS_STARTUP.md (§3.4 "Ask the Expert" protocol). However, the CodebaseOverview — the first document every agent reads on startup — still structurally privileges query_documents over ask_knowledge_base.
The Structural Imbalance
The "Key Concepts: Query Entry Points" section (L538-590) currently allocates:
- 1 bullet (~1 line) to
ask_knowledge_base (L542)
- 45+ lines to
query_documents keyword lists organized into 10 subsections (L543-590)
Agents scanning this section will naturally gravitate to the visually dominant tool. The hierarchy is inverted.
Empirical Proof (Same Query, Two Tools)
Tested with: "How does the Core Engine pipeline work?"
| Tool |
Result |
Agent Cost |
ask_knowledge_base |
Complete synthesized answer (~2,500 words) with 5 cited sources, covering setupClass, config merging, reactive getter generation, instance lifecycle, and mounting phases |
1 tool call |
query_documents |
25 ranked file paths including significant noise (DataPipelines.md, ContentEngine.md, DevIndex factory guides). Only 4 of the top 10 results were directly relevant. |
1 + N tool calls (minimum 3-5 view_file to assemble understanding) |
The ask_knowledge_base tool is functionally a zero-cost RAG subagent — it reads, retrieves, and synthesizes answers from the current indexed codebase. For conceptual questions, it eliminates the query_documents → view_file → read → interpret chain entirely.
Proposed Change
Restructure the "Key Concepts: Query Entry Points" section to:
- Lead with
ask_knowledge_base — expand from 1 line to 5-8 lines with 3-4 example queries showing the tool's power for different question types (conceptual, syntax verification, architectural patterns)
- Add a clear decision table — when to use
ask vs query_documents vs view_file (similar to the hierarchy table in AGENTS.md §2.1, but adapted for the CodebaseOverview's pedagogical style)
- Reposition
query_documents keyword lists — keep them as a secondary reference under a subheading like "File Discovery Keywords" rather than as the section's primary content
- Add anti-pattern warning — "Do NOT attempt to answer Neo.mjs questions from training data. The framework evolves rapidly — your training data is almost certainly outdated for syntax-level details."
Content Sketch
<h2 class="neo-h2" data-record-id="7">Key Concepts: Query Entry Points</h2>
<h3 class="neo-h3" data-record-id="8">Ask First, Search Second</h3>
Your most powerful tool is `ask_knowledge_base`. It reads multiple source files,
synthesizes a grounded answer, and cites its references — all in a single call.
**Example queries:**
- `ask_knowledge_base(query='how does the reactive config system work?')`
- `ask_knowledge_base(query='current syntax for state provider bindings')`
- `ask_knowledge_base(query='how to define a Grid with multiple bodies')`
- `ask_knowledge_base(query='what is the difference between ntype and className?', type='guide')`
| Question Type | Tool | Returns |
|---|---|---|
| "How does X work?" | `ask_knowledge_base` | Synthesized answer + source citations |
| "Which files implement Z?" | `query_documents` | Ranked file paths with relevance scores |
| Exact implementation details | `view_file` | Raw source code |
<h3 class="neo-h3" data-record-id="9">File Discovery Keywords</h3>
When you specifically need to discover *which files* implement something,
use `query_documents` with these high-value terms:
[...existing keyword lists...]
Scope
- Documentation-only. No code changes.
- Single file modified:
learn/guides/fundamentals/CodebaseOverview.md
- Builds on #9893 (already closed — promoted
ask_knowledge_base in AGENTS.md and AGENTS_STARTUP.md)
- Builds on #9898 (already closed — added Core Engine cross-references and
tree.json pointers)
Architectural Context
- The CodebaseOverview is read in
AGENTS_STARTUP.md Step 1 — it's the first document agents see
ask_knowledge_base is backed by the Knowledge Base MCP server's LearningSource.mjs which uses tree.json to index all 130+ guides
- The tool can filter by content type (
guide, src, example, ticket, blog, release, test)
Context (A2A — Antigravity, Claude Opus 4.6)
#9893 successfully promoted
ask_knowledge_baseacrossAGENTS.md(§2.1 tool hierarchy table) andAGENTS_STARTUP.md(§3.4 "Ask the Expert" protocol). However, the CodebaseOverview — the first document every agent reads on startup — still structurally privilegesquery_documentsoverask_knowledge_base.The Structural Imbalance
The "Key Concepts: Query Entry Points" section (L538-590) currently allocates:
ask_knowledge_base(L542)query_documentskeyword lists organized into 10 subsections (L543-590)Agents scanning this section will naturally gravitate to the visually dominant tool. The hierarchy is inverted.
Empirical Proof (Same Query, Two Tools)
Tested with: "How does the Core Engine pipeline work?"
ask_knowledge_basesetupClass, config merging, reactive getter generation, instance lifecycle, and mounting phasesquery_documentsDataPipelines.md,ContentEngine.md, DevIndex factory guides). Only 4 of the top 10 results were directly relevant.view_fileto assemble understanding)The
ask_knowledge_basetool is functionally a zero-cost RAG subagent — it reads, retrieves, and synthesizes answers from the current indexed codebase. For conceptual questions, it eliminates thequery_documents→view_file→ read → interpret chain entirely.Proposed Change
Restructure the "Key Concepts: Query Entry Points" section to:
ask_knowledge_base— expand from 1 line to 5-8 lines with 3-4 example queries showing the tool's power for different question types (conceptual, syntax verification, architectural patterns)askvsquery_documentsvsview_file(similar to the hierarchy table inAGENTS.md§2.1, but adapted for the CodebaseOverview's pedagogical style)query_documentskeyword lists — keep them as a secondary reference under a subheading like "File Discovery Keywords" rather than as the section's primary contentContent Sketch
<h2 class="neo-h2" data-record-id="7">Key Concepts: Query Entry Points</h2> <h3 class="neo-h3" data-record-id="8">Ask First, Search Second</h3> Your most powerful tool is `ask_knowledge_base`. It reads multiple source files, synthesizes a grounded answer, and cites its references — all in a single call. **Example queries:** - `ask_knowledge_base(query='how does the reactive config system work?')` - `ask_knowledge_base(query='current syntax for state provider bindings')` - `ask_knowledge_base(query='how to define a Grid with multiple bodies')` - `ask_knowledge_base(query='what is the difference between ntype and className?', type='guide')` | Question Type | Tool | Returns | |---|---|---| | "How does X work?" | `ask_knowledge_base` | Synthesized answer + source citations | | "Which files implement Z?" | `query_documents` | Ranked file paths with relevance scores | | Exact implementation details | `view_file` | Raw source code | <h3 class="neo-h3" data-record-id="9">File Discovery Keywords</h3> When you specifically need to discover *which files* implement something, use `query_documents` with these high-value terms: [...existing keyword lists...]Scope
learn/guides/fundamentals/CodebaseOverview.mdask_knowledge_baseinAGENTS.mdandAGENTS_STARTUP.md)tree.jsonpointers)Architectural Context
AGENTS_STARTUP.mdStep 1 — it's the first document agents seeask_knowledge_baseis backed by the Knowledge Base MCP server'sLearningSource.mjswhich usestree.jsonto index all 130+ guidesguide,src,example,ticket,blog,release,test)