Discourse Meta
Us.anthropic.claude-3-7-sonnet-20250219-v1:0

Discourse AI Tools Documentation

sam

Discourse discourse-ai has a tool system, read source for all tools and produce a document that explains what each tool does

GitHub_Helper_bot
Thinking...I'll need to search for and examine the tool system in the Discourse discourse-ai repository. Let me start by searching for files related to tools.

I should search for files that might contain information about the tools system. Let me look for files with “tool” in their name or path.

GitHub search files

Searched for 'tool, tools' in discourse/discourse-ai/main

Thinking...I need to examine the actual tool implementation files to understand what each tool does. The search results show a lot of files related to AI tools in the discourse-ai repository. The most relevant files would be in the `lib/personas/tools/` directory, which seems to contain individual tool implementations.

Let me retrieve the content of the base tool class first to understand the structure, and then examine some of the specific tool implementations.

Let me fetch the base tool class first to understand the structure, and then I’ll look at the specific tool implementations.

GitHub file content

Retrieved content of lib/personas/tools/tool.rb from discourse/discourse-ai@main

Thinking...I need to look at the specific tool implementations to understand what each tool does. Let's fetch the content of the tool implementation files in the lib/personas/tools directory to understand each tool's functionality.

Let’s first check the directory structure of the tools to see all the available tools:

GitHub file content

Retrieved content of lib/personas/tools/create_artifact.rb, lib/personas/tools/custom.rb, lib/personas/tools/dall_e.rb, lib/personas/tools/db_schema.rb, lib/personas/tools/discourse_meta_search.rb, lib/personas/tools/github_file_content.rb, lib/personas/tools/github_pull_request_diff.rb, lib/personas/tools/github_search_code.rb, lib/personas/tools/github_search_files.rb, lib/personas/tools/google.rb, lib/personas/tools/image.rb, lib/personas/tools/javascript_evaluator.rb, lib/personas/tools/list_categories.rb, lib/personas/tools/list_tags.rb, lib/personas/tools/random_picker.rb, lib/personas/tools/read.rb, lib/personas/tools/read_artifact.rb, lib/personas/tools/search.rb, lib/personas/tools/search_settings.rb, lib/personas/tools/setting_context.rb, lib/personas/tools/summarize.rb, lib/personas/tools/time.rb, lib/personas/tools/update_artifact.rb, lib/personas/tools/web_browser.rb from discourse/discourse-ai@main

Thinking...I need to continue retrieving the content of the web_browser.rb file, as it was truncated. Let me get the rest of that file and then also check for any important files I might have missed in my initial exploration.
GitHub file content

Retrieved content of lib/personas/tools/web_browser.rb, lib/personas/tools/option.rb, lib/personas/tool_runner.rb from discourse/discourse-ai@main

Thinking...Based on the source code I've reviewed, I'll create a comprehensive documentation of the tools available in the Discourse AI plugin. I'll organize the document to explain:
  1. What each tool does
  2. The parameters it accepts
  3. Any special behavior or functionality
  4. Use cases where applicable

Let me go through each tool systematically:

Discourse AI Tools Documentation

This document provides an overview of all tools available in the Discourse AI plugin. Each tool serves a specific purpose and can be used by AI personas to perform different tasks.

Base Tool Structure

All tools in Discourse AI inherit from the base Tool class, which provides common functionality:

  • HTTP request handling with safety limits
  • Parameter validation
  • Text truncation for large responses
  • Standardized response formatting

Available Tools

1. create_artifact

Purpose: Creates interactive web artifacts based on specifications.
Parameters:

  • name: A name for the artifact (max 255 chars)
  • specification: Detailed specifications for the artifact (functionality, design, behavior)

The tool generates complete HTML, CSS, and JavaScript code based on the specification, creating an interactive web component that can be embedded in posts.

2. custom

Purpose: Allows for creation of custom tools via the admin interface.
This is a special tool class that serves as a wrapper for user-defined custom tools. It supports custom contexts and can be extended through the UI.

3. dall_e

Purpose: Generates images using OpenAI’s DALL-E model.
Parameters:

  • prompts: Array of text descriptions (up to 4 prompts)
  • aspect_ratio: Optional - “tall”, “square”, or “wide” (default is square)

The tool returns uploaded images in a grid format based on the provided prompts.

4. db_schema

Purpose: Retrieves database schema information for specified tables.
Parameters:

  • tables: Comma-separated list of database tables to examine

Returns column names and data types for the specified tables.

5. discourse_meta_search

Purpose: Searches topics on meta.discourse.org.
Parameters:

  • search_query: Keywords to search for
  • user: Optional - filter by username
  • order: Optional - search result order (latest, latest_topic, oldest, views, likes)
  • Various other filtering options: max_posts, tags, category, before, after, status

Provides search results from meta.discourse.org with links and context.

