This is a sample/demo MCP server showcasing NestJS integration patterns. Tool definitions are present with descriptions and some schema information, but fall short of production quality. Most tools have generic one-liner descriptions (8-20 chars) that fail to guide LLM selection. 5 tools (pizza-map, pizza-carousel, pizza-albums, pizza-list, pizza-video from pizzaz-mcp-apps-ext) have no input parameters, while their counterparts in pizzaz-openai-apps-sdk define required parameters, indicating inconsistent API surface. Schemas are partially documented but descriptions are minimal. The sample lacks error handling guidance, permission scoping, and output schema documentation. Tool naming (pizza-*) is non-standard, lacks action verbs like get_, show_, render_. Duplicate tool names across the two packages (same name with different parameter signatures) would cause confusion in a real agent.

• Rename tools to follow verb_noun convention. Examples: show_pizza_map, render_pizza_carousel, list_available_pizzas, get_pizza_details. This helps LLMs infer intent from the name alone.
• Expand all tool descriptions to 50-200 characters explaining WHAT the tool does, WHEN to use it, and WHAT it returns. Example: 'Renders a visual map of pizza locations. Use this to help users find nearby pizza restaurants. Returns location coordinates and store details.'
• Consolidate duplicate tool definitions. Choose ONE canonical implementation per tool and define clear parameter signatures. If different parameter sets are needed, give them distinct names (e.g., show_pizza_map vs show_pizza_map_with_topping).
• Formally document output schemas using JSON Schema. Define the structure of 'content' array items, 'structuredContent' fields, and any nested objects. This enables LLMs to plan downstream tool chains.
• Add error handling and recovery guidance to tool descriptions. Document when tools fail, what errors are retryable, and what alternatives the LLM should try. Example: 'If location is not found, try calling list_available_locations() first.'
• Enhance parameter descriptions with format constraints. For 'topping' parameter: 'The pizza topping to filter or mention. Valid values: pepperoni, mushroom, sausage, vegetables, cheese. Case-insensitive. Optional; if omitted, shows all toppings.'
• Add 'when' context to UI metadata documentation. Clarify in the tool description when the UI resource will be rendered and what clients should do if they cannot render it.