What causes "OpenAPI tool '{spec.id}' requires a 'description'." in microsoft/semantic-kernel?

Add a concise, non-empty description to the openapi tool entry explaining what the API does.

microsoft/semantic-kernel · error · AgentInitializationException

OpenAPI tool '{spec.id}' requires a 'description'.

Error message

OpenAPI tool '{spec.id}' requires a 'description'.

What it means

Raised when an openapi tool spec has an id but no description. The Azure AI service requires a description for each tool to inform the model when to invoke it.

Source

Thrown at python/semantic_kernel/agents/azure_ai/azure_ai_agent.py:204

    funcs = kernel.get_list_of_function_metadata_filters({"included_functions": f"{plugin_name}-{function_name}"})

    match len(funcs):
        case 0:
            raise AgentInitializationException(f"Function `{spec.id}` not found in kernel.")
        case 1:
            return kernel_function_metadata_to_function_call_format(funcs[0])  # type: ignore[return-value]
        case _:
            raise AgentInitializationException(f"Multiple definitions found for `{spec.id}`. Please remove duplicates.")


@_register_tool("openapi")
def _openapi(spec: ToolSpec) -> OpenApiTool:
    opts = spec.options or {}

    if not spec.id:
        raise AgentInitializationException("OpenAPI tool requires a non-empty 'id' (used as name).")
    if not spec.description:
        raise AgentInitializationException(f"OpenAPI tool '{spec.id}' requires a 'description'.")

    raw_spec = opts.get("specification")
    if not raw_spec:
        raise AgentInitializationException(f"OpenAPI tool '{spec.id}' is missing required 'specification' field.")

    try:
        parsed_spec = json.loads(raw_spec) if isinstance(raw_spec, str) else raw_spec
    except json.JSONDecodeError as e:
        raise AgentInitializationException(f"Invalid JSON in OpenAPI 'specification' field: {e}") from e

    auth = opts.get("auth", OpenApiAnonymousAuthDetails())

    return OpenApiTool(
        name=spec.id,
        description=spec.description,
        spec=parsed_spec,
        auth=auth,
        default_parameters=opts.get("default_parameters"),

View on GitHub (pinned to c028a0c7dc)

Solutions

Add a concise, non-empty description to the openapi tool entry explaining what the API does.
If the description is generated dynamically, ensure it resolves to a non-empty string before building the agent.

Example fix

// before
tools:
  - type: openapi
    id: weatherApi
    options:
      specification: '{...}'

// after
tools:
  - type: openapi
    id: weatherApi
    description: Returns current weather for a city.
    options:
      specification: '{...}'

Defensive patterns

Strategy: validation

Validate before calling

def ensure_openapi_description(tool_spec: dict) -> None:
    if not tool_spec.get("description"):
        raise ValueError("openapi tool requires non-empty 'description'")

Type guard

def has_openapi_description(tool_spec: dict) -> bool:
    return bool(tool_spec.get("description"))

Prevention

Require description in your spec schema for every openapi tool.
Write the description for the model: describe when to call the API, not its internals.

When it happens

Trigger: Declarative spec includes an openapi tool with an id but missing or empty description field.

Common situations: Developer relies on the OpenAPI spec's own description and omits the tool-level description; description field templated from an unset variable.

Related errors

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