refactor(tools): improve descriptions and behavior for consistency

- Updated tool descriptions for clarity and to align with MODX terminology and best practices.
- Added filters such as `deleted` and `searchable` in GetResources.
- Enhanced return properties (e.g., added public URL to GetResources).
- Refined templates and chunks search logic by removing redundant category filters.
- Improved user confirmation instructions across resource and element creation tools.

Author: Mark-H

core/components/modai/src/Tools/CreateCategory.php

@@ -16,7 +16,7 @@ public static function getSuggestedName(): string
 
     public static function getDescription(): string
     {
-        return "ALWAYS ask for explicit user confirmation in a separate message before calling this function, even if user asks directly for creating categories, you HAVE TO ask for their confirmation in a separate message, provide a list of name, and parent category name that you want to create. If needed, use an appropriate tool to first list available categories. Creates new MODX categories and returns their IDs.";
+        return "Creates a new Category that any element (chunks or templates) can be grouped by. Use the get categories tool first to check if a category already exists. When successful, this tool returns the category ID to use when creating chunks or templates.";
     }
 
     public static function getParameters(): array

core/components/modai/src/Tools/CreateChunk.php

@@ -16,7 +16,7 @@ public static function getSuggestedName(): string
 
     public static function getDescription(): string
     {
-        return "ALWAYS ask for explicit user confirmation in a separate message before calling this function, even if user asks directly for creating chunk, you HAVE TO ask for their confirmation in a separate message, provide a list of name, description and category name, DON'T output content, that you want to create. If needed, use an appropriate tool to first create categories, wait for it's response and then continue with calling this tool. Creates new MODX chunks. Don't ask for the parameters, unless they were already provided.";
+        return "Creates a new Chunk, which is a reusable piece of HTML or other code that can be inserted into pages, templates, or other elements. Use when explicitly asked to create a chunk or when creating templates to break up reusable pieces. Once created, chunks can be rendered by using [[\$name_of_chunk]] in a template or elsewhere. ALWAYS ask for explicit user confirmation with the chunk name, description, and category name in a separate message BEFORE calling this function.";
     }
 
     public static function getParameters(): array

core/components/modai/src/Tools/CreateResource.php

@@ -16,7 +16,7 @@ public static function getSuggestedName(): string
 
     public static function getDescription(): string
     {
-        return "ALWAYS ask for explicit user confirmation in a separate message before calling this function, even if user asks directly for creating resource (page), you HAVE TO ask for their confirmation in a separate message, provide a list of page titles, DON'T output content, that you want to create. If needed, use an appropriate tool to first create categories or templates, wait for it's response and then continue with calling this tool. Creates new MODX resource (page). Don't ask for the parameters, if they were not provided, make them up.";
+        return "Creates a new resource, or page, on the website. ALWAYS ask for explicit user confirmation in a separate message before calling this function, even if user asks directly to create a resource, ask the user to confirm the resource before calling the tool with the information you intend to use. ";
     }
 
     public static function getParameters(): array

core/components/modai/src/Tools/CreateTemplate.php

@@ -16,7 +16,7 @@ public static function getSuggestedName(): string
 
     public static function getDescription(): string
     {
-        return "ALWAYS ask for explicit user confirmation in a separate message before calling this function, even if user asks directly for creating template, you HAVE TO ask for their confirmation in a separate message, provide a list of name, description and category name, DON'T output content, that you want to create. If needed, use an appropriate tool to first create categories, wait for it's response and then continue with calling this tool. Creates new MODX templates. Don't ask for the parameters, if they were not provided, make them up.";
+        return "Creates a new template for the website, which can be assigned to resources to determine how they are rendered in the frontend. Only use when explicitly asked to create a new template, and always check if appropriate templates already exist first. Always ask for explicit user confirmation in a separate message, providing the user with the template name and a summary of what the contents would be, BEFORE calling this function. Do NOT output the full template content. When generating template content you MUST make sure it uses the MODX templating syntax.";
     }
 
     public static function getParameters(): array

core/components/modai/src/Tools/GetCategories.php

@@ -16,7 +16,7 @@ public static function getSuggestedName(): string
 
     public static function getDescription(): string
     {
-        return "Get all categories in the current MODX Revolution database. Categories are used to separate chunks, snippets, templates, template variables and plugins. Each category can have parent to create a tree like structure. If parent is 0, the category is at root level.";
+        return "Lists all categories used to group templates and chunks. Each category can have a parent to create a tree like structure. If parent is 0, the category is at root level.";
     }
 
     public static function getParameters(): array

core/components/modai/src/Tools/GetChunks.php

@@ -16,7 +16,7 @@ public static function getSuggestedName(): string
 
     public static function getDescription(): string
     {
-        return "Get or search chunks (modChunk) from current MODX Revolution database. You can provide optional parameters to return only specific chunks - query: search chunks by name, broad match; name: return chunk with a given name; id: return chunk with a given ID. You'll receive an array of chunks with a properties of id, name, description, category (ID of a category) and optionally content.";
+        return "Find existing chunks in the website. Chunks are reusable pieces of HTML or other content. The tool can search for Get or search chunks (modChunk) from current MODX Revolution database. You can provide optional parameters to return only specific chunks - query: search chunks by name, broad match; name: return chunk with a given name; id: return chunk with a given ID. You'll receive an array of chunks with a properties of id, name, description, category (ID of a category) and optionally content.";
     }
 
     public static function getParameters(): array
