Skip to main content

Tool Definitions

The Tools tab provides an administrative interface for managing the AI tools available on the platform. Tools can originate from code (built-in) or from database overrides (customized). Administrators can search, filter, view, edit, and revert tool configurations.

Interface Overview​

The page header shows the title "Tools" with the number of tools, a help button and a Refresh button that reloads the tool list from the server.

The filter bar sits above the table:

FilterTypeDescription
SearchSearch box with debounce (300ms)Searches by tool name, description, or tags
CategoryFilter chipFilter by tool category (populated dynamically from available categories)
StatusFilter chipFilter by Enabled or Disabled

A filter chip applies as soon as you pick a value; the x on a set chip clears it. Changing any filter automatically resets the pagination to page 1.

Tools Table​

Names and descriptions do not wrap: a long one is cut short with an ellipsis. On a narrow screen the table scrolls sideways inside its own frame instead of squeezing the columns. The table has the following columns:

ColumnDescription
ToolTool name, cut short with an ellipsis if it is long (hover it to see the full name). Up to 2 tags are shown below the name; additional tags display as a "+N" chip
Short descriptionOne line; hover it to see the full text
CategoryTool category as a chip
Source"DB" for database overrides, "Code" for built-in tools
VersionVersion number (e.g., "v1", "v2") or "-" for unversioned tools
UsageTotal invocation count
SuccessSuccess rate as a percentage, or N/A for an unused tool
StatusStatus chip: Enabled (green) or Disabled (grey)

The row actions are in the "..." menu at the end of each row: View details, Edit tool, and, for a tool with a database override, Revert to code defaults.

Edit tool and Revert to code defaults need the settings:manage permission (see Delegated permissions). A delegate with only support:read can open the page and view details, but sees both actions disabled, with the missing permission named on hover.

Actions​

View Details​

The details dialog, titled with the tool name, displays comprehensive tool information:

  • Tool ID -- The unique identifier (monospace font)
  • Category -- Tool category
  • Tags -- All associated tags as chips
  • Short description -- The UI-facing description
  • Full description -- The complete description in a scrollable pane
  • Source -- "Database override" or "Code"
  • Version -- Version number or "N/A"
  • Status -- Enabled or Disabled
  • Usage count -- Total invocations
  • Success rate -- Percentage, or N/A for an unused tool
  • Last updated by -- Editor name and timestamp (if available)

Edit Tool​

The "Edit tool" dialog names the tool at the top and allows modifying three fields:

FieldDescriptionLimits
Short descriptionBrief text for UI display10-500 characters
Full descriptionDetailed description following a 5-section template (DATA TYPE, WHEN TO USE, WHEN NOT TO USE, RETURNS, EXAMPLE QUESTIONS)50-10,000 characters
EnabledToggle switch for enabling or disabling the tool--

The save button is disabled until at least one field has been changed. A banner shows the version that will be created (e.g., "Saving will create version 2" for an existing override, or "This will create the first override (v1) for this code-only tool" for a new override), and the save button repeats it: "Save changes (create v2)" or "Create override (v1)".

Revert to Code Defaults​

For tools with database overrides, choose Revert to code defaults in the row's "..." menu. A confirmation dialog explains that the database override is deleted; confirming with Revert to code defaults restores the tool to its original code-defined configuration.

Pagination​

The table shows 50 tools per page by default. The table footer shows the range on the left (for example "1 to 50 of 120"), with a rows-per-page select (25, 50 or 100) and Previous and Next arrow buttons on the right. The arrows are disabled at the first and last page.

Empty State​

When no tools match the current filters, the table shows "No tools match these filters" with a Clear filters button. When no tools are loaded at all, it shows "No tools are loaded" with a Refresh button.

Best Practices​

  • Use Search for Quick Access -- The debounced search is efficient for locating specific tools by name or description keywords
  • Review Before Editing -- Use the details dialog to review the full tool definition before making changes in the edit dialog
  • Version Awareness -- Each edit creates a new version; review the version number before saving to track change history
  • Revert with Caution -- Reverting to code defaults permanently deletes the database override; this cannot be undone
  • Monitor Success Rates -- Tools with low success rates (below 90%) may need description improvements to help the AI select them correctly