@browserstack/mcp-server 1.5.0-beta.1 → 1.5.0-beta.10

package/capability/tm.capability-index.json

@@ -1,11 +1,12 @@
 {
   "schema_version": 1,
-  "version": "1.0",
-  "build_id": "83525474_2026-09-02T12:13:05Z",
+  "version": "1.4",
+  "build_id": "f6a3eca0_2026-09-09T14:21:54Z",
   "tm": {
     "summary": "BrowserStack Test Management API (v1 — the SSO/OAuth app API, session-authenticated).",
     "capabilities": [
       {
+        "name": "assign_test_run_owner",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/assign",
         "mode": "write",
@@ -64,6 +65,7 @@
         }
       },
       {
+        "name": "bulk_archive_test_cases_by_project",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-cases/bulk-archive",
         "mode": "write",
@@ -119,6 +121,9 @@
           }
         ],
         "intent": "Bulk Archive Test Cases",
+        "guidance": [
+          "Archiving hides cases from the working set without deleting them; they can be retrieved again. Prefer it to deletion when the user says 'remove' or 'clean up' without being explicit."
+        ],
         "paginated": true,
         "responses": {
           "200": {
@@ -139,6 +144,7 @@
         }
       },
       {
+        "name": "bulk_archive_test_plans_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-plans/bulk-archive",
         "mode": "write",
@@ -188,6 +194,7 @@
         }
       },
       {
+        "name": "bulk_assign_test_cases_to_test_run",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/test-cases/bulk_assign",
         "mode": "write",
@@ -283,6 +290,7 @@
         }
       },
       {
+        "name": "bulk_copy_test_cases",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-cases/bulk-copy",
         "mode": "write",
@@ -386,6 +394,7 @@
         }
       },
       {
+        "name": "bulk_delete_test_cases",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-cases/bulk-delete",
         "mode": "destructive",
@@ -478,6 +487,7 @@
         }
       },
       {
+        "name": "bulk_delete_test_results_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-results/bulk-delete",
         "mode": "destructive",
@@ -559,6 +569,7 @@
         }
       },
       {
+        "name": "bulk_edit_test_cases",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-cases/bulk-edit",
         "mode": "write",
@@ -713,6 +724,7 @@
         }
       },
       {
+        "name": "bulk_edit_test_cases_in_test_run",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/test-cases/edit",
         "mode": "write",
@@ -845,6 +857,7 @@
         }
       },
       {
+        "name": "bulk_edit_test_cases_v2",
         "method": "PATCH",
         "path": "/api/v1/projects/{project_id}/test-cases",
         "mode": "write",
@@ -1087,6 +1100,9 @@
           }
         ],
         "intent": "Bulk edit test cases with per-field add / remove / replace operations (PREFERRED bulk write).",
+        "guidance": [
+          "Applies one change to many cases at once. Confirm the selection resolves to what the user meant before sending — there is no per-case confirmation and no undo."
+        ],
         "returns": [
           "async",
           "unique_id"
@@ -1133,6 +1149,7 @@
         }
       },
       {
+        "name": "bulk_move_test_cases",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-cases/bulk-move",
         "mode": "write",
@@ -1229,6 +1246,7 @@
         }
       },
       {
+        "name": "bulk_retrieve_test_cases",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-cases/bulk-retrieve",
         "mode": "write",
@@ -1324,6 +1342,7 @@
         }
       },
       {
+        "name": "bulk_retrieve_test_plans_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-plans/bulk-retrieve",
         "mode": "write",
@@ -1373,6 +1392,7 @@
         }
       },
       {
+        "name": "clone_exploratory_session_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions/{session_id}/clone",
         "mode": "write",
@@ -1403,6 +1423,7 @@
         }
       },
       {
+        "name": "clone_test_plan_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-plans/{test_plan_id}/clone",
         "mode": "write",
@@ -1467,6 +1488,7 @@
         }
       },
       {
+        "name": "clone_test_run",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/clone",
         "mode": "write",
@@ -1564,6 +1586,7 @@
         }
       },
       {
+        "name": "close_exploratory_session",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions/{session_id}/close",
         "mode": "write",
@@ -1613,6 +1636,7 @@
         }
       },
       {
+        "name": "close_test_run_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/close",
         "mode": "write",
@@ -1670,6 +1694,7 @@
         }
       },
       {
+        "name": "copy_folder",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folders/copy",
         "mode": "write",
@@ -1738,6 +1763,7 @@
         }
       },
       {
+        "name": "count_run_selection_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/selection-count",
         "mode": "read",
@@ -1828,6 +1854,7 @@
         }
       },
       {
+        "name": "create_bulk_test_cases_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/bulk-test-cases",
         "mode": "write",
@@ -2052,6 +2079,7 @@
         }
       },
       {
+        "name": "create_configuration_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/configurations",
         "mode": "write",
@@ -2100,6 +2128,7 @@
         }
       },
       {
+        "name": "create_custom_field_dataset_option_v2",
         "method": "POST",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}/datasets/{dataset_id}/options",
         "mode": "write",
@@ -2161,6 +2190,7 @@
         }
       },
       {
+        "name": "create_custom_field_dataset_v2",
         "method": "POST",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}/datasets",
         "mode": "write",
@@ -2236,6 +2266,7 @@
         }
       },
       {
+        "name": "create_custom_field_definition_v2",
         "method": "POST",
         "path": "/api/v1/admin-v2/settings/custom-fields",
         "mode": "write",
@@ -2343,6 +2374,7 @@
         }
       },
       {
+        "name": "create_dataset",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/datasets",
         "mode": "write",
@@ -2449,6 +2481,7 @@
         }
       },
       {
+        "name": "create_exploratory_session",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions",
         "mode": "write",
@@ -2612,6 +2645,7 @@
         }
       },
       {
+        "name": "create_exploratory_session_log",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions/{session_id}/logs",
         "mode": "write",
@@ -2725,6 +2759,7 @@
         }
       },
       {
+        "name": "create_filter",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/filter",
         "mode": "write",
@@ -2801,6 +2836,7 @@
         }
       },
       {
+        "name": "create_project_v1",
         "method": "POST",
         "path": "/api/v1/projects",
         "mode": "write",
@@ -2851,6 +2887,7 @@
         }
       },
       {
+        "name": "create_report",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/reports",
         "mode": "write",
@@ -3149,6 +3186,7 @@
         }
       },
       {
+        "name": "create_root_folder_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folders",
         "mode": "write",
@@ -3205,6 +3243,7 @@
         }
       },
       {
+        "name": "create_shared_step_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/shared-steps",
         "mode": "write",
@@ -3284,6 +3323,7 @@
         }
       },
       {
+        "name": "create_step_result_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/test-cases/{test_case_id}/step/{step_id}",
         "mode": "write",
@@ -3336,6 +3376,7 @@
         }
       },
       {
+        "name": "create_sub_folder_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/mkdir",
         "mode": "write",
@@ -3413,6 +3454,7 @@
         }
       },
       {
+        "name": "create_test_case_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-cases",
         "mode": "write",
@@ -3457,6 +3499,7 @@
         }
       },
       {
+        "name": "create_test_cases",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases",
         "mode": "write",
@@ -3649,6 +3692,7 @@
         }
       },
       {
+        "name": "create_test_plan_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-plans",
         "mode": "write",
@@ -3779,6 +3823,7 @@
         }
       },
       {
+        "name": "create_test_result_for_test_case",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/test-cases/{test_case_id}/test-results",
         "mode": "write",
@@ -3861,6 +3906,9 @@
           }
         ],
         "intent": "Create a new test result for a test case in a test run",
