googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

Firestore delete-documents tool configuration validation: Config.Initialize rejects the tool when its description is empty. The description is mandatory for the LLM-facing tool manifest, and the error names the offending tool.

Source

Thrown at internal/tools/firestore/firestoredeletedocuments/firestoredeletedocuments.go:69

}

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)
	}

	documentPathsParameter := parameters.NewArrayParameter(documentPathsKey, "Array of relative document paths to delete from Firestore (e.g., 'users/userId' or 'users/userId/posts/postId'). Note: These are relative paths, NOT absolute paths like 'projects/{project_id}/databases/{database_id}/documents/...'", parameters.NewStringParameter("item", "Relative document path"))
	params := parameters.Parameters{documentPathsParameter}

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

// validate interface
var _ tools.Tool = Tool{}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a non-empty 'description' field to the tool config.
2. Ensure env substitutions for description produce a non-empty value.
3. Restart the toolbox after updating the config.

Example fix

// before
  delete_docs:
    kind: firestore-delete-documents
    source: my-firestore
// after
  delete_docs:
    kind: firestore-delete-documents
    source: my-firestore
    description: Deletes documents from Firestore by relative document paths.

# Pre-flight validation
if not tools_cfg['delete_docs'].get('description'):
    raise SystemExit("delete_docs: description is required")

if err := cfg.Initialize(ctx); err != nil {
    if strings.Contains(err.Error(), "description is required") {
        err = fmt.Errorf("tools.yaml fix needed: %w", err)
    }
    return err
}

When it happens

Trigger: Declaring a firestore-delete-documents tool without a non-empty 'description' field in the tools YAML and initializing the config.

Common situations: Hand-written configs missing description; templated or env-substituted descriptions resolving to empty string; bulk-generated configs omitting required fields.

Related errors

• description is required for tool %q
• HTTP error! status: ${response.status}
• no document found
• doc %d: unexpected non-string key in input: %v
• doc %d: invalid config format at key %q: %w

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