googleapis/mcp-toolbox · error

description is required for tool %q

Error message

description is required for tool %q

What it means

Initialize() for the arcadedb-execute-cypher tool requires a non-empty description, which the LLM uses to select the tool. An empty cfg.Description aborts tool construction with this error naming the tool.

Source

Thrown at internal/tools/arcadedb/arcadedbexecutecypher/arcadedbexecutecypher.go:66

}

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

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

	cypherParameter := parameters.NewStringParameter("cypher", "The cypher to execute.")
	queryParamsParameter := parameters.NewMapParameter(
		"params",
		"Optional query parameters to use with the cypher statement.",
		"",
		parameters.WithMapDefault(map[string]any{}),
	)
	dryRunParameter := parameters.NewBooleanParameter(
		"dry_run",
		"If set to true, the query will be validated and information about the execution "+
			"will be returned without running the query. Defaults to false.",
		parameters.WithBooleanDefault(false),
	)
	params := parameters.Parameters{cypherParameter, queryParamsParameter, dryRunParameter}

	allParameters, paramManifest, err := parameters.ProcessParameters(nil, params)

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Add a description field describing what the cypher execution tool does.
2. Fix interpolation so the description resolves to non-empty text.
3. Re-run the server after adding it — the error occurs only at config load, not per-request.

Example fix

// before
tools:
  run-cypher:
    kind: arcadedb-execute-cypher
    source: my-arcadedb
// after
tools:
  run-cypher:
    kind: arcadedb-execute-cypher
    source: my-arcadedb
    description: Execute a Cypher query against the ArcadeDB database.

if cfg.Description == "" {
    return errors.New("arcadedb-execute-cypher requires a non-empty description")
}
tool, err := cfg.Initialize(ctx)

tool, err := cfg.Initialize(ctx)
if err != nil {
    if strings.Contains(err.Error(), "description is required") {
        // supply a description and re-initialize
    }
    return err
}

When it happens

Trigger: Defining an arcadedb-execute-cypher tool without a description field (or empty string) and initializing it at server startup.

Common situations: Omitting description when hand-writing tools.yaml; environment-variable interpolation yielding empty; copied tool blocks stripped down too far.

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
• `introspectionEndpoint` is not allowed when `mcpEnabled` is
• `introspectionMethod` is not allowed when `mcpEnabled` is fa

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