googleapis/mcp-toolbox · error

tool %q not found

Error message

tool %q not found

What it means

After initializing resources, runInvoke looks up the requested tool by name in the PrimitiveManager. If no tool with that name is registered, the command fails with this error. It means the first positional argument did not match any tool defined in the loaded config(s).

Source

Thrown at cmd/internal/invoke/command.go:81

	if err != nil {
		return err
	}

	// Initialize Resources
	sourcesMap, authServicesMap, embeddingModelsMap, toolsMap, promptsMap, groupsMap, err := server.InitializeConfigs(ctx, opts.Cfg)
	if err != nil {
		errMsg := fmt.Errorf("failed to initialize resources: %w", err)
		opts.Logger.ErrorContext(ctx, errMsg.Error())
		return errMsg
	}

	primitiveMgr := primitives.NewPrimitiveManager(sourcesMap, authServicesMap, embeddingModelsMap, toolsMap, promptsMap, groupsMap)

	// Execute Tool
	toolName := args[0]
	tool, ok := primitiveMgr.GetTool(toolName)
	if !ok {
		errMsg := fmt.Errorf("tool %q not found", toolName)
		opts.Logger.ErrorContext(ctx, errMsg.Error())
		return errMsg
	}

	srcName := tool.GetSourceName()
	var src sources.Source
	if srcName != "" {
		src, ok = primitiveMgr.GetSource(srcName)
		if !ok {
			errMsg := fmt.Errorf("unable to retrieve source for tool %s", toolName)
			opts.Logger.ErrorContext(ctx, errMsg.Error())
			return errMsg
		}
	}

	err = tool.ValidateSource(src)
	if err != nil {
		opts.Logger.ErrorContext(ctx, err.Error())

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Run `toolbox tools list` (or start the server and curl /api/tools) to see the exact registered tool names and copy one verbatim
2. Check that --tools-file / --prebuilt flags point to the config actually containing the tool
3. Verify the tool name spelling and casing (names are case-sensitive)
4. After a toolbox upgrade, regenerate or update the tools file to the new schema/tool names

Example fix

// before
toolbox invoke --tools-file tools.yaml list_users  # tool is actually named list-users
toolbox invoke list_users
// error: tool "list_users" not found
// after
toolbox invoke list-users

out, _ := exec.Command("toolbox", "tools", "list", "--tools-file", cfgPath).Output()
if !strings.Contains(string(out), toolName) {
    return fmt.Errorf("tool %q is not registered in %s", toolName, cfgPath)
}

if err := runInvoke(ctx, opts); err != nil {
    if strings.Contains(err.Error(), "not found") && strings.Contains(err.Error(), "tool") {
        return fmt.Errorf("unknown tool: %w; run 'toolbox tools list' for valid names", err)
    }
    return err
}

When it happens

Trigger: Running `toolbox invoke <name>` where <name> is absent from the tools file and prebuilt configs: a typo, a tool defined under a different kind, the wrong --tools-file/--prebuilt flag, or the tool was removed/renamed in a newer config version.

Common situations: Typos in the tool name, invoking a prebuilt tool whose config wasn't selected via --prebuilt, renamed tools after upgrading toolbox, using the service/group name instead of the tool name.

Related errors

• failed to initialize resources: %w
• unable to retrieve source for tool %s
• tool does not exist: %s
• error generating script content for %s: %w
• error writing script %s: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/ce6572d5e8a898d4. Report an issue: GitHub.