Document create, update, and delete detection rule MCP tools (#37687)

* [NOJIRA][docs] Document create, update, and delete detection rule MCP tools

Add three new write tools to the security MCP toolset docs:
- create_datadog_security_detection_rule
- update_datadog_security_detection_rule
- delete_datadog_security_detection_rules

Updated in both security/mcp_server.md and mcp_server/tools.md.
Also updated the use cases section to reflect write capabilities.

* [docs] Remove datadog_mcp:created/updated tag mentions from detection rule tool docs

* [docs] Add enable/disable examples to update detection rule tool docs

* Fix wording

* Remove em dash.

Author: hachem-dd

content/en/mcp_server/tools.md

@@ -1193,6 +1193,34 @@ Retrieves security detection rules. Supports two modes: provide `rule_id` to get
 - Get the full definition of detection rule `abc-123-def`.
 - What thresholds and group-by fields does this detection rule use?
 
+### `create_datadog_security_detection_rule`
+*Toolset: **security***\
+*Permissions Required: `Security Monitoring Rules Write`*\
+Creates a new detection rule. Call `get_datadog_security_detection_rules_schema` first to fetch the payload grammar, then supply a complete rule payload. On success, returns the full rule including its server-assigned ID.
+
+- Create a threshold detection rule that fires when more than 10 failed logins occur from the same IP in 5 minutes.
+- Author a new log detection rule for CloudTrail that alerts on IAM privilege escalation.
+- Create a detection rule for `source:nginx` that generates a signal when error rate exceeds 100 per minute.
+
+### `update_datadog_security_detection_rule`
+*Toolset: **security***\
+*Permissions Required: `Security Monitoring Rules Write`*\
+Updates an existing custom detection rule by replacing it entirely. Call `get_datadog_security_detection_rules` first to fetch the current rule body, modify the fields you need, and submit the full updated object. Cannot update Datadog-shipped default rules.
+
+- Enable detection rule `abc-123-def`.
+- Disable the brute force detection rule.
+- Update the threshold on my brute force detection rule from 10 to 20 failed logins.
+- Add a new case to detection rule `abc-123-def` that fires at critical severity.
+- Change the group-by field on this rule from `@usr.ip` to `@network.client.ip`.
+
+### `delete_datadog_security_detection_rules`
+*Toolset: **security***\
+*Permissions Required: `Security Monitoring Rules Write`*\
+Deletes one or more custom detection rules by ID. Only custom (non-default) rules can be deleted. Default rules return 403. Each rule is authorized individually; failures appear in `failed_rules` without aborting the batch.
+
+- Delete detection rule `abc-123-def`.
+- Remove these three test detection rules I created earlier.
+
 ### `get_datadog_security_suppressions`
 *Toolset: **security***\
 *Permissions Required: `Security Monitoring Suppressions Read`*\
@@ -1377,7 +1405,7 @@ Fetches aggregated code coverage summary metrics for a repository commit, includ
 ### `get_datadog_code_coverage_pr_summary`
 *Toolset: **software-delivery***\
 *Permissions Required: `Code Coverage read`*\
-Fetches aggregated code coverage summary metrics for a pull request, including total coverage, patch coverage, and service or codeowner breakdowns.
+Fetches aggregated code coverage summary metrics for a pull request, including total coverage, patch coverage, and service or codeowner breakdowns.
 
 - Show me the code coverage for PR #123 in `github.com/my-org/my-repo`.
 - What's the patch coverage for pull request #456 in `github.com/my-org/my-repo`?
@@ -1389,7 +1417,7 @@ Fetches per-file code coverage line data for a repository commit, branch, or pul
 
 - Show me per-file coverage for PR #123 in `github.com/my-org/my-repo`.
 - Get changed-file coverage for commit `abc123abc123abc123abc123abc123abc123abcd` in `github.com/my-org/my-repo`.
-- Show coverage for the `main` branch of `github.com/my-org/my-repo`, filtered by codeowner `@my-org/my-team`.`
+- Show coverage for the `main` branch of `github.com/my-org/my-repo`, filtered by codeowner `@my-org/my-team`.`
 
 ### `get_datadog_test_optimization_settings`
 *Toolset: **software-delivery***\

content/en/security/mcp_server.md

@@ -40,7 +40,7 @@ You can use the `security` toolset to:
 - **Investigate specific findings**: Retrieve full details for a set of findings to understand scope, affected resources, and remediation context.
 - **Triage security findings**: Create Jira issues, ServiceNow tickets, or Case Management cases for findings. Assign findings to team members, or mute false positives and accepted risks.
 - **Correlate signals and findings**: Cross-reference active security signals with open findings to determine whether an alert is tied to a known posture issue.
-- **Inspect and manage detection rules**: List and retrieve detection rule definitions to understand what logic is generating signals.
+- **Inspect and manage detection rules**: List, retrieve, create, update, and delete detection rules to understand and manage the logic generating signals.
 - **Manage suppressions**: Create, update, and delete suppressions to silence noisy rules for specific conditions without disabling them entirely.
 - **Remediate vulnerabilities with an AI agent**: Pull library vulnerability findings, including code location and remediation guidance, and pass them to your AI agent to apply patches directly in your codebase.
 
@@ -126,6 +126,18 @@ The `security` toolset exposes the following tools to your AI client. Each tool
 : Retrieves security detection rules. Supports two modes: provide `rule_id` to get the full definition of a single rule by ID, or omit `rule_id` to list rules (optionally filtered with `query` and token-limited with `max_tokens`). The two modes are mutually exclusive.
 : *Permissions required: `Security Monitoring Rules Read`*
 
+`create_datadog_security_detection_rule`
+: Creates a new detection rule. Call `get_datadog_security_detection_rules_schema` first to fetch the required payload grammar, then supply a complete rule payload. On success, returns the full rule including its server-assigned ID.
+: *Permissions required: `Security Monitoring Rules Write`*
+
+`update_datadog_security_detection_rule`
+: Updates an existing custom detection rule by replacing it entirely. Use this to enable or disable a rule, change thresholds, add cases, and more. Call `get_datadog_security_detection_rules` first to fetch the current rule body, modify the fields you need to change, and submit the full updated object. Cannot update Datadog-shipped default rules. On success, returns the full updated rule.
+: *Permissions required: `Security Monitoring Rules Write`*
+
+`delete_datadog_security_detection_rules`
+: Deletes one or more custom detection rules by ID. Only custom (non-default) rules can be deleted. Each rule is authorized individually; rules that cannot be deleted appear in `failed_rules` without aborting the batch. Returns `deleted_rules` and `failed_rules`.
+: *Permissions required: `Security Monitoring Rules Write`*
+
 ### Suppressions
 
 `get_datadog_security_suppressions`