googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

Config.Initialize for the cloudmonitoring (promql query) tool requires cfg.Description to be non-empty because it populates the MCP tool manifest. An empty description fails initialization immediately with this error.

Source

Thrown at internal/tools/cloudmonitoring/cloudmonitoring.go:66

}

type Config struct {
	tools.ConfigBase `yaml:",inline"`
	Type             string                 `yaml:"type" validate:"required"`
	Source           string                 `yaml:"source" validate:"required"`
	Annotations      *tools.ToolAnnotations `yaml:"annotations,omitempty"`
}

// validate interface
var _ tools.ToolConfig = Config{}

func (cfg Config) ToolConfigType() string {
	return resourceType
}

func (cfg Config) Initialize(context.Context) (tools.Tool, error) {
	if cfg.Description == "" {
		return nil, fmt.Errorf("description is required for tool %q", cfg.Name)
	}

	// Define the parameters internally instead of from the config file.
	allParameters := parameters.Parameters{
		parameters.NewStringParameter("projectId", "The Id of the Google Cloud project.", parameters.WithStringRequired(true)),
		parameters.NewStringParameter("query", "The promql query to execute.", parameters.WithStringRequired(true)),
	}

	return Tool{
		BaseTool: tools.NewBaseTool(
			cfg,
			tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewReadOnlyAnnotations),
			tools.Manifest{Description: cfg.Description, Parameters: allParameters.Manifest(), AuthRequired: cfg.AuthRequired},
			allParameters,
		),
	}, nil
}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a non-empty `description:` to the cloud monitoring tool entry.
2. Confirm the description key is nested under the correct tool.
3. Re-initialize; the error's %q names the exact tool to fix.

Example fix

// before
  execute-promql:
    kind: cloud-monitoring-execute-promql
    source: my-monitoring-source
// after
  execute-promql:
    kind: cloud-monitoring-execute-promql
    source: my-monitoring-source
    description: Executes a PromQL query against Google Cloud Monitoring.

// Go: guard required fields before Initialize
if strings.TrimSpace(cfg.Description) == "" {
    return nil, fmt.Errorf("cloud monitoring tool %q needs a description", cfg.Name)
}

tool, err := cfg.Initialize(ctx)
if err != nil {
    log.Fatalf("tool init failed (check tools.yaml description field): %v", err)
}

When it happens

Trigger: A tools.yaml entry of kind cloud--monitoring (execute-promql) missing the `description` field or with an empty value.

Common situations: Hand-written minimal configs; template generators emitting blank descriptions; YAML indentation placing description outside the tool mapping so it unmarshals empty.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• description is required for tool %q
• description is required for tool %q
• doc %d: unexpected non-string key in input: %v
• doc %d: invalid config format at key %q: %w
• doc %d: invalid config format at key %q: expected nested for

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