McpWorkbench.list_tools() drops MCP tool annotations; ToolSchema has no annotations field (0.7.2)

[mesimewplc]

Hello,

Annotations are part of many MCP tool ecosystems and are useful for UI/UX hints (e.g., readOnly, destructive) - documented here: MCP Annotations Spec (2025-06-18). As of Autogen 0.7.2 there is still no official support for annotations.

Stock McpWorkbench.list_tools() does not surface MCP tool annotations even when the server provides them, while raw MCP list_tools shows annotations present for tools.

Root cause:
autogen_core.tools._base.ToolSchema lacks annotations; autogen_ext.tools.mcp._workbench.McpWorkbench.list_tools() doesn’t forward them.

Sample script to reproduce:

import sys
import json
import asyncio
import importlib.metadata as md
from typing import Any, Mapping

from autogen_ext.tools.mcp import McpWorkbench, StreamableHttpServerParams

MCP_SERVER_URL = "" 
MCP_TOOL_NAME = "experimentalSummarizeText"

def _to_tool_dict(t: Any) -> Mapping[str, Any]:
    if isinstance(t, dict):
        return t
    if hasattr(t, "model_dump"):
        try:
            return t.model_dump()
        except Exception:
            pass
    return {
        "name": getattr(t, "name", None),
        "description": getattr(t, "description", None),
        "parameters": getattr(t, "parameters", None),
        "annotations": getattr(t, "annotations", None),
    }

async def main() -> None:
    url = MCP_SERVER_URL
    selected_tool_name = MCP_TOOL_NAME

    versions = {}
    for name in [
        "autogen-ext",
        "autogen-core",
        "autogen-agentchat",
        "autogen_ext",
        "autogen_core",
        "autogen_agentchat",
    ]:
        try:
            versions[name] = md.version(name)
        except Exception:
            pass

    params = StreamableHttpServerParams(url=url)
    wb = McpWorkbench(server_params=params)

    try:
        await wb.start()

        # 1) Stock workbench list_tools()
        tools = await wb.list_tools()
        if not selected_tool_name and tools:
            first = _to_tool_dict(tools[0])
            selected_tool_name = first.get("name")

        stock_tool = {"name": selected_tool_name, "has_annotations": False}
        for t in tools:
            td = _to_tool_dict(t)
            if td.get("name") == selected_tool_name:
                stock_tool["has_annotations"] = bool(td.get("annotations"))
                break

        # 2) Raw MCP payload via internal actor
        raw_tool = {"name": selected_tool_name, "has_annotations": False, "annotations_keys": []}
        actor = wb._actor
        rf = await actor.call("list_tools", None)
        ltr = await rf
        for t in getattr(ltr, "tools", []) or []:
            td = _to_tool_dict(t)
            name = td.get("name") or getattr(t, "name", None)
            if name != selected_tool_name:
                continue
            ann = td.get("annotations") or getattr(t, "annotations", None) or {}
            raw_tool = {
                "name": name,
                "has_annotations": bool(ann),
                "annotations_keys": list(ann.keys()) if isinstance(ann, dict) else [],
            }
            break

        output = {
            "versions": versions,
            "selected_tool": selected_tool_name,
            "stock_workbench": stock_tool,
            "raw_mcp": raw_tool,
        }
        print(json.dumps(output))
    finally:
        try:
            await wb.stop()
        except Exception:
            pass

if __name__ == "__main__":
    asyncio.run(main())

Example output observed:

{
	"versions": {
		"autogen-ext": "0.7.2",
		"autogen-core": "0.7.2",
		"autogen-agentchat": "0.7.2",
		"autogen_ext": "0.7.2",
		"autogen_core": "0.7.2",
		"autogen_agentchat": "0.7.2"
	},
	"selected_tool": "experimentalSummarizeText",
	"stock_workbench": {
		"name": "experimentalSummarizeText",
		"has_annotations": false
	},
	"raw_mcp": {
		"name": "experimentalSummarizeText",
		"has_annotations": true,
		"annotations_keys": [
			"title",
			"readOnlyHint",
			"destructiveHint",
			"idempotentHint",
			"openWorldHint"
		]
	}
}

Expected: If MCP server returns annotations, McpWorkbench.list_tools() should preserve them in the returned tool schema.
Actual: stock_workbench.has_annotations is false while raw_mcp.has_annotations is true. Annotations are dropped during conversion.

Origin:
autogen_core.tools._base.ToolSchema does not include an annotations key:

class ToolSchema(TypedDict):
    parameters: NotRequired[ParametersSchema]
    name: str
    description: NotRequired[str]
    strict: NotRequired[bool]

And autogen_ext.tools.mcp._workbench.McpWorkbench.list_tools() maps MCP tool responses into ToolSchema without forwarding annotations:

parameters = ParametersSchema(
    type="object",
    properties=tool.inputSchema.get("properties", {}),
    required=tool.inputSchema.get("required", []),
    additionalProperties=tool.inputSchema.get("additionalProperties", False),
)
tool_schema = ToolSchema(
    name=name,
    description=description,
    parameters=parameters,
)

Suggested Fix:
Add annotations: NotRequired[Dict[str, Any]] to autogen_core.tools._base.ToolSchema.
In autogen_ext.tools.mcp._workbench.McpWorkbench.list_tools(), if tool.annotations exists, include it when constructing the ToolSchema result.

For example: ToolSchema(..., annotations=getattr(tool, "annotations", None) or None)