feat: Add items and title to ToolParameter/ToolParamDefinition (#3003)

# What does this PR do?
<!-- Provide a short summary of what this PR does and why. Link to
relevant issues if applicable. -->
Add items and title to ToolParameter/ToolParamDefinition. Adding items
will resolve the issue that occurs with Gemini LLM when an MCP tool has
array-type properties.

<!-- If resolving an issue, uncomment and update the line below -->
<!-- Closes #[issue-number] -->

## Test Plan
<!-- Describe the tests you ran to verify your changes with result
summaries. *Provide clear instructions so the plan can be easily
re-executed.* -->
Unite test cases will be added.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Kai Wu <[email protected]>
Co-authored-by: Ashwin Bharambe <[email protected]>

Author: 4 people

docs/static/llama-stack-spec.html

@@ -6783,6 +6783,31 @@
                         "type": "boolean",
                         "default": true
                     },
+                    "items": {
+                        "oneOf": [
+                            {
+                                "type": "null"
+                            },
+                            {
+                                "type": "boolean"
+                            },
+                            {
+                                "type": "number"
+                            },
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "type": "array"
+                            },
+                            {
+                                "type": "object"
+                            }
+                        ]
+                    },
+                    "title": {
+                        "type": "string"
+                    },
                     "default": {
                         "oneOf": [
                             {
@@ -7457,6 +7482,14 @@
                         "default": true,
                         "description": "Whether this parameter is required for tool invocation"
                     },
+                    "items": {
+                        "type": "object",
+                        "description": "Type of the elements when parameter_type is array"
+                    },
+                    "title": {
+                        "type": "string",
+                        "description": "(Optional) Title of the parameter"
+                    },
                     "default": {
                         "oneOf": [
                             {

docs/static/llama-stack-spec.yaml

@@ -4866,6 +4866,16 @@ components:
         required:
           type: boolean
           default: true
+        items:
+          oneOf:
+            - type: 'null'
+            - type: boolean
+            - type: number
+            - type: string
+            - type: array
+            - type: object
+        title:
+          type: string
         default:
           oneOf:
             - type: 'null'
@@ -5403,6 +5413,13 @@ components:
           default: true
           description: >-
             Whether this parameter is required for tool invocation
+        items:
+          type: object
+          description: >-
+            Type of the elements when parameter_type is array
+        title:
+          type: string
+          description: (Optional) Title of the parameter
         default:
           oneOf:
             - type: 'null'

llama_stack/apis/tools/tools.py

@@ -27,13 +27,17 @@ class ToolParameter(BaseModel):
     :param parameter_type: Type of the parameter (e.g., string, integer)
     :param description: Human-readable description of what the parameter does
     :param required: Whether this parameter is required for tool invocation
+    :param items: Type of the elements when parameter_type is array
+    :param title: (Optional) Title of the parameter
     :param default: (Optional) Default value for the parameter if not provided
     """
 
     name: str
     parameter_type: str
     description: str
     required: bool = Field(default=True)
+    items: dict | None = None
+    title: str | None = None
     default: Any | None = None
 
 

llama_stack/models/llama/datatypes.py

@@ -92,6 +92,8 @@ class ToolParamDefinition(BaseModel):
     param_type: str
     description: str | None = None
     required: bool | None = True
+    items: Any | None = None
+    title: str | None = None
     default: Any | None = None
 
 

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

@@ -798,6 +798,8 @@ async def _initialize_tools(
                         param_type=param.parameter_type,
                         description=param.description,
                         required=param.required,
+                        items=param.items,
+                        title=param.title,
                         default=param.default,
                     )
                     for param in tool_def.parameters
@@ -841,6 +843,8 @@ async def _initialize_tools(
                                 param_type=param.parameter_type,
                                 description=param.description,
                                 required=param.required,
+                                items=param.items,
+                                title=param.title,
                                 default=param.default,
                             )
                             for param in tool_def.parameters

llama_stack/providers/utils/inference/openai_compat.py

@@ -805,6 +805,10 @@ def convert_tooldef_to_openai_tool(tool: ToolDefinition) -> dict:
                 properties[param_name].update(description=param.description)
             if param.default:
                 properties[param_name].update(default=param.default)
+            if param.items:
+                properties[param_name].update(items=param.items)
+            if param.title:
+                properties[param_name].update(title=param.title)
             if param.required:
                 required.append(param_name)
 

llama_stack/providers/utils/tools/mcp.py

@@ -120,6 +120,10 @@ async def list_mcp_tools(endpoint: str, headers: dict[str, str]) -> ListToolDefs
                         name=param_name,
                         parameter_type=param_schema.get("type", "string"),
                         description=param_schema.get("description", ""),
+                        required="default" not in param_schema,
+                        items=param_schema.get("items", None),
+                        title=param_schema.get("title", None),
+                        default=param_schema.get("default", None),
                     )
                 )
             tools.append(

tests/common/mcp.py

@@ -167,6 +167,8 @@ def make_mcp_server(required_auth_token: str | None = None, tools: dict[str, Cal
     from starlette.responses import Response
     from starlette.routing import Mount, Route
 
+    from llama_stack.log import get_logger
+
     server = FastMCP("FastMCP Test Server", log_level="WARNING")
 
     tools = tools or default_tools()
@@ -211,52 +213,72 @@ def get_open_port():
             return sock.getsockname()[1]
 
     port = get_open_port()
+    logger = get_logger(__name__, category="tests::mcp")
 
     # make uvicorn logs be less verbose
     config = uvicorn.Config(app, host="0.0.0.0", port=port, log_level="warning")
     server_instance = uvicorn.Server(config)
     app.state.uvicorn_server = server_instance
 
     def run_server():
-        server_instance.run()
+        try:
+            logger.info(f"Starting MCP server on port {port}")
+            server_instance.run()
+            logger.info(f"MCP server on port {port} has stopped")
+        except Exception as e:
+            logger.error(f"MCP server failed to start on port {port}: {e}")
+            raise
 
     # Start the server in a new thread
     server_thread = threading.Thread(target=run_server, daemon=True)
+    logger.info(f"Starting MCP server thread on port {port}")
     server_thread.start()
 
     # Polling until the server is ready
     timeout = 10
     start_time = time.time()
 
     server_url = f"http://localhost:{port}/sse"
+    logger.info(f"Waiting for MCP server to be ready at {server_url}")
+
     while time.time() - start_time < timeout:
         try:
             response = httpx.get(server_url)
             if response.status_code in [200, 401]:
+                logger.info(f"MCP server is ready on port {port} (status: {response.status_code})")
                 break
-        except httpx.RequestError:
+        except httpx.RequestError as e:
+            logger.debug(f"Server not ready yet, retrying... ({e})")
             pass
         time.sleep(0.1)
+    else:
+        # If we exit the loop due to timeout
+        logger.error(f"MCP server failed to start within {timeout} seconds on port {port}")
+        logger.error(f"Thread alive: {server_thread.is_alive()}")
+        if server_thread.is_alive():
+            logger.error("Server thread is still running but not responding to HTTP requests")
 
     try:
         yield {"server_url": server_url}
     finally:
+        logger.info(f"Shutting down MCP server on port {port}")
         server_instance.should_exit = True
         time.sleep(0.5)
 
         # Force shutdown if still running
         if server_thread.is_alive():
             try:
+                logger.info("Force shutting down server thread")
                 if hasattr(server_instance, "servers") and server_instance.servers:
                     for srv in server_instance.servers:
                         srv.close()
 
                 # Wait for graceful shutdown
                 server_thread.join(timeout=3)
                 if server_thread.is_alive():
-                    print("Warning: Server thread still alive after shutdown attempt")
+                    logger.warning("Server thread still alive after shutdown attempt")
             except Exception as e:
-                print(f"Error during server shutdown: {e}")
+                logger.error(f"Error during server shutdown: {e}")
 
         # CRITICAL: Reset SSE global state to prevent event loop contamination
         # Reset the SSE AppStatus singleton that stores anyio.Event objects

tests/integration/recordings/responses/168daab89068.json

@@ -0,0 +1,167 @@
+{
+  "request": {
+    "method": "POST",
+    "url": "http://localhost:11434/api/generate",
+    "headers": {},
+    "body": {
+      "model": "llama3.2:3b-instruct-fp16",
+      "raw": true,
+      "prompt": "<|begin_of_text|><|start_header_id|>system<|end_header_id|>\n\nYou are a helpful assistant. You have access to functions, but you should only use them if they are required.\nYou are an expert in composing functions. You are given a question and a set of possible functions.\nBased on the question, you may or may not need to make one function/tool call to achieve the purpose.\n\nIf you decide to invoke any of the function(s), you MUST put it in the format of [func_name1(params_name1=params_value1, params_name2=params_value2...), func_name2(params)]\nIf you decide to invoke a function, you SHOULD NOT include any other text in the response. besides the function call in the above format.\nFor a boolean parameter, be sure to use `True` or `False` (capitalized) for the value.\n\n\nHere is a list of functions in JSON format that you can invoke.\n\n[\n    {\n        \"name\": \"greet_everyone\",\n        \"description\": \"\",\n        \"parameters\": {\n            \"type\": \"dict\",\n            \"required\": [\"url\"],\n            \"properties\": {\n                \"url\": {\n                    \"type\": \"string\",\n                    \"description\": \"\"\n                }\n            }\n        }\n    },\n    {\n        \"name\": \"get_boiling_point\",\n        \"description\": \"\n        Returns the boiling point of a liquid in Celsius or Fahrenheit.\n\n        :param liquid_name: The name of the liquid\n        :param celsius: Whether to return the boiling point in Celsius\n        :return: The boiling point of the liquid in Celcius or Fahrenheit\n        \",\n        \"parameters\": {\n            \"type\": \"dict\",\n            \"required\": [\"liquid_name\"],\n            \"properties\": {\n                \"liquid_name\": {\n                    \"type\": \"string\",\n                    \"description\": \"\"\n                },\n                \"celsius\": {\n                    \"type\": \"boolean\",\n                    \"description\": \"\",\n                    \"default\": \"True\"\n                }\n            }\n        }\n    }\n]\n\nYou can answer general questions or invoke tools when necessary.\nIn addition to tool calls, you should also augment your responses by using the tool outputs.\nYou are a helpful assistant.<|eot_id|><|start_header_id|>user<|end_header_id|>\n\nSay hi to the world. Use tools to do so.<|eot_id|><|start_header_id|>assistant<|end_header_id|>\n\n[greet_everyone(url=\"world\")]<|eot_id|><|start_header_id|>ipython<|end_header_id|>\n\nHello, world!<|eot_id|><|start_header_id|>assistant<|end_header_id|>\n\n",
+      "options": {
+        "temperature": 0.0
+      },
+      "stream": true
+    },
+    "endpoint": "/api/generate",
+    "model": "llama3.2:3b-instruct-fp16"
+  },
+  "response": {
+    "body": [
+      {
+        "__type__": "ollama._types.GenerateResponse",
+        "__data__": {
+          "model": "llama3.2:3b-instruct-fp16",
+          "created_at": "2025-09-27T18:05:56.663224Z",
+          "done": false,
+          "done_reason": null,
+          "total_duration": null,
+          "load_duration": null,
+          "prompt_eval_count": null,
+          "prompt_eval_duration": null,
+          "eval_count": null,
+          "eval_duration": null,
+          "response": "How",
+          "thinking": null,
+          "context": null
+        }
+      },
+      {
+        "__type__": "ollama._types.GenerateResponse",
+        "__data__": {
+          "model": "llama3.2:3b-instruct-fp16",
+          "created_at": "2025-09-27T18:05:56.706706Z",
+          "done": false,
+          "done_reason": null,
+          "total_duration": null,
+          "load_duration": null,
+          "prompt_eval_count": null,
+          "prompt_eval_duration": null,
+          "eval_count": null,
+          "eval_duration": null,
+          "response": " can",
+          "thinking": null,
+          "context": null
+        }
+      },
+      {
+        "__type__": "ollama._types.GenerateResponse",
+        "__data__": {
+          "model": "llama3.2:3b-instruct-fp16",
+          "created_at": "2025-09-27T18:05:56.751075Z",
+          "done": false,
+          "done_reason": null,
+          "total_duration": null,
+          "load_duration": null,
+          "prompt_eval_count": null,
+          "prompt_eval_duration": null,
+          "eval_count": null,
+          "eval_duration": null,
+          "response": " I",
+          "thinking": null,
+          "context": null
+        }
+      },
+      {
+        "__type__": "ollama._types.GenerateResponse",
+        "__data__": {
+          "model": "llama3.2:3b-instruct-fp16",
+          "created_at": "2025-09-27T18:05:56.794187Z",
+          "done": false,
+          "done_reason": null,
+          "total_duration": null,
+          "load_duration": null,
+          "prompt_eval_count": null,
+          "prompt_eval_duration": null,
+          "eval_count": null,
+          "eval_duration": null,
+          "response": " assist",
+          "thinking": null,
+          "context": null
+        }
+      },
+      {
+        "__type__": "ollama._types.GenerateResponse",
+        "__data__": {
+          "model": "llama3.2:3b-instruct-fp16",
+          "created_at": "2025-09-27T18:05:56.837831Z",
+          "done": false,
+          "done_reason": null,
+          "total_duration": null,
+          "load_duration": null,
+          "prompt_eval_count": null,
+          "prompt_eval_duration": null,
+          "eval_count": null,
+          "eval_duration": null,
+          "response": " you",
+          "thinking": null,
+          "context": null
+        }
+      },
+      {
+        "__type__": "ollama._types.GenerateResponse",
+        "__data__": {
+          "model": "llama3.2:3b-instruct-fp16",
+          "created_at": "2025-09-27T18:05:56.879926Z",
+          "done": false,
+          "done_reason": null,
+          "total_duration": null,
+          "load_duration": null,
+          "prompt_eval_count": null,
+          "prompt_eval_duration": null,
+          "eval_count": null,
+          "eval_duration": null,
+          "response": " further",
+          "thinking": null,
+          "context": null
+        }
+      },
+      {
+        "__type__": "ollama._types.GenerateResponse",
+        "__data__": {
+          "model": "llama3.2:3b-instruct-fp16",
+          "created_at": "2025-09-27T18:05:56.92182Z",
+          "done": false,
+          "done_reason": null,
+          "total_duration": null,
+          "load_duration": null,
+          "prompt_eval_count": null,
+          "prompt_eval_duration": null,
+          "eval_count": null,
+          "eval_duration": null,
+          "response": "?",
+          "thinking": null,
+          "context": null
+        }
+      },
+      {
+        "__type__": "ollama._types.GenerateResponse",
+        "__data__": {
+          "model": "llama3.2:3b-instruct-fp16",
+          "created_at": "2025-09-27T18:05:56.963339Z",
+          "done": true,
+          "done_reason": "stop",
+          "total_duration": 492973041,
+          "load_duration": 103979375,
+          "prompt_eval_count": 482,
+          "prompt_eval_duration": 87032041,
+          "eval_count": 8,
+          "eval_duration": 300586375,
+          "response": "",
+          "thinking": null,
+          "context": null
+        }
+      }
+    ],
+    "is_streaming": true
+  }
+}