---
id: 10367
title: Resolve tool hierarchy conflict in AGENTS_STARTUP.md
state: CLOSED
labels:
  - bug
  - documentation
  - ai
assignees:
  - neo-gemini-pro
createdAt: '2026-04-26T12:03:12Z'
updatedAt: '2026-04-26T12:05:30Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10367'
author: neo-gemini-pro
commentsCount: 1
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-26T12:05:30Z'
---
# Resolve tool hierarchy conflict in AGENTS_STARTUP.md

**Context**
A user pointed out a structural conflict in `AGENTS_STARTUP.md`. While PRs #9893 and #9900 successfully added the `ask_knowledge_base` tool to `AGENTS.md` (§2.1 Tool Hierarchy) and `AGENTS_STARTUP.md` (§3.4 "Ask the Expert" Protocol), they left legacy instructions untouched in earlier sections of `AGENTS_STARTUP.md`.

**The Problem**
Currently, `AGENTS_STARTUP.md` contains conflicting instructions for agents during session initialization:
- **§3.1 The Query Command** explicitly states: *"Your most important tool is the local AI knowledge base. To use it, call the `query_documents` tool."*
- **§3.3 The Two-Stage Query Protocol (Stage 1)** dictates: *"Use the `query_documents` tool to find relevant source code..."*
- Yet, **§3.4 The "Ask the Expert" Protocol** states: *"`ask_knowledge_base` ... is the #1 tool in the Anti-Hallucination hierarchy"*

This creates a split-brain scenario where agents reading the file sequentially are first told to use `query_documents` in-depth for conceptual understanding, which wastes context window and violates the newer Tool Hierarchy defined in `AGENTS.md`.

**The Architectural Reality**
`AGENTS_STARTUP.md` sections 3.1 and 3.3 are out of sync with `AGENTS.md` §2.1. The tool `ask_knowledge_base` acts as a zero-cost subagent that retrieves, reads, and synthesizes answers, making it strictly superior to `query_documents` for Stage 1 knowledge querying. `query_documents` should be restricted to file path discovery only.

**The Fix**
Refactor `AGENTS_STARTUP.md` to establish `ask_knowledge_base` as the undisputed primary tool for conceptual queries:
1. Update §3.1 to introduce `ask_knowledge_base` as the primary tool.
2. Update §3.3 (Stage 1) to mandate `ask_knowledge_base` for "how/why" queries, demoting `query_documents` to file discovery.
3. Consolidate §3.4 into the broader Knowledge Base strategy to remove the redundancy.

**Acceptance Criteria**
- [ ] §3.1 reflects `ask_knowledge_base` as the primary query tool.
- [ ] §3.3 specifies `ask_knowledge_base` for Stage 1 conceptual queries.
- [ ] The conflict where `query_documents` is recommended over `ask_knowledge_base` is completely eliminated from `AGENTS_STARTUP.md`.
- [ ] Documentation aligns perfectly with the Tool Hierarchy in `AGENTS.md` §2.1.

**Out of Scope**
- Modifying `AGENTS.md` (it is already correct).
- Altering the implementation of the MCP tools themselves.

Origin Session ID: 27016011-8ae9-48bb-af87-9479dd5b0fd0

## Timeline

- 2026-04-26T12:03:13Z @neo-gemini-pro added the `bug` label
- 2026-04-26T12:03:13Z @neo-gemini-pro added the `documentation` label
- 2026-04-26T12:03:13Z @neo-gemini-pro added the `ai` label
- 2026-04-26T12:03:19Z @neo-gemini-pro assigned to @neo-gemini-pro
### @neo-gemini-pro - 2026-04-26T12:05:29Z

Closing as superseded. The legacy documentation conflict has migrated to AGENTS.md following the recent dev branch consolidation. I am opening a new, accurately scoped ticket to address the conflict in its new location.

- 2026-04-26T12:05:30Z @neo-gemini-pro closed this issue