+        "guidance": [
+          "This is how a pass or fail is recorded against a case in a run. Editing the run or the case does not record an outcome."
+        ],
         "returns": [
           "id",
           "status",
@@ -3900,6 +3948,7 @@
         }
       },
       {
+        "name": "create_test_run_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs",
         "mode": "write",
@@ -4091,6 +4140,13 @@
           }
         ],
         "intent": "Create a test run for a project",
+        "guidance": [
+          "Discovering cases does not put them in a run. Carry the case ids you found into this call — a create whose only case-bearing field is a filter rule succeeds and creates an EMPTY run.",
+          "run_state is required and is validated before the selection, so a bare 'invalid data' error means a bad run field, not a bad selection.",
+          "A filter rule also makes the run keep syncing as cases change, even if you did not ask for that. Create runs static unless the user explicitly wants a run that keeps updating.",
+          "Dynamic runs match on priority, status, category, owner, automation status, automation state, folder, tags and issues only. Creation and update dates are echoed back but never matched, so a 'last 7 days' dynamic run silently drops the date window and keeps collecting.",
+          "Preview the selection first if the count matters — it reports what the selection resolves to before anything is created."
+        ],
         "returns": [
           "id",
           "identifier",
@@ -4130,6 +4186,7 @@
         }
       },
       {
+        "name": "delete_custom_field_dataset_option_v2",
         "method": "POST",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}/datasets/{dataset_id}/options/{option_id}/delete",
         "mode": "destructive",
@@ -4177,6 +4234,7 @@
         }
       },
       {
+        "name": "delete_custom_field_dataset_v2",
         "method": "POST",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}/datasets/{dataset_id}/delete",
         "mode": "destructive",
@@ -4219,6 +4277,7 @@
         }
       },
       {
+        "name": "delete_custom_field_definition_v2",
         "method": "POST",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}/delete",
         "mode": "destructive",
@@ -4256,6 +4315,7 @@
         }
       },
       {
+        "name": "delete_dataset",
         "method": "DELETE",
         "path": "/api/v1/projects/{project_id}/datasets/{uuid}",
         "mode": "destructive",
@@ -4313,6 +4373,7 @@
         }
       },
       {
+        "name": "delete_exploratory_session",
         "method": "DELETE",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions/{session_id}",
         "mode": "destructive",
@@ -4372,6 +4433,7 @@
         }
       },
       {
+        "name": "delete_exploratory_session_log",
         "method": "DELETE",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions/{session_id}/logs/{log_id}",
         "mode": "destructive",
@@ -4424,6 +4486,7 @@
         }
       },
       {
+        "name": "delete_filter",
         "method": "DELETE",
         "path": "/api/v1/projects/{project_id}/filter/{filter_id}",
         "mode": "destructive",
@@ -4466,6 +4529,7 @@
         }
       },
       {
+        "name": "delete_folder_and_contents",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/rm",
         "mode": "destructive",
@@ -4534,6 +4598,7 @@
         }
       },
       {
+        "name": "delete_report_schedule",
         "method": "DELETE",
         "path": "/api/v1/projects/{project_id}/reports/schedules/{schedule_id}",
         "mode": "destructive",
@@ -4593,6 +4658,7 @@
         }
       },
       {
+        "name": "delete_shared_step_v1",
         "method": "DELETE",
         "path": "/api/v1/projects/{project_id}/shared-steps/{shared_step_id}",
         "mode": "destructive",
@@ -4635,6 +4701,7 @@
         }
       },
       {
+        "name": "delete_test_case_attachment",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases/{test_case_id}/attachments/{attachment_id}/delete",
         "mode": "destructive",
@@ -4701,6 +4768,7 @@
         }
       },
       {
+        "name": "delete_test_plan_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-plans/{test_plan_id}/delete",
         "mode": "destructive",
@@ -4756,6 +4824,7 @@
         }
       },
       {
+        "name": "delete_test_result_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-results/{test_result_id}/delete",
         "mode": "destructive",
@@ -4800,6 +4869,7 @@
         }
       },
       {
+        "name": "delete_v1_test_run",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/delete",
         "mode": "destructive",
@@ -4857,6 +4927,7 @@
         }
       },
       {
+        "name": "discard_duplicate_v1",
         "method": "PUT",
         "path": "/api/v1/projects/{project_id}/ai-duplicates/{duplicate_id}",
         "mode": "write",
@@ -4913,6 +4984,7 @@
         }
       },
       {
+        "name": "download_report",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/reports/{report_id}/download",
         "mode": "write",
@@ -4974,6 +5046,7 @@
         }
       },
       {
+        "name": "edit_test_case_partial_v1",
         "method": "PATCH",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases/{test_case_id}/edit-v2",
         "mode": "write",
@@ -5257,6 +5330,7 @@
         }
       },
       {
+        "name": "edit_test_case_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases/{test_case_id}/edit",
         "mode": "write",
@@ -5471,6 +5545,7 @@
         }
       },
       {
+        "name": "edit_test_run",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/edit",
         "mode": "write",
@@ -5707,6 +5782,7 @@
         }
       },
       {
+        "name": "export_dashboard_analytics",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/dashboard-analytics/download",
         "mode": "write",
@@ -5773,6 +5849,7 @@
         }
       },
       {
+        "name": "get_active_test_runs_info_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/dashboard-analytics/active-test-runs-info",
         "mode": "read",
@@ -5811,6 +5888,7 @@
         }
       },
       {
+        "name": "get_archived_test_cases",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-cases/archived_test_cases",
         "mode": "read",
@@ -5856,6 +5934,7 @@
         }
       },
       {
+        "name": "get_archived_test_plan_count_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-plans/archive_count",
         "mode": "read",
@@ -5893,6 +5972,7 @@
         }
       },
       {
+        "name": "get_automation_stats_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/dashboard-analytics/automation-stats",
         "mode": "read",
@@ -5937,6 +6017,7 @@
         }
       },
       {
+        "name": "get_closed_test_runs",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-runs/closed",
         "mode": "read",
@@ -5988,6 +6069,7 @@
         }
       },
       {
+        "name": "get_closed_test_runs_info_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/dashboard-analytics/closed-test-runs-info",
         "mode": "read",
@@ -6028,6 +6110,7 @@
         }
       },
       {
+        "name": "get_closed_test_runs_split_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/dashboard-analytics/closed-test-runs-split",
         "mode": "read",
@@ -6068,6 +6151,7 @@
         }
       },
       {
+        "name": "get_configurations_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/configurations",
         "mode": "read",
@@ -6116,6 +6200,7 @@
         }
       },
       {
+        "name": "get_custom_field_dataset_v2",
         "method": "GET",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}/datasets/{dataset_id}",
         "mode": "read",
