doc update

docs/content/tools/_index.md

@@ -1,38 +1,44 @@
 ---
-title: MCP/docker Toolbox
+title: MCP Catalog
 weight: 1
 cascade:
   type: docs
 ---
 
 ## Background
 
-The `mcp/run` container is an mcp server that can be extended with new
+The `mcp/docker` container is an mcp server that can be extended with new
 container-based tools, and prompts. Existing containers, like `curl` or `ffmpeg`, can
 now be exposed as MCP servers without having to wrap each tool in an mcp server.
 
 ```mermaid
 flowchart LR
-    desktop["Claude Desktop"]
-    subgraph docker["Docker"]
+    desktop["MCP Client"]
+    subgraph docker["Docker Desktop"]
         mcp["mcp/docker"]
     end
     desktop --> docker
-    docker -- extended by --- box1["Tools/Prompt Def (curl)"]
-    docker -- extended by --- box2["Tools/Prompt Def (ffmpeg)"]
+    docker -- extended by --- box1["Tool Containers"]
+    docker -- extended by --- box2["MCP Server Containers"]
     style desktop fill:#f9f9f9,stroke:#333,stroke-width:2px
     style docker fill:#e6f3ff,stroke:#333,stroke-width:2px,color:#0066cc
     style mcp fill:#fff,stroke:#333,stroke-width:1px
     style box1 fill:#f9f9f9,stroke:#333,stroke-width:2px
     style box2 fill:#f9f9f9,stroke:#333,stroke-width:2px
 ```
 
-Definitions of new tools and prompts are made using markdown documents (see [examples](examples)).
+Definitions of new tools and prompts are made using markdown documents that can either use plain Docker
+image _as_ tools, or serve requests to containerized MCP servers.
 
 ```markdown
 ---
 tools:
   - name: curl
+    description: run the curl command
+    container:
+      image: curl:latest
+mcp:
+  - container: mcp/sequentialthinking
 ---
 
 # prompt
@@ -42,14 +48,8 @@ Run the curl command, in silent mode, to fetch gists for user slimslenderslacks
 
 ## Getting Started
 
-We can use this to extend MCP clients like Claude Desktop, and test new tool definitions using
-VSCode. Instructions for these two paths are here.
-
-1. Attach the MCP server [to Claude Desktop](quickstart).
-   {{< callout >}}
-   Claude Desktop has not yet implemented the `notifications/tools/list_changed`. This means that
-   Claude doesn't reload our tool definitions until it is restarted. It's easier to develop
-   prompts in VSCode where we can create a much more efficient inner loop.
-   {{< /callout >}}
-2. [Test prompt definitions](quickstart_vscode) using our VSCode extension. Using VSCode as an
+1. [using Gordon](quickstart_gordon)
+2. [using Claude Desktop](quickstart)
+3. [using Cursor](quickstart_cursor)
+4. [testing definitions in vscode](quickstart_vscode) using our VSCode extension. Using VSCode as an
    mcp server can provide an effective inner loop for developing the content.

docs/content/tools/posts/_index.md

@@ -0,0 +1,3 @@
+---
+title: Posts
+---

docs/content/tools/posts/tool_descriptions.md

@@ -0,0 +1,64 @@
+---
+title: March 7th 2025 - Tool Descriptions
+---
+
+# Background
+
+When adding the qrencode tool, the easy part was the container definition. We simply wanted to expose the cli interface of qrencode since most foundation models did not need any additional prompting to use this tool correctly. 
+
+```yaml
+tools:
+  - name: qrencode
+    description: use the qrencode command
+    parameters:
+      type: object
+      properties:
+        args:
+          type: string
+          description: The arguments to pass to qrencode
+    container:
+      image: vonwig/qrencode:latest
+      command:
+        - "{{args}}"
+```
+
+This works well but the output of qrencode is not text. It's an image of course.
+
+## Resources
+
+MCP also supports the creation and update of resources. In order to turn simple tools, like qrencode,
+into resources, we decided to use the convention that any file written to the `/thread` volume of a tool 
+container, will be turned into a resource.  However, qrencode doesn't know this convention.
+
+Our first try at making this easier was to use a prompt.
+
+> Run the qrencode command to generate a QR code and write it to /thread/qrcode.png
+
+This works but the current support for custom prompts in MCP clients is limited. Users were running
+the tool but we were generating tool calls that didn't know about our `/thread/` convention.
+
+## Tool Descriptions
+
+Every tool also has a description. If we change the above command description 
+to be "generate a QR code and write it to /thread/qrcode.png", is that sufficient? Will tool calls 
+try to write new images to /thread so that they'll automatically be turned into resources? This turns out
+to work quite well so we've updated our tool definition. We've removed the prompt and just added a better 
+tool description.
+
+# Summary
+
+Tool descriptions are important!
+
+The tile in the MCP Catalog [extension](https://open.docker.com/extensions/marketplace?extensionId=docker/labs-ai-tools-for-devs) for qrencode will contribute
+just one tool (the qrencode Docker image), and zero prompts. The description of the tool guides the model to 
+write the tool's output in a manner that allows to recognize the creation of new resources.
+
+![Catalog Entry](qrencode-catalog.png)
+
+This makes our prompt to generate a request to create a QR code quite simple. Here's what this looks like
+in Claude Desktop.
+
+> please generate a QR code for www.docker.com
+
+![Claude Entry](claude-qrcode.png)
+