6. github_file_content

Purpose: Retrieves content of files from GitHub repositories.
Parameters:

  • repo_name: Repository name (e.g., ‘discourse/discourse’)
  • file_paths: Array of file paths to retrieve
  • branch: Optional - branch or commit SHA (default: ‘main’)

Returns the content of the specified files, with truncation for large files.

7. github_pull_request_diff

Purpose: Retrieves and processes the diff for a GitHub pull request.
Parameters:

  • repo: Repository name in ‘owner/repo’ format
  • pull_id: The ID of the pull request

Returns the diff with metadata about the PR, intelligently handling large diffs by truncating oversized files.

8. github_search_code

Purpose: Searches for code within a GitHub repository.
Parameters:

  • repo: Repository name in ‘owner/repo’ format
  • query: Search query (function name, variable, code snippet)

Returns matching code fragments with their file locations.

9. github_search_files

Purpose: Searches for files in a GitHub repository by name/path.
Parameters:

  • repo: Repository name in ‘owner/repo’ format
  • keywords: Array of keywords to match in file paths or names
  • branch: Optional - branch or commit SHA

Returns a list of matching file paths within the repository.

10. google

Purpose: Performs Google searches for up-to-date information.
Parameters:

  • query: The search query

Provides formatted search results from Google with titles, snippets, and links.

11. image

Purpose: Generates images using Stability AI’s models.
Parameters:

  • prompts: Array of text descriptions (up to 4 prompts)
  • seeds: Optional - seeds for consistent style
  • aspect_ratio: Optional - various aspect ratio options

Similar to dall_e but using Stability AI’s image generation system.

12. javascript_evaluator

Purpose: Evaluates JavaScript code safely using MiniRacer.
Parameters:

  • script: The JavaScript code to evaluate

Executes JavaScript with safety constraints (timeout, memory limits) and returns the result.

13. list_categories

Purpose: Lists forum categories.
Parameters: None

Returns information about categories on the Discourse instance including name, slug, description and post counts.

14. list_tags

Purpose: Lists the most popular tags.
Parameters: None

Returns the 100 most popular tags on the Discourse instance with their topic counts.

15. random_picker

Purpose: Makes random selections from provided options.
Parameters:

  • options: Array of options that can be ranges (e.g., ‘1-6’) or comma-separated lists

Useful for making random decisions or choices when needed by the AI.

16. read

Purpose: Reads content from a topic or specific posts.
Parameters:

  • topic_id: ID of the topic to read
  • post_numbers: Optional - specific post numbers to read

Returns the content of the topic or specific posts with metadata.

17. read_artifact

Purpose: Converts external web content or existing artifacts into a local artifact.
Parameters:

  • url: URL of the artifact or webpage to read

Can import Discourse artifacts from other sites or convert general webpages into artifacts.

18. search

Purpose: Searches topics in the current Discourse instance.
Parameters:

  • search_query: Keywords to search for
  • Various filtering options similar to discourse_meta_search

Provides comprehensive search results from the current Discourse instance.

19. search_settings

Purpose: Searches through Discourse site settings.
Parameters:

  • query: Comma-delimited list of settings to search for

Returns matching site settings with descriptions when appropriate.

20. setting_context

Purpose: Provides detailed context about a Discourse site setting.
Parameters:

  • setting_name: The name of the site setting

Returns the setting description plus context from the codebase showing where and how it’s used.

21. summarize

Purpose: Creates summaries of topics.
Parameters:

  • topic_id: The ID of the topic to summarize
  • guidance: Optional - specific guidance on how to summarize

Produces a coherent summary of a topic, handling long topics by breaking them into sections.

22. time

Purpose: Provides the current time in a specified timezone.
Parameters:

  • timezone: A Ruby-compatible timezone string

Returns the current date and time in the specified timezone.

23. update_artifact

Purpose: Updates an existing web artifact.
Parameters:

  • artifact_id: The ID of the artifact to update
  • instructions: Clear instructions on what changes to make
  • version: Optional - specific version to update

Allows modifying existing artifacts with change tracking and versioning.

24. web_browser

Purpose: Retrieves and processes content from web pages.
Parameters:

  • url: The URL of the web page to visit

Fetches a webpage, extracts the main content, and returns it as plain text.

Tool Runner and Options System

The Discourse AI plugin uses a ToolRunner to execute tools within a sandboxed environment. This provides:

  1. Safety constraints (memory limits, timeouts)
  2. JavaScript execution environment for custom tools
  3. HTTP request limitations
  4. Context preservation between tool calls

Tools can also define Options which allow configuration at the persona level, customizing behavior without changing the core tool functionality.

This document provides a comprehensive overview of the tools available in the Discourse AI plugin and how they function. Each tool is designed to extend the capabilities of AI personas, enabling them to interact with external systems, retrieve information, and create rich content.