@@ -6159,6 +6244,7 @@
         }
       },
       {
+        "name": "get_custom_field_definition_v2",
         "method": "GET",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}",
         "mode": "read",
@@ -6197,6 +6283,7 @@
         }
       },
       {
+        "name": "get_custom_field_values_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/{entity_type}/custom-fields/{field_id}",
         "mode": "read",
@@ -6249,6 +6336,7 @@
         }
       },
       {
+        "name": "get_dataset",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/datasets/{uuid}",
         "mode": "read",
@@ -6310,6 +6398,7 @@
         }
       },
       {
+        "name": "get_dataset_linked_test_cases",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/datasets/{uuid}/test-cases",
         "mode": "read",
@@ -6379,6 +6468,7 @@
         }
       },
       {
+        "name": "get_dataset_variables",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/datasets/variables",
         "mode": "read",
@@ -6444,6 +6534,7 @@
         }
       },
       {
+        "name": "get_dedupe_status_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/ai-duplicates/status",
         "mode": "read",
@@ -6483,6 +6574,7 @@
         }
       },
       {
+        "name": "get_duplicate_source_test_case_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/ai-duplicates/{duplicate_id}/source_tc",
         "mode": "read",
@@ -6520,6 +6612,7 @@
         }
       },
       {
+        "name": "get_duplicate_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/ai-duplicates/{duplicate_id}",
         "mode": "read",
@@ -6557,6 +6650,7 @@
         }
       },
       {
+        "name": "get_entity_filter_details_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/{entity}/filter-details",
         "mode": "read",
@@ -6851,6 +6945,7 @@
         }
       },
       {
+        "name": "get_exploratory_session",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions/{session_id}",
         "mode": "read",
@@ -6917,6 +7012,7 @@
         }
       },
       {
+        "name": "get_exploratory_session_summary_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/reports/exploratory-session-summary",
         "mode": "read",
@@ -6968,6 +7064,7 @@
         }
       },
       {
+        "name": "get_filter",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/filter/{filter_id}",
         "mode": "read",
@@ -7020,6 +7117,7 @@
         }
       },
       {
+        "name": "get_folder_remove_summary",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/rm-summary",
         "mode": "read",
@@ -7062,6 +7160,7 @@
         }
       },
       {
+        "name": "get_folder_tree_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/repository/mapping",
         "mode": "read",
@@ -7099,6 +7198,7 @@
         }
       },
       {
+        "name": "get_group_users_v2_v1",
         "method": "GET",
         "path": "/api/v1/group/users-v2",
         "mode": "read",
@@ -7138,6 +7238,7 @@
         }
       },
       {
+        "name": "get_issues_count_info_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/dashboard-analytics/issues-count-info",
         "mode": "read",
@@ -7178,6 +7279,7 @@
         }
       },
       {
+        "name": "get_project_by_integer_id_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}",
         "mode": "read",
@@ -7220,6 +7322,7 @@
         }
       },
       {
+        "name": "get_project_id_custom_fields_v2_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/form-fields-v2",
         "mode": "read",
@@ -7268,6 +7371,7 @@
         }
       },
       {
+        "name": "get_project_settings",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/settings",
         "mode": "read",
@@ -7345,6 +7449,7 @@
         }
       },
       {
+        "name": "get_project_users_v2_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/users-v2",
         "mode": "read",
@@ -7394,6 +7499,7 @@
         }
       },
       {
+        "name": "get_projects_basic_v1",
         "method": "GET",
         "path": "/api/v1/projects/basic",
         "mode": "read",
@@ -7410,7 +7516,7 @@
           {
             "name": "q[query]",
             "type": "string",
-            "example": "jdoe42"
+            "example": "example-project"
           },
           {
             "name": "q[identifier]",
@@ -7449,6 +7555,7 @@
         }
       },
       {
+        "name": "get_projects_minify_v1",
         "method": "GET",
         "path": "/api/v1/projects/minify",
         "mode": "read",
@@ -7494,6 +7601,7 @@
         }
       },
       {
+        "name": "get_report_attachment_url",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/reports/attachments/{attachment_id}",
         "mode": "read",
@@ -7554,6 +7662,7 @@
         }
       },
       {
+        "name": "get_report_detail",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/reports/{report_id}",
         "mode": "read",
@@ -7628,6 +7737,7 @@
         }
       },
       {
+        "name": "get_report_section_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/reports/{report_id}/{section_name}",
         "mode": "read",
@@ -7683,6 +7793,7 @@
         }
       },
       {
+        "name": "get_report_summary_by_type",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/reports/{report_id}/detail/{report_type}",
         "mode": "read",
@@ -7784,6 +7895,7 @@
         }
       },
       {
+        "name": "get_root_folders_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/folders",
         "mode": "read",
@@ -7842,6 +7954,7 @@
         }
       },
       {
+        "name": "get_selected_report_testcases",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/reports/{report_id}/selection/edit",
         "mode": "read",
@@ -7885,6 +7998,7 @@
         }
       },
       {
+        "name": "get_shared_steps_by_i_d_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/shared-steps/{shared_step_id}",
         "mode": "read",
@@ -7942,6 +8056,7 @@
         }
       },
       {
+        "name": "get_shared_steps_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/shared-steps",
         "mode": "read",
@@ -8000,6 +8115,7 @@
         }
       },
       {
+        "name": "get_system_field_values_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-case/{field_name}",
         "mode": "read",
@@ -8049,6 +8165,7 @@
         }
       },
       {
+        "name": "get_test_case_attachments_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases/{test_case_id}/attachments",
         "mode": "read",
@@ -8116,6 +8233,7 @@
         }
       },
       {
+        "name": "get_test_case_by_integer_id_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases/{test_case_id}",
         "mode": "read",
@@ -8159,6 +8277,7 @@
         }
       },
       {
+        "name": "get_test_case_count_trend_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/dashboard-analytics/test-case-count-trend",
         "mode": "read",
@@ -8199,6 +8318,7 @@
         }
       },
       {
+        "name": "get_test_case_detail",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases/{test_case_id}/detail",
         "mode": "read",
@@ -8278,6 +8398,7 @@
         }
       },
       {
+        "name": "get_test_case_histories_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-cases/{test_case_id}/histories",
         "mode": "read",
@@ -8333,6 +8454,7 @@
         }
       },
       {
+        "name": "get_test_case_history_diff_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-cases/{test_case_id}/histories/diff",
         "mode": "read",
@@ -8386,6 +8508,7 @@
         }
       },
       {
+        "name": "get_test_case_history_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-cases/{test_case_id}/histories/{history_id}",
         "mode": "read",
@@ -8457,6 +8580,7 @@
         }
       },
       {
+        "name": "get_test_case_tags",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases/{test_case_id}/tags",
         "mode": "read",
@@ -8526,6 +8650,7 @@
         }
       },
       {
+        "name": "get_test_case_type_split_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/dashboard-analytics/test-case-type-split",
         "mode": "read",
@@ -8569,6 +8694,7 @@
         }
       },
       {
+        "name": "get_test_cases_for_v1_test_run",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/test-cases",
         "mode": "read",
@@ -8619,6 +8745,7 @@
         }
       },
       {
+        "name": "get_test_cases_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-cases",
         "mode": "read",
@@ -8703,6 +8830,7 @@
         }
       },
       {
+        "name": "get_test_plan_by_integer_id_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-plans/{test_plan_id}",
         "mode": "read",
@@ -8740,6 +8868,7 @@
         }
       },
       {
+        "name": "get_test_plan_execution_trend_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-plans/execution-trend",
         "mode": "read",
@@ -8805,6 +8934,7 @@
         }
       },
       {
+        "name": "get_test_plan_linked_sessions_chart_data_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-plans/{test_plan_id}/linked-sessions-chart-data",
         "mode": "read",
@@ -8842,6 +8972,7 @@
         }
       },
       {
+        "name": "get_test_plan_test_runs_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-plans/{test_plan_id}/test-runs",
         "mode": "read",
@@ -8904,6 +9035,7 @@
         }
       },
       {
+        "name": "get_test_results_custom_fields_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-results/custom-fields",
         "mode": "read",
@@ -8963,6 +9095,7 @@
         }
       },
       {
+        "name": "get_test_results_for_test_case",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/test-cases/{test_case_id}/test-results",
         "mode": "read",
@@ -9025,6 +9158,7 @@
         }
       },
       {
+        "name": "get_test_run_by_integer_id_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}",
         "mode": "read",
@@ -9042,6 +9176,9 @@
           }
         ],
         "intent": "Get a test run by INTEGER id (v1) — full detail + its TR-NNN identifier",
