microsoft/semantic-kernel · error · InvalidOperationException

Function description is required. Please provide a descripti

Error message

Function description is required. Please provide a description for the function {this.FullyQualifiedName}.

What it means

Thrown by GeminiFunction.ToFunctionDeclaration when this.Description is null while serializing the function for the Gemini API. Gemini's FunctionDeclaration requires a non-empty description so the model understands what the function does; the connector refuses to send a descriptionless tool. The error names the offending function via FullyQualifiedName.

Source

Thrown at dotnet/src/Connectors/Connectors.Google/Models/Gemini/GeminiFunction.cs:163

                properties.Add(parameter.Name, parameter.Schema ?? GetDefaultSchemaForParameter(parameter));
                if (parameter.IsRequired)
                {
                    required.Add(parameter.Name);
                }
            }

            resultParameters = new Dictionary<string, object?>
            {
                { "type", "object" },
                { "required", required },
                { "properties", properties },
            };
        }

        return new GeminiTool.FunctionDeclaration
        {
            Name = this.FullyQualifiedName,
            Description = this.Description ?? throw new InvalidOperationException(
                $"Function description is required. Please provide a description for the function {this.FullyQualifiedName}."),
            Parameters = GeminiRequest.TransformToOpenApi3Schema(JsonSerializer.SerializeToElement(resultParameters)),
        };
    }

    /// <summary>Gets a <see cref="KernelJsonSchema"/> for a typeless parameter with the specified description, defaulting to typeof(string)</summary>
    private static KernelJsonSchema GetDefaultSchemaForParameter(GeminiFunctionParameter parameter)
    {
        // If there's a description, incorporate it.
        if (!string.IsNullOrWhiteSpace(parameter.Description))
        {
            return KernelJsonSchemaBuilder.Build(typeof(string), parameter.Description);
        }

        // Otherwise, we can use a cached schema for a string with no description.
        return s_stringNoDescriptionSchema;
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

Add a [Description("...")] attribute to every [KernelFunction] method exposed to Gemini.
Provide a description string when registering functions via KernelFunctionFactory.CreateFromMethod / CreateFromPrompt.
If building GeminiFunction manually, pass a non-null description in the constructor.

Example fix

// before
public class MyPlugin
{
    [KernelFunction]
    public string GetTime() => DateTime.Now.ToString();
}

// after
public class MyPlugin
{
    [KernelFunction]
    [Description("Returns the current date and time.")]
    public string GetTime() => DateTime.Now.ToString();
}

Defensive patterns

Strategy: validation

Validate before calling

static void EnsureDescriptions(IReadOnlyList<KernelFunctionMetadata> fns)
{
    foreach (var f in fns)
        if (string.IsNullOrWhiteSpace(f.Description))
            throw new InvalidOperationException($"Function {f.PluginName}.{f.Name} has no description.");
}

Type guard

static bool AllFunctionsDescribed(IEnumerable<KernelFunctionMetadata> fns)
    => fns.All(f => !string.IsNullOrWhiteSpace(f.Description));

Try / catch

try { await kernel.InvokePromptAsync(prompt, new(settings)); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Function description is required"))
{ logger.LogError(ex, "Add [Description] to the offending kernel function."); throw; }

Prevention

Add a [Description] attribute to every [KernelFunction] exposed to Gemini.
Provide descriptions when registering functions via KernelFunctionFactory.
Lint plugins at startup to assert all functions have descriptions.

When it happens

Trigger: Registering a kernel function (via method attribute, delegate, or KernelFunctionFactory) that has no KernelFunctionDescription.Description; e.g. a [KernelFunction] method without a [Description] and no description passed at registration, then exposing it to Gemini via tool-call behavior or auto-function importing.

Common situations: Adding a plugin from a class where the [KernelFunction] method lacks a [Description] attribute; creating KernelFunction from a delegate without a description argument; version changes that tightened description requirements.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/bda498fe736799ea. Report an issue: GitHub.