Update x-ai-description for 44 tools to improve LLM tool selection (#16579)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

awx/api/openapi_ai_descriptions.json

@@ -1,10 +1,10 @@
 {
   "activity_stream_retrieve": "Retrieve an audit trail entry for tracking all changes within the system",
   "ad_hoc_commands_activity_stream_list": "List activity stream of an ad hoc command",
-  "ad_hoc_commands_create": "Create an ad hoc command",
+  "ad_hoc_commands_create": "Run an ad hoc command. Executes a single Ansible module on specified hosts without a playbook.",
   "ad_hoc_commands_destroy": "Delete an ad hoc command",
   "ad_hoc_commands_events_list": "List events of an ad hoc command",
-  "ad_hoc_commands_list": "List ad hoc commands",
+  "ad_hoc_commands_list": "Returns a paginated list of all ad hoc command runs. Ad hoc commands execute a single Ansible module without a playbook.",
   "ad_hoc_commands_notifications_list": "List notifications of an ad hoc command",
   "ad_hoc_commands_retrieve": "Retrieve an ad hoc command",
   "ad_hoc_commands_stdout_retrieve": "Retrieve a stdout output of an ad hoc command",
@@ -30,7 +30,7 @@
   "constructed_inventories_update": "Update a constructed inventory",
   "credential_input_sources_create": "Create a credential input source",
   "credential_input_sources_destroy": "Delete a credential input source",
-  "credential_input_sources_list": "List credential input sources",
+  "credential_input_sources_list": "Returns a paginated list of external secret management input sources.",
   "credential_input_sources_partial_update": "Update a credential input source",
   "credential_input_sources_retrieve": "Retrieve a credential input source",
   "credential_input_sources_update": "Update a credential input source",
@@ -39,7 +39,7 @@
   "credential_types_retrieve": "Retrieve a credential type",
   "credential_types_test_retrieve": "Retrieve single test for a credential_type",
   "credentials_destroy": "Delete a credential",
-  "credentials_input_sources_create": "Create new source for a credential",
+  "credentials_input_sources_create": "Link an external secret source (Vault, CyberArk) to a credential field.",
   "credentials_input_sources_list": "List all sources for a credential",
   "credentials_object_roles_list": "List roles of a credential",
   "credentials_owner_teams_list": "List all teams for a credential",
@@ -57,7 +57,7 @@
   "feature_flags_states_list": "List all feature flags states",
   "feature_flags_states_retrieve": "Retrieve single feature flags state",
   "groups_activity_stream_list": "List activity stream for a group",
-  "groups_ad_hoc_commands_create": "Create an ad hoc command for a group",
+  "groups_ad_hoc_commands_create": "Run an ad hoc command against all hosts in a group. Executes a single Ansible module without a playbook.",
   "groups_ad_hoc_commands_list": "List ad hoc commands for a group",
   "groups_all_hosts_list": "List all hosts for a group",
   "groups_children_create": "Create new child for a group",
@@ -80,10 +80,10 @@
   "host_metrics_retrieve": "Retrieve a host metric",
   "hosts_activity_stream_list": "List activity stream for a host",
   "hosts_ad_hoc_command_events_list": "List events of ad hoc command of a host",
-  "hosts_ad_hoc_commands_create": "Create an ad hoc command of a host",
+  "hosts_ad_hoc_commands_create": "Run an ad hoc command against a specific host. Executes a single Ansible module without a playbook.",
   "hosts_ad_hoc_commands_list": "List ad hoc commands of a host",
   "hosts_all_groups_list": "List all groups for a host",
-  "hosts_create": "Create a host",
+  "hosts_create": "Create a host entry in an inventory. Hosts are managed nodes that Ansible automation can execute against.",
   "hosts_groups_create": "Create the list of groups a host is directly a member of",
   "hosts_groups_list": "List the list of groups a host is directly a member of",
   "hosts_inventory_sources_list": "List inventory sources of a host",
@@ -112,11 +112,11 @@
   "instances_retrieve": "Retrieve an instance",
   "instances_update": "Update an instance",
   "inventories_access_list_list": "List users who can access the inventory",
-  "inventories_ad_hoc_commands_create": "Create an ad hoc command for an inventory",
+  "inventories_ad_hoc_commands_create": "Run an ad hoc command against all hosts in an inventory. Executes a single Ansible module without a playbook.",
   "inventories_ad_hoc_commands_list": "List ad hoc command for an inventory",
   "inventories_copy_create": "Create a copy of an inventory",
   "inventories_copy_retrieve": "Retrieve a copy of an inventory",
-  "inventories_create": "Create an inventory",
+  "inventories_create": "Create an inventory to define the set of hosts that jobs can target.",
   "inventories_destroy": "Delete an inventory",
   "inventories_groups_create": "Create a group of an inventory",
   "inventories_groups_list": "List groups of an inventory",
@@ -137,7 +137,7 @@
   "inventories_variable_data_retrieve": "Retrieve single datum for an inventory",
   "inventories_variable_data_update": "Update existing datum for an inventory",
   "inventory_sources_activity_stream_list": "List activity stream of an inventory source",
-  "inventory_sources_create": "Create an inventory source",
+  "inventory_sources_create": "Create an inventory source to sync host data from external systems.",
   "inventory_sources_credentials_create": "Create a credential of an inventory source",
   "inventory_sources_credentials_list": "List credentials of an inventory source",
   "inventory_sources_destroy": "Delete an inventory source",
@@ -172,20 +172,20 @@
   "job_templates_activity_stream_list": "List activity stream of a job template",
   "job_templates_copy_create": "Create a copy a job template",
   "job_templates_copy_retrieve": "Retrieve a copy a job template",
-  "job_templates_create": "Create a job template",
-  "job_templates_credentials_create": "Create a credential of a job template",
+  "job_templates_create": "Create a new job template. A job template defines the playbook, inventory, credentials, variables, and settings needed to launch an automation job.",
+  "job_templates_credentials_create": "Associate a credential with a job template. The credential will be used when launching jobs from this template.",
   "job_templates_credentials_list": "List credentials of a job template",
   "job_templates_destroy": "Delete a job template",
   "job_templates_instance_groups_create": "Create an instance group of a job template",
   "job_templates_instance_groups_list": "List instance groups of a job template",
   "job_templates_jobs_list": "List jobs of a job template",
   "job_templates_labels_list": "List labels of a job template",
-  "job_templates_launch_retrieve": "Retrieve single launch for a job_template",
-  "job_templates_notification_templates_error_create": "Create a notification templates triggered on job error",
+  "job_templates_launch_retrieve": "Returns the launch configuration and required fields needed to launch a specific job template by ID.",
+  "job_templates_notification_templates_error_create": "Attach a notification template to trigger when a job from this template fails.",
   "job_templates_notification_templates_error_list": "List notification templates triggered on job error",
-  "job_templates_notification_templates_started_create": "Create a notification templates triggered on job start",
+  "job_templates_notification_templates_started_create": "Attach a notification template to trigger when a job from this template starts.",
   "job_templates_notification_templates_started_list": "List notification templates triggered on job start",
-  "job_templates_notification_templates_success_create": "Create a notification templates triggered on job success",
+  "job_templates_notification_templates_success_create": "Attach a notification template to trigger when a job from this template succeeds.",
   "job_templates_notification_templates_success_list": "List notification templates triggered on job success",
   "job_templates_object_roles_list": "List roles of a job template",
   "job_templates_partial_update": "Update a job template",
@@ -200,11 +200,11 @@
   "jobs_create_schedule_retrieve": "Retrieve single schedule for a job",
   "jobs_credentials_list": "List credentials of a job",
   "jobs_destroy": "Delete a job",
-  "jobs_job_events_list": "List job events of a job",
-  "jobs_job_host_summaries_list": "List job host summaries of a job",
+  "jobs_job_events_list": "Returns a paginated list of execution events for a specific job run. Use to inspect task-level output.",
+  "jobs_job_host_summaries_list": "Returns a paginated list of per-host result summaries (ok, changed, failed counts) for a specific job.",
   "jobs_labels_list": "List labels of a job",
   "jobs_notifications_list": "List notifications of a job",
-  "jobs_relaunch_retrieve": "Retrieve single relaunch for a job",
+  "jobs_relaunch_retrieve": "Returns the list of credential passwords required to relaunch a specific job by ID.",
   "jobs_retrieve": "Retrieve a job",
   "labels_create": "Create a label",
   "labels_list": "List labels",
@@ -226,11 +226,11 @@
   "organizations_credentials_create": "Create a credential of an organization",
   "organizations_credentials_list": "List credentials of an organization",
   "organizations_destroy": "Delete an organization",
-  "organizations_execution_environments_create": "Create an execution environment of an organization",
+  "organizations_execution_environments_create": "Associate an execution environment with an organization by default.",
   "organizations_execution_environments_list": "List execution environments of an organization",
-  "organizations_galaxy_credentials_create": "Create new credential for an organization",
+  "organizations_galaxy_credentials_create": "Associate a Galaxy credential with an organization for syncing content.",
   "organizations_galaxy_credentials_list": "List all credentials for an organization",
-  "organizations_instance_groups_create": "Create an instance group of an organization",
+  "organizations_instance_groups_create": "Associate an instance group with an organization.",
   "organizations_instance_groups_list": "List instance groups of an organization",
   "organizations_inventories_list": "List inventories of an organization",
   "organizations_job_templates_create": "Create a job template of an organization",
@@ -271,7 +271,7 @@
   "projects_activity_stream_list": "List activity stream for a project",
   "projects_copy_create": "Create a copy of a project",
   "projects_copy_retrieve": "Retrieve a copy of a project",
-  "projects_create": "Create a project",
+  "projects_create": "Create a new project. Projects represent a collection of Ansible playbooks and related files sourced from a version control system.",
   "projects_destroy": "Delete a project",
   "projects_inventories_retrieve": "Retrieve an inventory from a project",
   "projects_notification_templates_error_create": "Create a notification template for project error events",
@@ -282,7 +282,7 @@
   "projects_notification_templates_success_list": "List notification templates for project success events",
   "projects_object_roles_list": "List roles of a project",
   "projects_partial_update": "Update a project",
-  "projects_playbooks_retrieve": "Retrieve single playbook for a project",
+  "projects_playbooks_retrieve": "Returns the list of playbook files available in a specific project by ID.",
   "projects_project_updates_list": "List project updates of a project",
   "projects_retrieve": "Retrieve a project",
   "projects_schedules_create": "Create a schedule of a project",
@@ -318,7 +318,7 @@
   "roles_retrieve": "Retrieve a role",
   "roles_teams_list": "List teams with a role",
   "roles_users_list": "List users with a role",
-  "schedules_create": "Create a schedule",
+  "schedules_create": "Create a schedule for recurring automated execution of a job template, workflow job template, project sync, inventory sync or management job.",
   "schedules_credentials_create": "Create a credential of a schedule",
   "schedules_credentials_list": "List credentials of a schedule",
   "schedules_destroy": "Delete a schedule",
@@ -351,7 +351,7 @@
   "service_index_role_user_assignments_unassign_create": "Create new service index role user assignments unassign",
   "settings_destroy": "Delete existing setting",
   "settings_logging_test_create": "Create new settings logging test",
-  "settings_retrieve": "Retrieve single setting",
+  "settings_retrieve": "Returns Controller settings for a specific category by slug.",
   "settings_update": "Update existing setting",
   "system_job_templates_jobs_list": "List system jobs of a system job template",
   "system_job_templates_notification_templates_error_create": "Create a notification templates triggered on system job error",
@@ -384,7 +384,7 @@
   "teams_update": "Update a team",
   "teams_users_create": "Create a user of a team",
   "teams_users_list": "List users of a team",
-  "unified_job_templates_list": "List unified job templates",
+  "unified_job_templates_list": "Returns a paginated list of all unified job templates. Combines job templates, workflow templates, and project updates in a single view.",
   "unified_jobs_list": "List unified jobs",
   "users_access_list_list": "List users who can access the user",
   "users_activity_stream_list": "List activity stream for a user",

awx/api/views/__init__.py

@@ -890,7 +890,7 @@ class ExecutionEnvironmentList(ListCreateAPIView):
     def get(self, request, *args, **kwargs):
         return super().get(request, *args, **kwargs)
 
-    @extend_schema_if_available(extensions={"x-ai-description": "Create a new execution environment. Once associated with JT/org/etc"})
+    @extend_schema_if_available(extensions={"x-ai-description": "Create a new execution environment container image reference."})
     def post(self, request, *args, **kwargs):
         return super().post(request, *args, **kwargs)
 
@@ -963,7 +963,9 @@ class ProjectList(ListCreateAPIView):
     serializer_class = serializers.ProjectSerializer
     resource_purpose = 'projects'
 
-    @extend_schema_if_available(extensions={"x-ai-description": "A list of projects."})
+    @extend_schema_if_available(
+        extensions={"x-ai-description": "Returns a paginated list of all projects. Projects represent playbook collections sourced from version control."}
+    )
     def get(self, request, *args, **kwargs):
         return super().get(request, *args, **kwargs)
 
@@ -1385,7 +1387,7 @@ class CredentialTypeList(ListCreateAPIView):
     serializer_class = serializers.CredentialTypeSerializer
     resource_purpose = 'credential types'
 
-    @extend_schema_if_available(extensions={"x-ai-description": "A list of credential types"})
+    @extend_schema_if_available(extensions={"x-ai-description": "Returns a paginated list of all credential types (machine, vault, cloud, etc.)."})
     def get(self, request, *args, **kwargs):
         return super().get(request, *args, **kwargs)
 
@@ -2071,11 +2073,11 @@ class GroupList(ListCreateAPIView):
     serializer_class = serializers.GroupSerializer
     resource_purpose = 'groups'
 
-    @extend_schema_if_available(extensions={"x-ai-description": "A list of groups."})
+    @extend_schema_if_available(extensions={"x-ai-description": "Returns a paginated list of all host groups."})
     def get(self, request, *args, **kwargs):
         return super().get(request, *args, **kwargs)
 
-    @extend_schema_if_available(extensions={"x-ai-description": "Create a new group."})
+    @extend_schema_if_available(extensions={"x-ai-description": "Create a new host group within an inventory."})
     def post(self, request, *args, **kwargs):
         return super().post(request, *args, **kwargs)
 
@@ -2281,7 +2283,7 @@ class HostVariableData(BaseVariableData):
     serializer_class = serializers.HostVariableDataSerializer
     resource_purpose = 'variable data for a host'
 
-    @extend_schema_if_available(extensions={"x-ai-description": "The extra variable configuration for this host."})
+    @extend_schema_if_available(extensions={"x-ai-description": "Returns the extra variables (YAML/JSON) configured for a specific host by ID."})
     def get(self, request, *args, **kwargs):
         return super().get(request, *args, **kwargs)
 
@@ -2575,7 +2577,9 @@ class InventorySourceUpdateView(RetrieveAPIView):
     serializer_class = serializers.InventorySourceUpdateSerializer
     resource_purpose = 'update an inventory source'
 
-    @extend_schema_if_available(extensions={"x-ai-description": "Sync the inventory source"})
+    @extend_schema_if_available(
+        extensions={"x-ai-description": "Trigger a sync of an inventory source by ID. Pulls latest host data from the external source."}
+    )
     def post(self, request, *args, **kwargs):
         obj = self.get_object()
         serializer = self.get_serializer(instance=obj, data=request.data)
@@ -2635,7 +2639,11 @@ class JobTemplateList(ListCreateAPIView):
     always_allow_superuser = False
     resource_purpose = 'job templates'
 
-    @extend_schema_if_available(extensions={"x-ai-description": "A list of job templates."})
+    @extend_schema_if_available(
+        extensions={
+            "x-ai-description": "Returns a paginated list of all job templates. A job template defines the playbook, inventory, credentials, and settings for launching a job."
+        }
+    )
     def get(self, request, *args, **kwargs):
         return super().get(request, *args, **kwargs)
 
@@ -2724,7 +2732,9 @@ class JobTemplateLaunch(RetrieveAPIView):
 
         return modern_data
 
-    @extend_schema_if_available(extensions={"x-ai-description": "Launch the job template"})
+    @extend_schema_if_available(
+        extensions={"x-ai-description": "Launch a job from a job template by ID. Starts execution of the playbook defined in the template."}
+    )
     def post(self, request, *args, **kwargs):
         obj = self.get_object()
 
@@ -2807,7 +2817,11 @@ class JobTemplateSurveySpec(GenericAPIView):
         obj = self.get_object()
         return Response(obj.display_survey_spec())
 
-    @extend_schema_if_available(extensions={"x-ai-description": "Update job template survey specification"})
+    @extend_schema_if_available(
+        extensions={
+            "x-ai-description": "Create or update the survey specification for a job template. Surveys prompt users for input variables at launch time."
+        }
+    )
     def post(self, request, *args, **kwargs):
         obj = self.get_object()
 
@@ -3423,7 +3437,11 @@ class WorkflowJobTemplateList(ListCreateAPIView):
     always_allow_superuser = False
     resource_purpose = 'workflow job templates'
 
-    @extend_schema_if_available(extensions={"x-ai-description": "A list of workflow job templates."})
+    @extend_schema_if_available(
+        extensions={
+            "x-ai-description": "Returns a paginated list of all workflow job templates. Workflow templates chain multiple node types—job templates, other workflows, project syncs, inventory syncs, management jobs, and approval gates—into a single automated workflow."
+        }
+    )
     def get(self, request, *args, **kwargs):
         return super().get(request, *args, **kwargs)
 
@@ -3590,7 +3608,9 @@ class WorkflowJobRelaunch(GenericAPIView):
     def get(self, request, *args, **kwargs):
         return Response({})
 
-    @extend_schema_if_available(extensions={"x-ai-description": "Relaunch a workflow job"})
+    @extend_schema_if_available(
+        extensions={"x-ai-description": "Relaunch a previously completed or failed workflow job using the same parameters as the original run."}
+    )
     def post(self, request, *args, **kwargs):
         obj = self.get_object()
         if obj.is_sliced_job:
@@ -3954,7 +3974,7 @@ class JobRelaunch(RetrieveAPIView):
                 self.permission_denied(request, message=messages['detail'])
         return super(JobRelaunch, self).check_object_permissions(request, obj)
 
-    @extend_schema_if_available(extensions={"x-ai-description": "Relaunch a job"})
+    @extend_schema_if_available(extensions={"x-ai-description": "Relaunch a previously completed or failed job using the same parameters as the original run."})
     def post(self, request, *args, **kwargs):
         obj = self.get_object()
         context = self.get_serializer_context()
@@ -4724,7 +4744,7 @@ class NotificationTemplateList(ListCreateAPIView):
     def get(self, request, *args, **kwargs):
         return super().get(request, *args, **kwargs)
 
-    @extend_schema_if_available(extensions={"x-ai-description": "Create a new notification template."})
+    @extend_schema_if_available(extensions={"x-ai-description": "Create a new notification template (email, Slack, webhook, etc.)."})
     def post(self, request, *args, **kwargs):
         return super().post(request, *args, **kwargs)
 

awx/api/views/analytics.py

@@ -51,7 +51,7 @@ class AnalyticsRootView(APIView):
     name = _('Automation Analytics')
     resource_purpose = 'automation analytics endpoints'
 
-    @extend_schema_if_available(extensions={"x-ai-description": "A list of additional API endpoints related to analytics"})
+    @extend_schema_if_available(extensions={"x-ai-description": "Returns available analytics API endpoints and their descriptions."})
     def get(self, request, format=None):
         data = OrderedDict()
         data['authorized'] = reverse('api:analytics_authorized', request=request)

awx/api/views/root.py

@@ -323,7 +323,7 @@ class ApiV2ConfigView(APIView):
             self.permission_denied(request)  # Raises PermissionDenied exception.
 
     @extend_schema_if_available(
-        extensions={'x-ai-description': 'Return various configuration settings'},
+        extensions={'x-ai-description': 'Returns platform-level configuration and license info.'},
     )
     def get(self, request, format=None):
         '''Return various sitewide configuration settings'''

awx/conf/views.py

@@ -42,7 +42,7 @@ class SettingCategoryList(ListAPIView):
     filter_backends = []
     name = _('Setting Categories')
 
-    @extend_schema_if_available(extensions={"x-ai-description": "A list of additional API endpoints related to settings."})
+    @extend_schema_if_available(extensions={"x-ai-description": "Returns a paginated list of Controller setting categories."})
     def get(self, request, *args, **kwargs):
         return super().get(request, *args, **kwargs)