+        "guidance": [
+          "The run's id field is the display identifier string, while uuid is the integer. Take uuid whenever you carry this run into another call: the display string is rejected downstream."
+        ],
         "returns": [
           "id",
           "identifier",
@@ -9064,6 +9201,7 @@
         }
       },
       {
+        "name": "get_test_run_cases_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/detail",
         "mode": "read",
@@ -9095,6 +9233,7 @@
         }
       },
       {
+        "name": "get_test_runs_form_fields_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-runs/form-fields",
         "mode": "read",
@@ -9146,6 +9285,7 @@
         }
       },
       {
+        "name": "get_test_runs_selection",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-runs/selection",
         "mode": "read",
@@ -9222,6 +9362,7 @@
         }
       },
       {
+        "name": "get_test_runs_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-runs",
         "mode": "read",
@@ -9283,6 +9424,7 @@
         }
       },
       {
+        "name": "import_dataset_c_s_v",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/datasets/import_csv",
         "mode": "write",
@@ -9345,6 +9487,7 @@
         }
       },
       {
+        "name": "list_activity_events_v1",
         "method": "GET",
         "path": "/api/v1/activities",
         "mode": "read",
@@ -9435,6 +9578,7 @@
         }
       },
       {
+        "name": "list_archived_test_plans_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-plans/archived_test_plans",
         "mode": "read",
@@ -9474,6 +9618,7 @@
         }
       },
       {
+        "name": "list_custom_field_dataset_options_v2",
         "method": "GET",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}/datasets/{dataset_id}/options",
         "mode": "read",
@@ -9517,6 +9662,7 @@
         }
       },
       {
+        "name": "list_datasets",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/datasets",
         "mode": "read",
@@ -9590,6 +9736,7 @@
         }
       },
       {
+        "name": "list_duplicates_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/ai-duplicates",
         "mode": "read",
@@ -9641,6 +9788,7 @@
         }
       },
       {
+        "name": "list_exploratory_session_defects",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions/{session_id}/defects",
         "mode": "read",
@@ -9735,6 +9883,7 @@
         }
       },
       {
+        "name": "list_exploratory_session_logs",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions/{session_id}/logs",
         "mode": "read",
@@ -9801,6 +9950,7 @@
         }
       },
       {
+        "name": "list_exploratory_sessions",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions",
         "mode": "read",
@@ -9926,6 +10076,7 @@
         }
       },
       {
+        "name": "list_filters",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/filter",
         "mode": "read",
@@ -9989,6 +10140,7 @@
         }
       },
       {
+        "name": "list_folder_contents",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}",
         "mode": "read",
