googleapis/mcp-toolbox · error

tool does not exist: %s

Error message

tool does not exist: %s

What it means

Toolset.Initialize resolves each configured tool name against the map of registered tools. If a listed tool name does not exist in toolsMap, Initialize returns this error. The toolset references a tool that was never defined or registered.

Source

Thrown at internal/tools/toolsets.go:101

func (t ToolsetConfig) Initialize(serverVersion string, toolsMap map[string]Tool) (Toolset, error) {
	// finish toolset setup
	// Check each declared tool name exists
	toolset := Toolset{
		ToolsetConfig: t,
		Tools:         make([]*Tool, 0, len(t.ToolNames)),
		Manifest: ToolsetManifest{
			ServerVersion: serverVersion,
		},
		toolNameSet: make(map[string]struct{}, len(t.ToolNames)),
	}
	if !IsValidName(toolset.Name) {
		return toolset, fmt.Errorf("invalid toolset name: %s", toolset.Name)
	}
	for _, toolName := range t.ToolNames {
		tool, ok := toolsMap[toolName]
		if !ok {
			return toolset, fmt.Errorf("tool does not exist: %s", toolName)
		}
		toolset.Tools = append(toolset.Tools, &tool)
		toolset.toolNameSet[toolName] = struct{}{}
	}
	return toolset, nil
}

var validName = regexp.MustCompile(`^[a-zA-Z0-9_-]*$`)

func IsValidName(s string) bool {
	return validName.MatchString(s)
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Make the toolset's tool entry exactly match a defined tool key in the tools section
2. Fix typos in the tool name list
3. Re-add or rename the missing tool, or remove it from the toolset
4. Confirm the binary includes the package that registers the referenced tool

Example fix

// before (tools.yaml)
toolsets:
  my_toolset:
    - run_queery
// after
toolsets:
  my_toolset:
    - run_query

definedTools := map[string]bool{"run_query": true} // keys of tools: in config
for _, name := range toolset.ToolNames {
    if !definedTools[name] {
        return fmt.Errorf("toolset lists unknown tool %q", name)
    }
}

ts, err := t.Initialize(ctx)
if err != nil {
    if strings.Contains(err.Error(), "tool does not exist") {
        log.Printf("add or fix the tool entry: %v", err)
    }
    return err
}

When it happens

Trigger: Calling Initialize with a Toolset whose ToolNames contains a name absent from toolsMap — the toolset lists a tool that isn't defined in the tools section or wasn't registered in the binary.

Common situations: Typo in a tool name inside the toolset list; tool defined under a different key than referenced; tool removed/renamed while toolsets still reference the old name; custom binary missing the package registering the tool.

Related errors

• tool %q not found
• toolset %q not found
• unable to retrieve %s source for tool %q
• failed to initialize resources: %w
• unable to retrieve source for tool %s

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