googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

This error is thrown by the cassandracql tool's Config.Initialize when the tool config has an empty Description. Every MCP tool requires a description for the LLM-facing manifest, so initialization aborts and the tool is not registered.

Source

Thrown at internal/tools/cassandra/cassandracql/cassandracql.go:71

	Type               string                 `yaml:"type" validate:"required"`
	Source             string                 `yaml:"source" validate:"required"`
	Statement          string                 `yaml:"statement" validate:"required"`
	Parameters         parameters.Parameters  `yaml:"parameters"`
	TemplateParameters parameters.Parameters  `yaml:"templateParameters"`
	Annotations        *tools.ToolAnnotations `yaml:"annotations,omitempty"`
}

var _ tools.ToolConfig = Config{}

// ToolConfigType implements tools.ToolConfig.
func (c Config) ToolConfigType() string {
	return resourceType
}

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

	allParameters, paramManifest, err := parameters.ProcessParameters(c.TemplateParameters, c.Parameters)
	if err != nil {
		return nil, err
	}

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

var _ tools.Tool = Tool{}

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a non-empty description field to the cassandra-cql tool definition in tools.yaml
2. Check that env-var/template substitution for description yields a non-empty string
3. Fix YAML indentation so description is nested under the tool
4. Restart the server and confirm the tool initializes

Example fix

// before (tools.yaml)
tools:
  cql-query:
    kind: cassandra-cql
    source: my-cassandra
    statement: SELECT * FROM keyspace.table
// after
tools:
  cql-query:
    kind: cassandra-cql
    source: my-cassandra
    description: Executes a CQL statement against the Cassandra cluster.
    statement: SELECT * FROM keyspace.table

// Validate before building the tool
cfg := cassandracql.Config{Name: "cql-query", Source: "my-cassandra"}
if strings.TrimSpace(cfg.Description) == "" {
    return fmt.Errorf("tool %q requires a non-empty description", cfg.Name)
}
// Or check the YAML node: tools["cql-query"].description must exist and be non-empty

func hasDescription(name, desc string) bool {
    return strings.TrimSpace(desc) != ""
}

When it happens

Trigger: Calling Initialize on a cassandracql Config with Description == "" — e.g. a tools.yaml entry of kind cassandra-cql missing the description field or with an empty value after variable expansion.

Common situations: Authoring tools.yaml by hand and omitting description; ${VAR} placeholders resolving to empty; YAML mis-nesting so description lands in the wrong scope; minimal examples copied without the field.

Related errors

• description is required for tool %q
• invalid source for %q tool: source %q is not a compatible ty
• description is required for tool %q
• description is required for tool %q
• description is required for tool %q

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