Adding that Chef's Kiss to your Teams App descriptions for Copilot

Introduction

As a brief introduction, Teams Message extensions is one of the extensibility approaches for Copilot for Microsoft 365. In writing a recent community sample for my own learning, I discovered it is very fiddly to setup the app to ensure that Copilot can recognise that the app can serve data from the plugin for solving the users prompt.

I cannot emphesise enough that the key to this is ensuring that the app description is well written and structured to allow Copilot to understand the app’s capabilities - which leads me to the purpose of this post highlight the differences between strong and weak app descriptions and how to improve them.

What are the key fields in the app manifest that Copilot uses?

When developing we are used to a fixed set of inputs and in a sense predictable outcomes, but with Copilot, it is a bit of a black box, as Copilot either the LLM or the Orchestrator uses key description fields within the app manifest to understand what your app is doing and determining suitablility of the request, what the parameters are and how to respond to the user prompt. In essense to advertise your app and “convince” Copilot to use your app to fulfil the user prompt.

In a recent manifest update (1.17) there are new properties that can be used to help Copilot understand your app better, such as semantic descriptions for commands and parameters. This can provide you a way to describe what the app is doing and how to behave, in a prompt manner, which wouldnt necessarily be seen, clearly describable or readable by the end user. If you do not populate the semantic descriptions, Copilot will fall back to the standard description fields.

For example this is a bad example of description:

In the above example, the description (and semantic) is very short and does not provide enough information for Copilot to understand what the app does or even to a human if we cannot understand it, how can Copilot.

Beefing up your descriptions

So lets look at what you can do to improve your app descriptions to make them more discoverable by Copilot:

• App Descriptions - clearly describe what the app is doing, the benefits and features to the user, examples and scenarios where the app can be used.
• Command Descriptions (Semantic Descriptions) - describe what the command does, how it can be used, what parameters are needed and how to use them.
• Command Parameter Descriptions (Semantic Descriptions) - describe the property, expected inputs, formats and examples, I found examples to be very effective.

Did you know that Teams App Descriptions support Markdown to provide very rich descriptions

I cannot take full credit for this, during my learning I found an awesome sample from Microsoft the NorthWind Inventory Message Extension example, after reading the Teams Application code and noticed the descriptions and formatting to be very rich and detailed, which I found very helpful in understanding how to structure the descriptions.

 "description": {
        "short": "App allows you to find and update product inventory information",
        "full": "Northwind Inventory is the ultimate tool for managing your product inventory. With its intuitive interface and powerful features, you'll be able to easily find your products by name, category, inventory status, and supplier city. You can also update inventory information with the app. \n\n **Why Choose Northwind Inventory:** \n\n Northwind Inventory is the perfect solution for businesses of all sizes that need to keep track of their inventory. Whether you're a small business owner or a large corporation, Northwind Inventory can help you stay on top of your inventory management needs. \n\n **Features and Benefits:** \n\n - Easy Product Search through Microsoft Copilot. Simply start by saying, 'Find northwind dairy products that are low on stock' \r - Real-Time Inventory Updates: Keep track of inventory levels in real-time and update them as needed \r  - User-Friendly Interface: Northwind Inventory's intuitive interface makes it easy to navigate and use \n\n **Availability:** \n\n To use Northwind Inventory, you'll need an active Microsoft 365 account . Ensure that your administrator enables the app for your Microsoft 365 account."
    },

So lets make our descriptions richer

Using this example, I produced my description and it produced nice results in describing the app and its capabilities, not just to Copilot but the end user too.

 "description": {
        "short": "Allows users to query the status of their M365 Tenant Message Center messages",
        "full": "PKB Message Center is an app that lets the user know the status of the Microsoft 365 tenant including service health and message center announcement for change and other changes coming soon. \n\n**Why choose PKB Message Center** \n\n PKB Message Center is a great way of finding out in the flow of work the status of the tenant and any upcoming changes that staff may need to know about. This app can help you stay on top of the upcoming changes with a specific workloads within the tenant e.g., Teams, SharePoint, OneDrive and Exchange services \n\n**Features and Benefits**\n\n - Simple health search through Microsoft Copilot. Simply start saying 'What is the health status of SharePoint workload?' \n\n - Get latest announcements from the message center through Microsoft Copilot. Start saying 'What new features or changes are coming to the SharePoint workload?'\n\n - Find out what is happening with a specific ID for message with Microsoft Copilot, by saying 'What is status of MC123456 within the message center?'"
    },

Which when loaded for the user when selecting the application, looks quite tidy:

Note: I made small modification to the image to avoid showing the scrollbar and the full text

Semantic Descriptions for Commands and Parameters

So lets see what a better app sementic description looks like in the Teams App Manifest:

To zoom in a bit on the command:

For this command, I provide clear usage details, such as types of words to watch, and tell the LLM to ignore some of the output details, if I wanted to capture IDs or types, then I can describe this and I found this to be very effective in getting Copilot to understand the command and populate the parameters correctly.

At this time, you might be thinking, really, is that it, but yeap, thats it, however don’t under estimate the rounds it took to refine the description to get it right, So I would recommend using the same prompts to get started then branch out with variations to see what works best for you.

Lets show you the difference:

Using bad app description with Copilot

In this example, I had minimal/no descriptions and Copilot could not match the simpliest queries:

As you can see, Copilot could not match the query, to then use the data from the app, the results you see, are from another data source, my Graph connector sample for Ignite 2023 content.

So lets be more specific with an ID and still this didnt yield a positive result:

Good app description with Copilot

Ok, then I updated the app description and command descriptions to see the difference:

Same prompt, but with a good quality output. Sweet!

Conclusion

The app descriptions was a huge surprise for me when developing for Copilot, as I did not expect the app descriptions to be so important in the development process. My descriptions are by no means perfect and I’m sure there is plenty of room for improvement, however, I am fairly happy with the results.

I hope this post has been useful in understanding how to improve your app descriptions to make them more discoverable by Copilot or humans even lol.

‘appy Days!

Resources

• Define descriptions in Guidelines for message extension plugins
• Customise the App Manifest | Microsoft Learn
• Microsoft Teams Toolkit Overview | Microsoft Learn
• Extend Microsoft Copilot for Microsoft 365 | Microsoft Learn
• Microsoft Adaptive Card Previewer | Microsoft Learn
• Extend bot-based message extension as plugin for Copilot for Microsoft 365 | Microsoft Learn
• Build message extensions using Bot Framework | Microsoft Learn
• Copilot Plugin FAQ | Microsoft Learn

Transparency Notice: Content within this post was assisted with AI to speed up the writing process and experimentation on my part, accuracy has been checked and adjusted where needed.

Enjoy!