@@ -10032,6 +10184,7 @@
         }
       },
       {
+        "name": "list_folder_test_cases_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases",
         "mode": "read",
@@ -10097,6 +10250,7 @@
         }
       },
       {
+        "name": "list_projects_v1",
         "method": "GET",
         "path": "/api/v1/projects",
         "mode": "read",
@@ -10105,7 +10259,7 @@
           {
             "name": "q",
             "type": "string",
-            "example": "jdoe42"
+            "example": "example-project"
           },
           {
             "name": "p",
@@ -10170,6 +10324,7 @@
         }
       },
       {
+        "name": "list_schedules",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/reports/schedules",
         "mode": "read",
@@ -10243,6 +10398,7 @@
         }
       },
       {
+        "name": "list_test_case_tags_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-case/tags-v2",
         "mode": "read",
@@ -10280,6 +10436,7 @@
         }
       },
       {
+        "name": "list_test_case_templates_v2",
         "method": "GET",
         "path": "/api/v1/admin-v2/settings/templates",
         "mode": "read",
@@ -10333,6 +10490,7 @@
         }
       },
       {
+        "name": "list_test_plans_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-plans",
         "mode": "read",
@@ -10402,6 +10560,7 @@
         }
       },
       {
+        "name": "list_workspace_fields_v2",
         "method": "GET",
         "path": "/api/v1/admin-v2/settings/fields",
         "mode": "read",
@@ -10464,6 +10623,7 @@
         }
       },
       {
+        "name": "merge_tags_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/tags/merge",
         "mode": "write",
@@ -10512,6 +10672,7 @@
         }
       },
       {
+        "name": "move_folder_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/mv",
         "mode": "write",
@@ -10618,6 +10779,7 @@
         }
       },
       {
+        "name": "rename_folder_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/rename",
         "mode": "write",
@@ -10691,6 +10853,7 @@
         }
       },
       {
+        "name": "reorder_folders",
         "method": "PATCH",
         "path": "/api/v1/projects/{project_id}/folders/reorder",
         "mode": "write",
@@ -10770,6 +10933,7 @@
         }
       },
       {
+        "name": "reorder_test_cases_by_folder_v1",
         "method": "PATCH",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases/reorder",
         "mode": "write",
@@ -10864,6 +11028,7 @@
         }
       },
       {
+        "name": "resolve_duplicate_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/ai-duplicates",
         "mode": "write",
@@ -10930,6 +11095,7 @@
         }
       },
       {
+        "name": "restore_history_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-cases/{test_case_id}/histories/{history_id}/restore",
         "mode": "write",
@@ -10985,6 +11151,7 @@
         }
       },
       {
+        "name": "search_duplicates_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/ai-duplicates/search-v2",
         "mode": "read",
@@ -11037,6 +11204,7 @@
         }
       },
       {
+        "name": "search_group_tags",
         "method": "GET",
         "path": "/api/v1/group/{entity_type}/tags",
         "mode": "read",
@@ -11086,6 +11254,7 @@
         }
       },
       {
+        "name": "search_project_entities",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/{entity}/search",
         "mode": "read",
@@ -11172,6 +11341,7 @@
         }
       },
       {
+        "name": "search_project_entities_v2",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/{entity}/search-v2",
         "mode": "read",
@@ -11412,6 +11582,9 @@
           }
         ],
         "intent": "Search for entities within a project (v2 - POST with body)",
+        "guidance": [
+          "The general way to find cases by attribute. Ask for a large page when collecting ids to feed into another call, so the follow-up gets the whole set rather than the first page."
+        ],
         "shape": "discovered",
         "max_page_size": 100,
         "paginated": true,
@@ -11446,6 +11619,7 @@
         }
       },
       {
+        "name": "search_project_users",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/users/search",
         "mode": "read",
@@ -11501,6 +11675,7 @@
         }
       },
       {
+        "name": "search_test_case_tags",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/test-case/tags/search",
         "mode": "read",
@@ -11547,6 +11722,7 @@
         }
       },
       {
+        "name": "search_test_cases_by_folder_v1",
         "method": "GET",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases/search",
         "mode": "read",
@@ -11634,6 +11810,7 @@
         }
       },
       {
+        "name": "send_report_email_now_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/reports/{report_id}/send_email_now",
         "mode": "write",
@@ -11685,6 +11862,7 @@
         }
       },
       {
+        "name": "undo_remove_folder",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/undo-rm",
         "mode": "write",
@@ -11753,6 +11931,7 @@
         }
       },
       {
+        "name": "unlink_test_runs_from_test_plan",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-plans/{test_plan_id}/test-runs/unlink",
         "mode": "write",
@@ -11803,6 +11982,7 @@
         }
       },
       {
+        "name": "update_custom_field_dataset_option_v2",
         "method": "POST",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}/datasets/{dataset_id}/options/{option_id}/update",
         "mode": "write",
@@ -11869,6 +12049,7 @@
         }
       },
       {
+        "name": "update_custom_field_dataset_project_mapping_v2",
         "method": "POST",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}/datasets/{dataset_id}/project-mappings/update",
         "mode": "write",
