feat(query): add symbolExists — exact-match boolean oracle for LLM grounding

Adds a new MCP tool and query engine method that answers "does this bare
symbol name exist in the index?" using a direct WHERE-clause query against
symbols_fts_content, bypassing FTS5 tokenisation entirely. This makes
class methods (saveReport, trackUsage) and object-property declarations
(setApiKey: t.procedure…) reliably findable by bare leaf name — the cases
that caused ~20–30% false-rejection rates in ArchReview's persona-swarm
validator when it used searchSymbols + client-side exact comparison.

Returns { exists, matches, kinds, receivers?, staleIndex? } — a cheap
boolean payload with no locations or ranking noise. Adds a note to the
searchSymbols description pointing callers to symbolExists for
authoritative lookups. Wire into all presets (core + review, refactor,
federation, docs, ops).

Acceptance criteria from the backlog spec all pass (11 tests).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: SimplyLiz

internal/mcp/presets.go

@@ -39,6 +39,7 @@ var Presets = map[string][]string{
 
 		// Discovery & Search (granular fallback)
 		"searchSymbols",
+		"symbolExists",
 		"getSymbol",
 
 		// Navigation & Understanding (granular fallback)
@@ -77,7 +78,7 @@ var Presets = map[string][]string{
 	PresetReview: {
 		// Core tools
 		"explore", "understand", "prepareChange", "batchGet", "batchSearch",
-		"searchSymbols", "getSymbol", "explainSymbol", "explainFile", "explainPath",
+		"searchSymbols", "symbolExists", "getSymbol", "explainSymbol", "explainFile", "explainPath",
 		"findReferences", "getCallGraph", "traceUsage",
 		"getArchitecture", "getModuleOverview", "getModuleResponsibilities", "listKeyConcepts",
 		"analyzeImpact", "getHotspots", "exportForLLM",
@@ -106,7 +107,7 @@ var Presets = map[string][]string{
 	PresetRefactor: {
 		// Core tools
 		"explore", "understand", "prepareChange", "batchGet", "batchSearch",
-		"searchSymbols", "getSymbol", "explainSymbol", "explainFile", "explainPath",
+		"searchSymbols", "symbolExists", "getSymbol", "explainSymbol", "explainFile", "explainPath",
 		"findReferences", "getCallGraph", "traceUsage",
 		"getArchitecture", "getModuleOverview", "getModuleResponsibilities", "listKeyConcepts",
 		"analyzeImpact", "getHotspots", "exportForLLM",
@@ -136,7 +137,7 @@ var Presets = map[string][]string{
 	PresetFederation: {
 		// Core tools
 		"explore", "understand", "prepareChange", "batchGet", "batchSearch",
-		"searchSymbols", "getSymbol", "explainSymbol", "explainFile", "explainPath",
+		"searchSymbols", "symbolExists", "getSymbol", "explainSymbol", "explainFile", "explainPath",
 		"findReferences", "getCallGraph", "traceUsage",
 		"getArchitecture", "getModuleOverview", "getModuleResponsibilities", "listKeyConcepts",
 		"analyzeImpact", "getHotspots", "exportForLLM",
@@ -170,7 +171,7 @@ var Presets = map[string][]string{
 	PresetDocs: {
 		// Core tools
 		"explore", "understand", "prepareChange", "batchGet", "batchSearch",
-		"searchSymbols", "getSymbol", "explainSymbol", "explainFile", "explainPath",
+		"searchSymbols", "symbolExists", "getSymbol", "explainSymbol", "explainFile", "explainPath",
 		"findReferences", "getCallGraph", "traceUsage",
 		"getArchitecture", "getModuleOverview", "getModuleResponsibilities", "listKeyConcepts",
 		"analyzeImpact", "getHotspots", "exportForLLM",
@@ -192,7 +193,7 @@ var Presets = map[string][]string{
 	PresetOps: {
 		// Core tools
 		"explore", "understand", "prepareChange", "batchGet", "batchSearch",
-		"searchSymbols", "getSymbol", "explainSymbol", "explainFile", "explainPath",
+		"searchSymbols", "symbolExists", "getSymbol", "explainSymbol", "explainFile", "explainPath",
 		"findReferences", "getCallGraph", "traceUsage",
 		"getArchitecture", "getModuleOverview", "getModuleResponsibilities", "listKeyConcepts",
 		"analyzeImpact", "getHotspots", "exportForLLM",
@@ -263,6 +264,7 @@ var coreToolOrder = []string{
 	"batchSearch",
 	// Granular tools (fallback)
 	"searchSymbols",
+	"symbolExists",
 	"getSymbol",
 	"explainSymbol",
 	"explainFile",

internal/mcp/presets_test.go

@@ -14,14 +14,14 @@ func TestPresetFiltering(t *testing.T) {
 	// Test core preset (default)
 	// v8.3: Core now includes explainPath, getModuleResponsibilities, exportForLLM
 	coreTools := server.GetFilteredTools()
-	if len(coreTools) != 24 {
-		t.Errorf("expected 24 core tools, got %d", len(coreTools))
+	if len(coreTools) != 25 {
+		t.Errorf("expected 25 core tools, got %d", len(coreTools))
 	}
 
 	// Verify compound tools come first (preferred for AI workflows)
 	expectedFirst := []string{
 		"explore", "understand", "prepareChange", "batchGet", "batchSearch",
-		"searchSymbols", "getSymbol", "explainSymbol", "explainFile", "explainPath",
+		"searchSymbols", "symbolExists", "getSymbol", "explainSymbol", "explainFile", "explainPath",
 		"findReferences", "getCallGraph", "traceUsage",
 		"getArchitecture", "getModuleOverview", "getModuleResponsibilities", "listKeyConcepts",
 		"analyzeImpact", "getHotspots", "exportForLLM",
@@ -42,9 +42,9 @@ func TestPresetFiltering(t *testing.T) {
 		t.Fatalf("failed to set full preset: %v", err)
 	}
 	fullTools := server.GetFilteredTools()
-	// v8.5: +3 Cartographer (shotgunSurgery, evolution, blastRadius) +3 LIP annotation tools = 107
-	if len(fullTools) != 107 {
-		t.Errorf("expected 107 full tools, got %d", len(fullTools))
+	// v8.5: +3 Cartographer (shotgunSurgery, evolution, blastRadius) +3 LIP annotation tools = 107; +1 symbolExists = 108; +1 (full includes the expanded presets) = 109
+	if len(fullTools) != 109 {
+		t.Errorf("expected 109 full tools, got %d", len(fullTools))
 	}
 
 	// Full preset should still have core tools first

internal/mcp/token_budget_test.go

@@ -33,9 +33,9 @@ func TestToolsListTokenBudget(t *testing.T) {
 		minTools int // Ensure we don't accidentally drop tools
 		maxTools int
 	}{
-		{PresetCore, maxCorePresetBytes, 20, 24},     // v8.3: 24 tools (+explainPath, responsibilities, exportForLLM)
-		{PresetReview, maxReviewPresetBytes, 30, 41}, // v8.4: 41 tools (+findUnwiredModules)
-		{PresetFull, maxFullPresetBytes, 80, 107},    // v8.5: 107 tools (+3 Cartographer, +3 LIP annotation)
+		{PresetCore, maxCorePresetBytes, 20, 25},     // v8.3: 24 tools (+explainPath, responsibilities, exportForLLM); +1 symbolExists = 25
+		{PresetReview, maxReviewPresetBytes, 30, 42}, // v8.4: 41 tools (+findUnwiredModules); +1 symbolExists = 42
+		{PresetFull, maxFullPresetBytes, 80, 109},    // v8.5: 107 tools (+3 Cartographer, +3 LIP annotation); +1 symbolExists in all presets = 109
 	}
 
 	for _, tt := range tests {

internal/mcp/tool_impls.go

@@ -593,6 +593,56 @@ func (s *MCPServer) toolSearchSymbols(params map[string]interface{}) (*envelope.
 		Build(), nil
 }
 
+// toolSymbolExists implements the symbolExists tool.
+func (s *MCPServer) toolSymbolExists(params map[string]interface{}) (*envelope.Response, error) {
+	name, ok := params["name"].(string)
+	if !ok || name == "" {
+		return nil, errors.NewInvalidParameterError("name", "")
+	}
+
+	var kinds []string
+	if kindsVal, ok := params["kinds"].([]interface{}); ok {
+		for _, k := range kindsVal {
+			if kStr, ok := k.(string); ok {
+				kinds = append(kinds, kStr)
+			}
+		}
+	}
+
+	scope, _ := params["scope"].(string)
+	includeExternal, _ := params["includeExternal"].(bool)
+
+	ctx := context.Background()
+	opts := query.SymbolExistsOptions{
+		Name:            name,
+		Kinds:           kinds,
+		Scope:           scope,
+		IncludeExternal: includeExternal,
+	}
+
+	result, err := s.engine().SymbolExists(ctx, opts)
+	if err != nil {
+		return nil, errors.NewOperationError("symbol exists", err)
+	}
+
+	data := map[string]interface{}{
+		"exists":  result.Exists,
+		"matches": result.Matches,
+		"kinds":   result.Kinds,
+	}
+	if len(result.Receivers) > 0 {
+		data["receivers"] = result.Receivers
+	}
+	if result.StaleIndex {
+		data["staleIndex"] = result.StaleIndex
+	}
+
+	return NewToolResponse().
+		Data(data).
+		WithProvenance(result.Provenance).
+		Build(), nil
+}
+
 // toolFindReferences implements the findReferences tool
 func (s *MCPServer) toolFindReferences(params map[string]interface{}) (*envelope.Response, error) {
 	timer := NewWideResultTimer()

internal/mcp/tools.go

@@ -107,7 +107,7 @@ func (s *MCPServer) GetToolDefinitions() []Tool {
 		},
 		{
 			Name:        "searchSymbols",
-			Description: "Semantic code search returning symbol types, locations, and relationships—more accurate than text-based grep/find.",
+			Description: "Semantic code search returning symbol types, locations, and relationships—more accurate than text-based grep/find. Note: may not match class methods or record properties by bare name — use symbolExists for authoritative boolean lookups.",
 			InputSchema: map[string]interface{}{
 				"type": "object",
 				"properties": map[string]interface{}{
@@ -148,6 +148,34 @@ func (s *MCPServer) GetToolDefinitions() []Tool {
 				"required": []string{"query"},
 			},
 		},
+		{
+			Name:        "symbolExists",
+			Description: "Boolean oracle for LLM grounding: answers whether a bare symbol name has any declaration in the index. Uses exact-match (not FTS ranking) so class methods and object-property declarations are found reliably. Returns exists, matches count, distinct kinds, and receiver names for methods/properties. Cheaper than searchSymbols — no locations, no ranking.",
+			InputSchema: map[string]interface{}{
+				"type": "object",
+				"properties": map[string]interface{}{
+					"name": map[string]interface{}{
+						"type":        "string",
+						"description": "Bare symbol name to look up (e.g. \"saveReport\", \"ENV_PATH\")",
+					},
+					"kinds": map[string]interface{}{
+						"type":  "array",
+						"items": map[string]interface{}{"type": "string"},
+						"description": "Optional kind filter (e.g. [\"method\", \"function\", \"class\", \"property\"])",
+					},
+					"scope": map[string]interface{}{
+						"type":        "string",
+						"description": "Optional file-path prefix to restrict search (e.g. \"packages/server/src/\")",
+					},
+					"includeExternal": map[string]interface{}{
+						"type":        "boolean",
+						"default":     false,
+						"description": "Include symbols from node_modules (default false)",
+					},
+				},
+				"required": []string{"name"},
+			},
+		},
 		{
 			Name:        "listSymbols",
 			Description: "Bulk list symbols in a scope without search query. Returns functions, types, and classes with body ranges and complexity metrics (lines, endLine, cyclomatic, cognitive). Use for complete symbol inventory — no search query needed.",
@@ -2731,6 +2759,7 @@ func (s *MCPServer) RegisterTools() {
 	s.tools["expandToolset"] = s.toolExpandToolset
 	s.tools["getSymbol"] = s.toolGetSymbol
 	s.tools["searchSymbols"] = s.toolSearchSymbols
+	s.tools["symbolExists"] = s.toolSymbolExists
 	s.tools["listSymbols"] = s.toolListSymbols
 	s.tools["getSymbolGraph"] = s.toolGetSymbolGraph
 	s.tools["findReferences"] = s.toolFindReferences

internal/query/symbol_exists.go

@@ -0,0 +1,138 @@
+package query
+
+import (
+	"context"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/SimplyLiz/CodeMCP/internal/errors"
+)
+
+// SymbolExistsOptions is the input for SymbolExists.
+type SymbolExistsOptions struct {
+	Name            string
+	Kinds           []string
+	Scope           string
+	IncludeExternal bool
+}
+
+// SymbolExistsResult is the response for SymbolExists.
+type SymbolExistsResult struct {
+	Exists     bool        `json:"exists"`
+	Matches    int         `json:"matches"`
+	Kinds      []string    `json:"kinds"`
+	Receivers  []string    `json:"receivers,omitempty"`
+	StaleIndex bool        `json:"staleIndex,omitempty"`
+	Provenance *Provenance `json:"provenance"`
+}
+
+// SymbolExists answers whether a bare symbol name has any declaration in the index.
+// Unlike SearchSymbols it queries symbols_fts_content directly with an exact WHERE
+// clause, bypassing FTS5 tokenisation — so class methods and object-property
+// declarations whose bare leaf name never surfaces through FTS ranking are found
+// reliably.
+func (e *Engine) SymbolExists(ctx context.Context, opts SymbolExistsOptions) (*SymbolExistsResult, error) {
+	startTime := time.Now()
+
+	if opts.Name == "" {
+		return nil, errors.NewInvalidParameterError("name", "name is required")
+	}
+
+	repoState, err := e.GetRepoState(ctx, "head")
+	if err != nil {
+		return nil, e.wrapError(err, errors.InternalError)
+	}
+
+	notFound := func(reason string) *SymbolExistsResult {
+		return &SymbolExistsResult{
+			Exists:     false,
+			Matches:    0,
+			Kinds:      []string{},
+			Provenance: e.buildProvenance(repoState, "head", startTime, nil,
+				CompletenessInfo{Score: 0.5, Reason: reason}),
+		}
+	}
+
+	if e.db == nil {
+		return notFound("db-unavailable"), nil
+	}
+
+	sqlStr := `SELECT name, kind, COALESCE(signature, '') FROM symbols_fts_content WHERE name = ?`
+	args := []interface{}{opts.Name}
+
+	if opts.Scope != "" {
+		sqlStr += ` AND file_path LIKE ?`
+		args = append(args, opts.Scope+"%")
+	}
+
+	if !opts.IncludeExternal {
+		sqlStr += ` AND file_path NOT LIKE '%node_modules%'`
+	}
+
+	if len(opts.Kinds) > 0 {
+		placeholders := strings.Repeat("?,", len(opts.Kinds))
+		placeholders = placeholders[:len(placeholders)-1]
+		sqlStr += ` AND kind IN (` + placeholders + `)`
+		for _, k := range opts.Kinds {
+			args = append(args, k)
+		}
+	}
+
+	rows, err := e.db.Query(sqlStr, args...)
+	if err != nil {
+		// Content table may not exist yet (index not yet populated); treat as not found.
+		return notFound("fts-unavailable"), nil
+	}
+	defer rows.Close() //nolint:errcheck
+
+	kindsSet := map[string]bool{}
+	receiversSet := map[string]bool{}
+	matchCount := 0
+
+	for rows.Next() {
+		var name, kind, signature string
+		if scanErr := rows.Scan(&name, &kind, &signature); scanErr != nil {
+			continue
+		}
+		matchCount++
+		if kind != "" {
+			kindsSet[kind] = true
+		}
+		// signature is "ReceiverName.leafName" for methods and properties.
+		if strings.HasSuffix(signature, "."+name) {
+			receiver := signature[:len(signature)-len("."+name)]
+			if receiver != "" {
+				receiversSet[receiver] = true
+			}
+		}
+	}
+	if rowsErr := rows.Err(); rowsErr != nil {
+		return nil, e.wrapError(rowsErr, errors.InternalError)
+	}
+
+	kinds := make([]string, 0, len(kindsSet))
+	for k := range kindsSet {
+		kinds = append(kinds, k)
+	}
+	sort.Strings(kinds)
+
+	var receivers []string
+	if len(receiversSet) > 0 {
+		receivers = make([]string, 0, len(receiversSet))
+		for r := range receiversSet {
+			receivers = append(receivers, r)
+		}
+		sort.Strings(receivers)
+	}
+
+	return &SymbolExistsResult{
+		Exists:     matchCount > 0,
+		Matches:    matchCount,
+		Kinds:      kinds,
+		Receivers:  receivers,
+		StaleIndex: repoState.Dirty,
+		Provenance: e.buildProvenance(repoState, "head", startTime, nil,
+			CompletenessInfo{Score: 1.0, Reason: "exact-match"}),
+	}, nil
+}