tool discovery is enabled but neither 'use_bm25' nor 'use_re

Error message

tool discovery is enabled but neither 'use_bm25' nor 'use_regex' is set to true in the configuration

What it means

MCP tool discovery registers hidden tools and exposes them through search backends. picoclaw supports two search methods, BM25 and regex, and this is a fail-fast config check in ensureMCPInitialized: when tools.mcp.discovery.enabled=true but both use_bm25 and use_regex are false, there is no search backend to surface deferred tools, so initialization aborts with this error.

Source

Thrown at pkg/agent/agent_mcp.go:222

				)
			}
		}
		logger.InfoCF("agent", "MCP tools registered successfully",
			map[string]any{
				"server_count":        len(servers),
				"unique_tools":        uniqueTools,
				"total_registrations": totalRegistrations,
				"agent_count":         agentCount,
			})

		// Initializes Discovery Tools only if enabled by configuration
		if al.cfg.Tools.MCP.Enabled && al.cfg.Tools.MCP.Discovery.Enabled {
			useBM25 := al.cfg.Tools.MCP.Discovery.UseBM25
			useRegex := al.cfg.Tools.MCP.Discovery.UseRegex

			// Fail fast: If discovery is enabled but no search method is turned on
			if !useBM25 && !useRegex {
				al.mcp.setInitErr(fmt.Errorf(
					"tool discovery is enabled but neither 'use_bm25' nor 'use_regex' is set to true in the configuration",
				))
				if closeErr := mcpManager.Close(); closeErr != nil {
					logger.ErrorCF("agent", "Failed to close MCP manager",
						map[string]any{
							"error": closeErr.Error(),
						})
				}
				return
			}

			ttl := al.cfg.Tools.MCP.Discovery.TTL
			if ttl <= 0 {
				ttl = 5 // Default value
			}

			maxSearchResults := al.cfg.Tools.MCP.Discovery.MaxSearchResults
			if maxSearchResults <= 0 {

View on GitHub (pinned to 49183d7e8d)

Solutions

Set at least one of use_bm25 / use_regex to true in tools.mcp.discovery (regex is the cheaper option)
If you do not want deferred tools at all, set discovery.enabled=false instead of disabling both engines
Check env overrides (PICOCLAW_TOOLS_DISCOVERY_USE_BM25 / _USE_REGEX) that may silently flip the flags
Restart picoclaw after the config change

Example fix

// config — before
"discovery": { "enabled": true, "use_bm25": false, "use_regex": false }

// after
"discovery": { "enabled": true, "use_bm25": false, "use_regex": true }

Defensive patterns

Strategy: validation

Validate before calling

if cfg.Tools.MCP.Enabled && cfg.Tools.MCP.Discovery.Enabled {
    if !cfg.Tools.MCP.Discovery.UseBM25 && !cfg.Tools.MCP.Discovery.UseRegex {
        return fmt.Errorf("tools.mcp.discovery: enable use_bm25 or use_regex (regex is cheaper)")
    }
}

Prevention

Add a config lint step that checks discovery engines whenever discovery.enabled is true
Watch env overrides PICOCLAW_TOOLS_DISCOVERY_USE_BM25/_USE_REGEX — they can flip flags silently
If neither engine is wanted, set discovery.enabled=false instead of zeroing both flags

When it happens

Trigger: Setting tools.mcp.discovery.enabled=true together with use_bm25=false and use_regex=false (both default-overridden to false). Note the shipped default is use_bm25=true (pkg/config/defaults.go:436), so this only happens when BM25 is explicitly disabled without enabling regex.

Common situations: Copying a minimal discovery block from docs and zeroing both flags to 'save resources'; toggling use_bm25 off for CPU reasons and forgetting to enable regex; env overrides PICOCLAW_TOOLS_DISCOVERY_USE_BM25=false without PICOCLAW_TOOLS_DISCOVERY_USE_REGEX=true.

Related errors

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/ba69b2d81cab4c49. Report an issue: GitHub.