googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

cloudstorage-list-buckets requires a non-empty description; Config.Initialize returns this error when cfg.Description is empty. The description is mandatory for all toolbox tools since it is exposed to the LLM client.

Source

Thrown at internal/tools/cloudstorage/cloudstoragelistbuckets/cloudstoragelistbuckets.go:79

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"`
	Project          *string                `yaml:"project,omitempty"`
	Prefix           *string                `yaml:"prefix,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)
	}

	maxResultsParam := parameters.NewIntParameter(maxResultsKey, "Maximum number of buckets to return per page. A value of 0 uses the API default (1000); negative values and values above 1000 are rejected.", parameters.WithIntDefault(0))
	pageTokenParam := parameters.NewStringParameter(pageTokenKey, "A previously-returned page token for retrieving the next page of results.", parameters.WithStringDefault(""))
	allParameters := parameters.Parameters{}
	if cfg.Project == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(projectKey, "Project ID to list buckets in. When empty, the source's configured project is used.", parameters.WithStringDefault("")))
	}
	if cfg.Prefix == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(prefixKey, "Filter results to buckets whose names begin with this prefix.", parameters.WithStringDefault("")))
	}
	allParameters = append(allParameters, maxResultsParam, pageTokenParam)

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

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a `description` field to the tool config.
2. Ensure template substitution yields a non-empty string.
3. Validate configs before server start.

Example fix

# before
list_buckets:
  kind: cloudstorage-list-buckets
  source: my-gcs
# after
list_buckets:
  kind: cloudstorage-list-buckets
  source: my-gcs
  description: Lists Cloud Storage buckets in the configured project.

if strings.TrimSpace(cfg.Description) == "" {
    return errors.New("description is required for tool " + cfg.Name)
}

When it happens

Trigger: Initializing a cloudstorage-list-buckets tool with `description` omitted or set to "".

Common situations: Minimal YAML configs missing the field; empty value after templating; older config formats predating stricter validation.

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
• description is required for tool %q
• bucket cannot be empty for tool %q
• bucket cannot be empty for tool %q

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