What causes "description is required for tool %q" in googleapis/mcp-toolbox?

Add a non-empty 'description' field to the cloudstorage-list-objects tool config in tools.yaml

description is required for tool %q

Error message

description is required for tool %q

What it means

This error is thrown by the cloudstorage-list-objects tool's Config.Initialize when the tool's YAML config has no description set. MCP Toolbox requires every tool to have a non-empty description because it is exposed to the LLM via the MCP manifest to explain the tool's purpose. Initialize refuses to construct the tool without one.

Source

Thrown at internal/tools/cloudstorage/cloudstoragelistobjects/cloudstoragelistobjects.go:81

	tools.ConfigBase `yaml:",inline"`
	Type             string                 `yaml:"type" validate:"required"`
	Source           string                 `yaml:"source" validate:"required"`
	Annotations      *tools.ToolAnnotations `yaml:"annotations,omitempty"`
	Bucket           *string                `yaml:"bucket,omitempty"`
	Prefix           *string                `yaml:"prefix,omitempty"`
	Delimiter        *string                `yaml:"delimiter,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)
	}
	if cfg.Bucket != nil && *cfg.Bucket == "" {
		return nil, fmt.Errorf("bucket cannot be empty for tool %q", cfg.Name)
	}

	maxResultsParam := parameters.NewIntParameter(maxResultsKey, "Maximum number of objects 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.Bucket == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(bucketKey, "Name of the Cloud Storage bucket to list objects from."))
	}
	if cfg.Prefix == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(prefixKey, "Filter results to objects whose names begin with this prefix.", parameters.WithStringDefault("")))
	}
	if cfg.Delimiter == nil {
		allParameters = append(allParameters, parameters.NewStringParameter(delimiterKey, "Delimiter used to group object names (typically '/'). When set, common prefixes are returned as 'prefixes'.", parameters.WithStringDefault("")))
	}
	allParameters = append(allParameters, maxResultsParam, pageTokenParam)

View on GitHub (pinned to 8cc6e09de2)

Solutions

Add a non-empty 'description' field to the cloudstorage-list-objects tool config in tools.yaml
Verify the rendered YAML actually contains the description (check template/variable interpolation)
Restart/reload the toolbox server so the config is re-validated

Example fix

// before
sources:
  my-gcs:
    kind: cloud-storage
tools:
  list-objects:
    kind: cloudstorage-list-objects
    source: my-gcs
// after
sources:
  my-gcs:
    kind: cloud-storage
tools:
  list-objects:
    kind: cloudstorage-list-objects
    source: my-gcs
    description: List objects in a Cloud Storage bucket with pagination

Defensive patterns

Strategy: validation

Validate before calling

func validateListObjectsConfig(name, description string) error {
    if description == "" {
        return fmt.Errorf("tool %q: description is required before loading tools.yaml", name)
    }
    return nil
}

Prevention

Always include a description in every tool definition in tools.yaml
Add a config linter/CI check that asserts description is non-empty for each tool
Use schema validation for tools.yaml before starting the server

When it happens

Trigger: A tools.yaml defines a cloudstorage-list-objects tool whose config omits the 'description' field or sets it to an empty string; Initialize is called during server startup or config loading.

Common situations: Hand-editing tools.yaml and forgetting the description; copying a minimal example that omitted it; templating tools where an empty variable was interpolated into the description field.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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