vxcontrol/pentagi · error

unknown tool: %s

Error message

unknown tool: %s

What it means

The guide tool dispatcher received a tool name that is neither search_guide nor store_guide. The name must exactly match one of the registered switch cases; anything else falls to the default branch and errors out.

Source

Thrown at backend/pkg/tools/guide.go:391

			}
			_, _ = g.vslp.PutLog(
				ctx,
				agentCtx.ParentAgentType,
				agentCtx.CurrentAgentType,
				filtersData,
				action.Question,
				database.VecstoreActionTypeStore,
				guide,
				g.taskID,
				g.subtaskID,
			)
		}

		return "guide stored successfully", nil

	default:
		logger.Error("unknown tool")
		return "", fmt.Errorf("unknown tool: %s", name)
	}
}

func (g *guide) IsAvailable() bool {
	return g.store != nil
}

View on GitHub (pinned to ea665308ba)

Solutions

1. Check the log field 'tool' for the exact unknown name and compare against SearchGuideToolName/StoreGuideToolName constants.
2. Fix the tool-name registration so guide.Handle only receives names it implements.
3. If a new tool is intended, add a case to the switch in guide.Handle.
4. Verify the agent's system prompt/tool list doesn't advertise nonexistent guide tools.
5. Regenerate the flow if a single model hallucination caused it.

const (
    SearchGuideToolName = "search_guide"
    StoreGuideToolName  = "store_guide"
)
func isGuideTool(name string) bool {
    return name == SearchGuideToolName || name == StoreGuideToolName
}

func knownGuideTool(name string) (string, bool) {
    switch name {
    case SearchGuideToolName, StoreGuideToolName:
        return name, true
    }
    return "", false
}

out, err := tool.Handle(ctx, name, args)
if err != nil && strings.HasPrefix(err.Error(), "unknown tool") {
    log.Printf("agent called unregistered tool %q; falling back", name)
    return fallbackTool.Handle(ctx, name, args)
}

When it happens

Trigger: Agent calls a guide-family tool with a misspelled or nonexistent name; tool registry wires a wrong name string into guide.Handle; a new guide tool was added to the schema but not to the switch.

Common situations: LLM hallucinating tool names; case-sensitivity mismatch (e.g. 'Search_Guide'); adding a tool to the GraphQL/agent schema without updating guide.go; copy-pasted registration passing the wrong ToolName constant.

Related errors

• unknown tool: %s
• unknown tool: %s
• failed to switch provider: %w
• failed to set provider: %w
• failed to perform agent chain for subtask %d: %w

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/235c896d7b82c0e6. Report an issue: GitHub.