@@ -11932,6 +12113,7 @@
         }
       },
       {
+        "name": "update_custom_field_definition_v2",
         "method": "POST",
         "path": "/api/v1/admin-v2/settings/custom-fields/{custom_fields_id}/update",
         "mode": "write",
@@ -12002,6 +12184,7 @@
         }
       },
       {
+        "name": "update_dataset",
         "method": "PUT",
         "path": "/api/v1/projects/{project_id}/datasets/{uuid}",
         "mode": "write",
@@ -12110,6 +12293,7 @@
         }
       },
       {
+        "name": "update_exploratory_session",
         "method": "PATCH",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions/{session_id}",
         "mode": "write",
@@ -12286,6 +12470,7 @@
         }
       },
       {
+        "name": "update_exploratory_session_log",
         "method": "PATCH",
         "path": "/api/v1/projects/{project_id}/exploratory-sessions/{session_id}/logs/{log_id}",
         "mode": "write",
@@ -12405,6 +12590,7 @@
         }
       },
       {
+        "name": "update_filter",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/filter/{filter_id}",
         "mode": "write",
@@ -12488,6 +12674,7 @@
         }
       },
       {
+        "name": "update_latest_test_result_for_test_case",
         "method": "PATCH",
         "path": "/api/v1/projects/{project_id}/test-runs/{test_run_id}/test-cases/{test_case_id}/test-results",
         "mode": "write",
@@ -12650,6 +12837,7 @@
         }
       },
       {
+        "name": "update_project_settings",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/settings",
         "mode": "write",
@@ -12696,6 +12884,7 @@
         }
       },
       {
+        "name": "update_report",
         "method": "PATCH",
         "path": "/api/v1/projects/{project_id}/reports/{report_id}",
         "mode": "write",
@@ -12998,6 +13187,7 @@
         }
       },
       {
+        "name": "update_shared_step_v1",
         "method": "PATCH",
         "path": "/api/v1/projects/{project_id}/shared-steps/{shared_step_id}",
         "mode": "write",
@@ -13084,6 +13274,7 @@
         }
       },
       {
+        "name": "update_test_plan_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/test-plans/{test_plan_id}/update",
         "mode": "write",
@@ -13219,6 +13410,7 @@
         }
       },
       {
+        "name": "upload_a_i_attachments",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/generic/attachments/ai_uploads",
         "mode": "write",
@@ -13255,6 +13447,7 @@
         }
       },
       {
+        "name": "upload_generic_attachments",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/generic/attachments",
         "mode": "write",
@@ -13291,6 +13484,7 @@
         }
       },
       {
+        "name": "upload_test_case_attachments_v1",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/folder/{folder_id}/test-cases/{test_case_id}/attachments",
         "mode": "write",
@@ -13358,6 +13552,7 @@
         }
       },
       {
+        "name": "user_workload_drilldown",
         "method": "POST",
         "path": "/api/v1/projects/{project_id}/reports/{report_id}/drilldown",
         "mode": "read",
@@ -17043,13 +17238,13 @@
             "type": "string",
             "format": "uri",
             "description": "Pre-signed S3 URL for viewing (inline, ~26 min expiry)",
-            "example": "https://example.com/media/genric/1/2921471/86de8094..."
+            "example": "https://example.com/media/1/2921471/86de8094..."
           },
           "download_url": {
             "type": "string",
             "format": "uri",
             "description": "Pre-signed S3 URL for downloading (attachment, ~26 min expiry)",
-            "example": "https://example.com/media/genric/1/2921471/86de8094..."
+            "example": "https://example.com/media/1/2921471/86de8094..."
           },
           "content_type": {
             "type": "string",
@@ -18160,7 +18355,7 @@
             },
             "selection": {
               "type": "object",
-              "description": "the primary project's persisted folder-structured test-case selection (with select_all / per-folder flags + unique_test_case_count), in the same shape as the test-run edit/selection endpoint. `{}` when the report has no saved selection for the primary project. Used by the Edit dialog to re-check saved test cases (including folder/project-level select_all, which the flat ids cannot represent).",
+              "description": "The primary project's persisted folder-structured test-case selection (with select_all / per-folder flags + unique_test_case_count), in the same shape as the test-run edit/selection endpoint. `{}` when the report has no saved selection for the primary project. Used by the Edit dialog to re-check saved test cases (including folder/project-level select_all, which the flat ids cannot represent).",
               "example": {
                 "select_all": false,
                 "folders": {
@@ -18177,7 +18372,7 @@
             },
             "shared_selection": {
               "type": "object",
-              "description": "per-project folder-structured selection for the report's non-primary projects, keyed by project id ({ \"<project_id>\": <selection> }). Present only for cross-project Test Case Activity reports; `{}` otherwise.",
+              "description": "Per-project folder-structured selection for the report's non-primary projects, keyed by project id ({ \"<project_id>\": <selection> }). Present only for cross-project Test Case Activity reports; `{}` otherwise.",
               "example": {
                 "10209": {
                   "select_all": true,
@@ -19090,6 +19285,15 @@
         ],
         "capabilities": [
           "list_activity_events_v1"
+        ],
+        "key_facts": [
+          "READ-ONLY by design. Activity events are emitted by the system as a side effect of other writes — there is no create, update, or delete, and there never will be. If asked to edit or remove an audit entry, say it is immutable.",
+          "HARD 15-DAY WINDOW. The server clamps every query to the last 15 days no matter what you ask for. For anything older, say the history is not retrievable through the API and point to the Test Management UI — do NOT report 'no activity' for an older period, which would be a false negative.",
+          "CURSOR pagination, not page numbers. Follow pagination.next_cursor and stop when pagination.has_next_page is false. There is no p param and no info.count, so you CANNOT state a total number of events or jump to a page.",
+          "Not project-scoped in the path — it is group-wide. Pass project_id as a QUERY param to narrow it to one project.",
+          "starred_only=true restricts to the caller's starred projects. When they have none the response is {events: [], no_starred_projects: true} — that means 'no starred projects', NOT 'no activity'. Check for that flag before reporting emptiness.",
+          "The response carries a projects map (project id → metadata) so you can resolve the project an event refers to without extra reads.",
+          "Gated by a group feature flag. If the call is refused, report that the activity feed isn't enabled for the group rather than that there is no activity."
         ]
       },
       "attachment": {
@@ -19121,6 +19325,10 @@
           "upload_a_i_attachments",
           "upload_generic_attachments",
           "upload_test_case_attachments_v1"
+        ],
+        "key_facts": [
+          "ai_uploads uploads a file as AI CONTEXT (restricted types, smaller cap) for seeding case content — see create-test-case.",
+          "Each blob/attachment row carries an integer id and a url (the file's location) — read the file from that url; there is no dedicated download endpoint."
         ]
       },
       "configuration": {
@@ -19189,6 +19397,15 @@
           "update_custom_field_dataset_option_v2",
           "update_custom_field_dataset_project_mapping_v2",
           "update_custom_field_definition_v2"
+        ],
+        "key_facts": [
+          "A field applies to ONE entity type (TestCase | TestResult | TestPlan) — pick the matching entity_type; project scope is via the integer project id in the path.",
+          "A definition write is workspace-wide, not project-scoped: it affects every project the field's datasets link to. Say which projects are affected BEFORE writing.",
+          "field_name IS editable via .../update; field_type is SILENTLY immutable — sending a new type returns 200 and changes nothing. Never report a type change as done; a real one means delete-and-recreate, which destroys every stored value.",
+          "Update is a full REPLACE: field_name + field_type + is_required must all be present (missing is_required = 400, missing field_name = 500). Read the field first and resend the whole set.",
+          "The project-mapping endpoint uses link_projects / unlink_projects — NOT the linked_projects of the create bodies. The wrong spelling is silently dropped: 200, nothing changed.",
+          "Three operations destroy stored data across every linked project: deleting a field, deleting an option, and unlinking a project. There is no bin. Count and name the affected projects before asking to proceed.",
+          "Don't confuse a DEFINITION with a VALUE. A definition is which attributes exist; a value is what one case holds. Only values are writable here, through the test-case create/update body's custom_fields."
         ]
       },
       "dataset": {
@@ -19222,6 +19439,9 @@
           "import_dataset_c_s_v",
           "list_datasets",
           "update_dataset"
+        ],
+        "key_facts": [
+          "Team Pro plan gated: without it EVERY dataset endpoint returns 422 \"Feature not available\". A 422 here means NOT-ENTITLED, not a bad payload — say so and stop, don't retry with a different body."
         ]
       },
       "duplicate": {
@@ -19254,6 +19474,13 @@
           "list_duplicates_v1",
           "resolve_duplicate_v1",
           "search_duplicates_v1"
+        ],
+        "key_facts": [
+          "There is NO create. Duplicate suggestions are produced by the dedupe pipeline; a caller cannot author one.",
+          "Only status=suggested can be read or resolved; already-merged/archived/discarded suggestions return 404. A 404 here usually means 'already handled', not 'never existed'.",
+          "source_tc works ONLY for status=merged, and the snapshot may legitimately be absent (404 with error 'Source test case snapshot not available'). Treat that as 'not retained', not as a retryable error.",
+          "This list family pages with `page`, not the `p` used elsewhere in the profile.",
+          "Dedupe REVIEW is exposed here; TCG test-case GENERATION is not. Don't offer to generate cases."
         ]
       },
       "exploratory_session": {
@@ -19300,6 +19527,12 @@
           "list_exploratory_sessions",
           "update_exploratory_session",
           "update_exploratory_session_log"
+        ],
+        "key_facts": [
+          "session_id and log_id are plain INTEGERS; the parent project takes the INTEGER project id (v1).",
+          "Logs hold rich-text HTML sanitised on write (off-project anchor/image links stripped); defects are the issues linked to the session.",
+          "Clone runs async when the session has many logs → re-fetch to confirm (see async-jobs).",
+          "No convert endpoint: turn session notes into test cases via the create-test-case flow."
         ]
       },
       "filter": {
@@ -19336,6 +19569,10 @@
           "get_filter",
           "list_filters",
           "update_filter"
+        ],
+        "key_facts": [
+          "A saved filter view persists a reusable filter: { name, entity, filters, is_project_level }. entity = testcase | testplan | testrun | exploratory_session; filter_id is an integer.",
+          "is_project_level scopes the view to the whole project vs. just the creator."
         ]
       },
       "folder": {
@@ -19372,6 +19609,10 @@
           "rename_folder_v1",
           "reorder_folders",
           "undo_remove_folder"
+        ],
+        "key_facts": [
+          "Folder ids are plain INTEGERS (e.g. 54) — never FL-… strings. Nesting is via parent_id (integer, null = root).",
+          "mv cross-project and copy run ASYNC ({ success, async, unique_id }) — confirm by re-reading the destination (see async-jobs)."
         ]
       },
       "project": {
@@ -19475,6 +19716,15 @@
           "send_report_email_now_v1",
           "update_report",
           "user_workload_drilldown"
+        ],
+        "key_facts": [
+          "report_id and schedule_id are INTEGERS; the parent project takes the INTEGER project id (v1).",
+          "report_type on create/update is a DISPLAY NAME and the set is CLOSED — exactly these nine: Test Run Summary, Test Run Detailed Report, Test Plan Summary, Requirement Traceability Report, Test Case Activity, Exploratory Session Summary, User Workload Report, Defects Summary, Defects Detailed Report. Never invent one and never substitute a neighbouring type: if the user asks for activity, it is 'Test Case Activity', not 'Test Run Summary'.",
+          "Defects Summary and Defects Detailed Report are accepted on create but have no data branch — they always read back report_data: null. For defect counts use Test Run Summary's issues_by_priority / issues_by_status sections instead.",
+          "null inside report_data means NOT COMPUTED, not 'no data'. A Test Case Activity report fills its headline counts on a bare read; a Test Run Summary leaves issues_data / test_run_status / test_cases_status / issues_by_priority / issues_by_status null until you name them in sections. Never conclude 'there is no defect or status data' from a null — request the section; an empty payload like {total: 0} is a real finding, null is not. And never answer a 400 on sections by retreating to a bare read.",
+          "*_drilldown sections return PAGINATED ROWS, not aggregates — never tally rows into a count; read the aggregate section or report_data.",
+          "frequency + frequency_details travel together or not at all; omit both for an unscheduled on-demand report. weekly needs day as a lowercase name, monthly needs day as an integer 1-28. There is no 'once'. report_timeframe: custom REQUIRES custom_date_range.",
+          "\"Understand a report\" = fetch the report + its section/widget data and summarise agent-side; the API returns structured data, not narrative."
         ]
       },
       "result": {
@@ -19507,6 +19757,11 @@
           "delete_test_result_v1",
           "get_test_results_for_test_case",
           "update_latest_test_result_for_test_case"
+        ],
+        "key_facts": [
+          "Bodies are wrapped in test_result; set status by NAME (status) or id (status_id) — use a real configured status (see statuses-and-states).",
+          "bulk-delete SUCCEEDS PARTIALLY and still returns 200. Authorisation is per id (author OR project admin); ids the caller may not delete come back in `skipped` — and BOTH lists are nested under a top-level `result` key, with `skipped` holding OBJECTS ({id, reason}) not bare ids, so read result.deleted_ids / result.skipped. Not as an error. ALWAYS compare deleted_ids against what you asked for and report the skipped ids — treating 200 as 'all deleted' will misreport.",
+          "bulk-delete needs a non-empty result_ids array (400 otherwise) of at most 300 ids (422 beyond) — batch bigger sets yourself."
         ]
       },
       "shared_step": {
@@ -19534,6 +19789,10 @@
           "get_shared_steps_by_i_d_v1",
           "get_shared_steps_v1",
           "update_shared_step_v1"
+        ],
+        "key_facts": [
+          "A shared step is embedded by MANY test cases, so editing or deleting it changes every one of them at once. That is the point of shared steps, but it also means a delete is a wide blast radius — say how it is used before changing it.",
+          "Reference a shared step from a test case's steps via shared_step_id in test_case_steps — see test-case-authoring."
         ]
       },
       "tag": {
@@ -19569,6 +19828,12 @@
           "merge_tags_v1",
           "search_group_tags",
           "search_test_case_tags"
+        ],
+        "key_facts": [
+          "Tags are referenced by NAME in filters and on cases; the merge endpoint takes integer source_id/target_id, so resolve ids via the tag reads first.",
+          "That body MUST carry custom_fields (send {} when not changing any) — omitting it returns 500 'undefined method each for nil', even though the server's validator lists it as optional.",
+          "tags/merge is admin-gated (tags_management flag) — may be unavailable for a group; degrade gracefully and say so.",
+          "TAG-OBJECT WRITES ARE NOT EXPOSED. Renaming or deleting a tag project-wide is deliberately out of this profile: the endpoints exist but sit behind the tags_management flag that most groups do not have, and tagging is always driven through the ENTITY. If asked to rename or delete a tag, say it is not available here and point to the Test Management UI."
         ]
       },
       "test_case": {
@@ -19632,6 +19897,14 @@
           "reorder_test_cases_by_folder_v1",
           "search_project_entities_v2",
           "search_test_cases_by_folder_v1"
+        ],
+        "key_facts": [
+          "A filter is a (key, value) pair and each half fails silently: an unknown KEY is dropped (you get the whole project with success: true), and a wrong-form VALUE matches nothing (count: 0, also success: true). So resolve both — never guess either — and see pagination-and-filtering for the key table and each value's source.",
+          "A surprising count means check the FORM, not try another value: 0 on a value the user plainly meant = wrong form, so go resolve ids; filtered count == unfiltered count = the key was dropped. Never take either count from a per_page: 1 call — it returns count: 1 regardless of the real total.",
+          "required.fields ADDS joined columns; it does NOT slim a row, so naming fields never buys more rows per page. required.fields=[\"count\"] ALONE is the only value that changes the response.",
+          "The compact response has a DIFFERENT envelope: no `success` key ({test_cases, info, filter_details} only — absence of success is NOT failure), info.page_size echoes the server ceiling not your per_page, and filter_details is {} so confirm filter intent before the call.",
+          "READING ROWS to show a user: leave per_page at its default and walk p until info.next is null. p advances by per_page and not by what came back, so paging over an incomplete read never recovers the gap.",
+          "Paths take INTEGER ids (project + folder + case). The case's TC-NNN comes back as data.test_case.identifier on any read; folder ids are plain integers."
         ]
       },
       "test_plan": {
@@ -19674,6 +19947,18 @@
           "list_test_plans_v1",
           "unlink_test_runs_from_test_plan",
           "update_test_plan_v1"
+        ],
+        "key_facts": [
+          "Paths take the INTEGER plan id. The prefixed identifier (TP-NNN / STP-NNN) is for display; never put it in a v1 path.",
+          "The read detail has NO data wrapper: the plan sits under a top-level test_plan key, and test_plan.identifier is the TP-NNN / STP-NNN.",
+          "Sub-plans are HIDDEN by default in the list. Without include_sub_plans=true you see only top-level plans, so a sub-plan the user named will look missing.",
+          "name IS REQUIRED ON EVERY PLAN UPDATE, including one that only touches test_runs. Omit it and the call is rejected with 400 {success: false, error: 'Invalid Update Params'} however valid the rest of the body is — the server's edit branch is gated on name being present. Read the plan first and echo its current name back unchanged. Only a pure plan_status transition and a reviewers-only edit are exempt. Verified live: {test_plan: {test_runs: [198]}} 400s; adding name makes the identical call succeed.",
+          "Run ids in test_runs are the INTEGER uuid from a run read — NOT the run's id field, which is the TR-NNN string on every run endpoint (list, plan's run list, single detail alike). Identifiers are forwarded to the upstream service uncoerced and fail upstream (observed 502 Upstream service error). Take uuid, never id.",
+          "Linking a run MOVES it: a run belongs to at most one plan, so linking silently unlinks it from the plan that held it, with nothing in the 200 to say so. Read the runs' current membership first and tell the user which plans will lose runs. Verified live.",
+          "test_runs accepts an id array OR a bulk-selection object {select_all, de_selected_ids, search_query}. select_all means 'the newest active runs', NOT 'everything matching' — and `filters` is accepted but SILENTLY IGNORED, so a filtered select_all links the whole recent set. Narrow with search_query (name/identifier substring) or send explicit ids. Verified live.",
+          "bulk-archive / bulk-retrieve go ASYNC above the bulk threshold and return {success, async: true, unique_id} — the plans are NOT changed yet. Re-read to confirm; see async-jobs.",
+          "execution-trend is scoped by EXACTLY ONE of test_plan_id / test_run_id. Both → 400 'Provide either test_plan_id or test_run_id, not both'; neither → 400 'test_plan_id or test_run_id is required'.",
+          "execution-trend and linked-sessions-chart-data return chart DATA. There is no insights-widget object to create, update, or delete in this profile."
         ]
       },
       "test_run": {
@@ -19723,6 +20008,13 @@
           "get_test_runs_form_fields_v1",
           "get_test_runs_selection",
           "get_test_runs_v1"
+        ],
+        "key_facts": [
+          "Only test_case_ids / selection / shared_selection put cases in a run. `filters` and `dynamic_filter` are a forward-sync rule, NOT a selection: a create carrying only `filters` returns 200 with ZERO cases, and sets is_dynamic: true even though you did not ask. Verified live.",
+          "Dynamic runs match on nine fields only: priority, status, category, owner, automation_status, automation_state, folder, tags, issues. created_at/updated_at are stored and echoed on read but NEVER matched, so a 'last 7 days' dynamic run drops the date window and over-collects forever. Create runs static unless the user explicitly asks for sync.",
+          "test_run.run_state is MANDATORY on create and edit (new_run | in_progress | under_review | rejected | done | closed). It is validated before the selection, so a bare 400 'invalid data' means a bad test_run field — NOT a bad selection shape.",
+          "A run's `id` FIELD is the TR-NNN STRING, not the integer — on the project list, a plan's linked-run list and the single-run detail alike. The integer lives in `uuid` ({id: 'TR-90', uuid: 198}). Paths tolerate either form, which hides this; bodies and UI paths do not. Carrying `id` into a test plan's test_runs array sends a string that reaches the upstream service uncoerced and 502s there. Take `uuid` whenever a run id leaves a read.",
+          "Full lifecycle is exposed: create, edit, assign, bulk-assign cases, bulk-edit results, clone, close, delete."
         ]
       },
       "user": {
@@ -19755,6 +20047,10 @@
         "capabilities": [
           "get_group_users_v2_v1",
           "search_project_users"
+        ],
+        "key_facts": [
+          "WRITE BODIES take the integer: test_case.owner, test_run.owner/assignee_id — send 14.",
+          "An unrecognised q key is dropped, not rejected — the server silently omits that condition and returns an unfiltered set that looks like a successful filter. Use the documented key names verbatim."
         ]
       },
       "version": {
@@ -19786,6 +20082,11 @@
           "get_test_case_history_diff_v1",
           "get_test_case_history_v1",
           "restore_history_v1"
+        ],
+        "key_facts": [
+          "Each record carries source (create/update), modified_fields, a modified map (per-field old/new), user and created_at.",
+          "diff (compare two versions) and restore require a PAID plan; listing + single-version reads work otherwise. Degrade gracefully.",
+          "A plain-language diff summary is agent-side — read the field deltas and describe them; the API returns structured data, not prose."
         ]
       }
     }