@@ -26,26 +26,22 @@ public static function getParameters(): array
             'properties' => [
                 'query' => [
                     'type' => 'string',
-                    "description" => 'Search by category name'
+                    "description" => 'Simple wild-card search on the chunk name'
                 ],
                 'name' => [
                     'type' => 'string',
-                    "description" => 'Get single chunk by name'
+                    "description" => 'Get a single chunk by name if you already know the name'
                 ],
                 'id' => [
                     'type' => 'number',
-                    "description" => 'Get single chunk by ID'
+                    "description" => 'Get a single chunk by its ID'
                 ],
                 'categories' => [
                     'type' => 'array',
                     'items' => [
                         'type' => 'number',
                     ],
-                    "description" => 'Search chunks by multiple category IDs'
-                ],
-                'category' => [
-                    'type' => 'number',
-                    "description" => 'Search chunks by category ID'
+                    "description" => 'List chunks that are assigned to the provided category ID(s)'
                 ],
                 'returnContent' => [
                     'type' => 'boolean',
@@ -97,12 +93,6 @@ public function runTool($parameters): string
                 ];
             }
 
-            if (!empty($parameters['category'])) {
-                $where[] = [
-                    'category' => $parameters['category'],
-                ];
-            }
-
             if (!empty($parameters['categories'])) {
                 $where[] = [
                     'category:IN' => $parameters['categories'],

core/components/modai/src/Tools/GetResourceDetail.php

@@ -17,7 +17,7 @@ public static function getSuggestedName(): string
 
     public static function getDescription(): string
     {
-        return "Use this tool to get more information about a resource, concept, or service you are unfamiliar with from of an array of integer resource IDs. Use the appropriate tool first to identify relevant resources on a topic. The tool will retrieve metadata, like title, description, published state, and last edit dates, as well as full HTML-formatted content. Provide at least one, or multiple resource IDs.";
+        return "Get more information about a resource, page, concept, or service you are unfamiliar with from of an array of integer resource IDs. Use the appropriate tool first to identify relevant resources on a topic. The tool will retrieve metadata, like title, description, published state, and last edit dates, as well as full HTML-formatted content. Provide at least one, or multiple resource IDs.";
     }
 
     public static function getParameters(): array
@@ -31,7 +31,7 @@ public static function getParameters(): array
                     'items' => [
                         'type' => 'number'
                     ],
-                    "description" => 'Array of IDs of resources to get details for.'
+                    "description" => 'Array of IDs of resources to load.'
                 ],
             ],
             "required" => ['ids']

core/components/modai/src/Tools/GetResources.php

@@ -17,7 +17,7 @@ public static function getSuggestedName(): string
 
     public static function getDescription(): string
     {
-        return "Get or search resources (modResource) from current MODX Revolution database. You can provide optional parameters to return only specific resources. You'll receive an array of resources with a properties of id, pagetitle, parent (ID of another resource), template (ID of a template) and edit url.";
+        return "Search for resources, also called pages or documents, on the website. You can provide optional parameters to return only specific resources. Returns matching resources with their id, pagetitle, parent resource ID, template ID, edit url, and public URL.";
     }
 
     public static function getParameters(): array
@@ -63,6 +63,8 @@ public function runTool($parameters): string
         }
 
         $where = [];
+        $where['deleted'] = false;
+        $where['searchable'] = true;
 
         if (is_array($parameters)) {
             if (!empty($parameters['query'])) {
@@ -97,6 +99,7 @@ public function runTool($parameters): string
                 'parent' => $resource->get('parent'),
                 'template' => $resource->get('template'),
                 'edit_url' => $this->modx->config['manager_url'] . '?a=resource/update&id=' . $resource->get('id'),
+                'url' => $this->modx->makeUrl($resource->get('id'), '', '', 'full'),
             ];
 
             $output[] = $arr;

core/components/modai/src/Tools/GetTemplates.php

@@ -17,7 +17,7 @@ public static function getSuggestedName(): string
 
     public static function getDescription(): string
     {
-        return "Get or search templates (modTemplate) from current MODX Revolution database. You can provide optional parameters to return only specific templates. You'll receive an array of templates with a properties of id, name, description, category (ID of a category) and optionally content.";
+        return "Find templates available in the website. Templates are assigned to resources and determine how a page is rendered to visitors. You can provide optional parameters to return only specific templates. You'll receive an array of templates with a properties of id, name, description, category (ID of a category) and optionally content.";
     }
 
     public static function getParameters(): array
@@ -27,30 +27,26 @@ public static function getParameters(): array
             'properties' => [
                 'query' => [
                     'type' => 'string',
-                    "description" => 'Search templates by name'
+                    "description" => 'Search templates by a simple search on the name'
                 ],
                 'name' => [
                     'type' => 'string',
-                    "description" => 'Get single template by name'
+                    "description" => 'Get a template by its exact name'
                 ],
                 'id' => [
                     'type' => 'number',
-                    "description" => 'Get single template by ID'
+                    "description" => 'Get a template by its ID'
                 ],
                 'categories' => [
                     'type' => 'array',
                     'items' => [
                         'type' => 'number',
                     ],
-                    "description" => 'Search templates by multiple category IDs'
-                ],
-                'category' => [
-                    'type' => 'number',
-                    "description" => 'Search templates by category ID'
+                    "description" => 'List templates within the provided categories'
                 ],
                 'returnContent' => [
                     'type' => 'boolean',
-                    "description" => 'Return template\'s content, use this only when you are tasked with updating template'
+                    "description" => 'Include the template content in the response, use this only when you are tasked with updating template'
                 ],
             ],
             "required" => []
@@ -97,12 +93,6 @@ public function runTool($parameters): string
                 ];
             }
 
-            if (!empty($parameters['category'])) {
-                $where[] = [
-                    'category' => $parameters['category'],
-                ];
-            }
-
             if (!empty($parameters['categories'])) {
                 $where[] = [
                     'category:IN' => $parameters['categories'],