Document Tools API

[isidorn]

We need https://code.visualstudio.com/api/extension-guides/tools

I can take a first stab at this, and then @roblourens and @ntrogh can contribute.
I see that @roblourens already updated the sample.

[roblourens]

Just a few simple notes on a tools doc

• First, I am working on some kind of library that will make it easier to write chat participants with tool calling. It doesn't exist yet but will in some form by the end of the month. I would like it to be the primary way recommended way to write a chat extension. So we might keep that in mind, because when it's ready, the docs would probably change to focus on that, while also mentioning how it all works in the API itself without using the library. Maybe we want to keep the doc light in the first cut, I just don't want us all to waste too much effort on a version that might be reworked for the library...
• What is tool calling, in an LLM?
  • Could link to How to use function calling with Azure OpenAI Service - Azure OpenAI Service | Microsoft Learn, or the OpenAI version, or use it for inspiration
• What are some scenarios that you might want to use tool calling for?
  • Let the LLM dynamically ask for more context
  • Let the LLM take some action dynamically
  • Hook up some context/behavior that is contributed by another VS Code extension
• What does the basic tool calling flow look like?
  • Maybe show the code sample for the basic non-prompt-tsx tool calling loop
• When to register a tool with the VS Code API, and when to do "private" tool calling?
  • Makes the most sense to register the tool with vscode when the tool makes sense to other extensions, and could be used without special handling for the particular tool. Point out that tools in the API are all public, so other extensions can use them.
  • If extensions want to make use of the progress message and confirmation, then it needs to be registered in the API.
  • If the tool has some special handling, or the extension doesn't want it to be public, then it can be a private tool.
  • I don't know whether "private" tool is the best phrasing, could also be "ad-hoc tool" or just "a tool that isn't registered in the API..."
• Description of the chat samples