feat: adding tool annotation used by MCP

llama_stack/apis/agents/openai_responses.py

@@ -116,6 +116,7 @@ class MCPListToolsTool(BaseModel):
     input_schema: dict[str, Any]
     name: str
     description: str | None = None
+    annotations: dict[str, Any] | None = None
 
 
 @json_schema_type

llama_stack/apis/tools/tools.py

@@ -27,6 +27,15 @@ class ToolParameter(BaseModel):
     default: Any | None = None
 
 
+@json_schema_type
+class ToolAnnotations(BaseModel):
+    title: str | None = None
+    readOnlyHint: bool | None = None
+    destructiveHint: bool | None = None
+    idempotentHint: bool | None = None
+    openWorldHint: bool | None = None
+
+
 @json_schema_type
 class Tool(Resource):
     type: Literal[ResourceType.tool] = ResourceType.tool
@@ -34,6 +43,7 @@ class Tool(Resource):
     description: str
     parameters: list[ToolParameter]
     metadata: dict[str, Any] | None = None
+    annotations: ToolAnnotations | None = None
 
 
 @json_schema_type
@@ -42,6 +52,7 @@ class ToolDef(BaseModel):
     description: str | None = None
     parameters: list[ToolParameter] | None = None
     metadata: dict[str, Any] | None = None
+    annotations: ToolAnnotations | None = None
 
 
 @json_schema_type

llama_stack/distribution/routing_tables/toolgroups.py

@@ -74,6 +74,7 @@ class ToolGroupsRoutingTable(CommonRoutingTableImpl, ToolGroups):
                     parameters=t.parameters or [],
                     metadata=t.metadata,
                     provider_id=toolgroup.provider_id,
+                    annotations=t.annotations,
                 )
             )
 

llama_stack/models/llama/datatypes.py

@@ -11,6 +11,8 @@ from typing import Annotated, Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
 
+from apis.tools import ToolAnnotations
+
 # The goal is that these set of types are relevant for all Llama models.
 # That isn't the current state yet -- e.g., BuiltinTool is somewhat specific to
 # the llama3 series of models.
@@ -99,6 +101,7 @@ class ToolDefinition(BaseModel):
     tool_name: BuiltinTool | str
     description: str | None = None
     parameters: dict[str, ToolParamDefinition] | None = None
+    annotations: ToolAnnotations | None = None
 
     @field_validator("tool_name", mode="before")
     @classmethod

llama_stack/providers/inline/agents/meta_reference/agent_instance.py

@@ -843,6 +843,7 @@ class ChatAgent(ShieldRunnerMixin):
                             )
                             for param in tool_def.parameters
                         },
+                        annotations=tool_def.annotations,
                     )
                     tool_name_to_args[tool_def.identifier] = toolgroup_to_args.get(toolgroup_name, {})
 

llama_stack/providers/inline/agents/meta_reference/openai_responses.py

@@ -665,6 +665,7 @@ class OpenAIResponsesImpl:
                                     },
                                     "required": [p.name for p in t.parameters if p.required],
                                 },
+                                annotations=t.annotations,
                             )
                         )
             else:

llama_stack/providers/utils/tools/mcp.py

@@ -65,6 +65,7 @@ async def list_mcp_tools(endpoint: str, headers: dict[str, str]) -> ListToolDefs
                         description=param_schema.get("description", ""),
                     )
                 )
+            annotations = getattr(tool, "annotations", None)
             tools.append(
                 ToolDef(
                     name=tool.name,
@@ -73,6 +74,7 @@ async def list_mcp_tools(endpoint: str, headers: dict[str, str]) -> ListToolDefs
                     metadata={
                         "endpoint": endpoint,
                     },
+                    annotations=annotations,
                 )
             )
     return ListToolDefsResponse(data=tools)