fix(search): Use query for agent-assisted search

Collapse natural language search input into the existing query parameter and run configured agent providers as a repair pass over query, dataset, fields, sort, and time hints.

Update generated definitions, docs, evals, and tests so search tools expose query as the single input for both natural language and direct Sentry syntax.

Co-Authored-By: Codex GPT-5 <codex@openai.com>

Author: dcramer

docs/adding-tools.md

@@ -294,7 +294,7 @@ Some tools (`search_events` and `search_issues`) embed AI agents to handle compl
 // Tool handler delegates to embedded agent
 async handler(params, context) {
   // 1. Embedded agent translates natural language
-  const translated = await translateQuery(params.naturalLanguageQuery, ...);
+  const translated = await translateQuery(params.query, ...);
 
   // 2. Tool executes the translated query
   const results = await apiService.searchEvents(translated.query, ...);

docs/architecture.md

@@ -279,7 +279,7 @@ Some tools (`search_events` and `search_issues`) implement a two-tier agent patt
 ```
 1. User: "Show me errors from yesterday"
    ↓
-2. Claude: Calls search_events(naturalLanguageQuery="errors from yesterday")
+2. Claude: Calls search_events(query="errors from yesterday")
    ↓
 3. MCP Tool Handler: Receives request
    ↓

docs/specs/search-events.md

@@ -15,7 +15,7 @@ A unified search tool that accepts natural language queries and translates them
 ```typescript
 interface SearchEventsParams {
   organizationSlug: string;      // Required
-  naturalLanguageQuery: string;  // Natural language search description
+  query: string;  // Natural language search description
   dataset?: "spans" | "errors" | "logs" | "metrics"; // Dataset to search (default: "errors")
   projectSlug?: string;          // Optional - limit to specific project
   regionUrl?: string;           
@@ -30,28 +30,28 @@ interface SearchEventsParams {
 // Find errors (errors dataset is default)
 search_events({
   organizationSlug: "my-org",
-  naturalLanguageQuery: "database timeouts in checkout flow from last hour"
+  query: "database timeouts in checkout flow from last hour"
 })
 
 // Find slow transactions
 search_events({
   organizationSlug: "my-org",
-  naturalLanguageQuery: "API calls taking over 5 seconds",
+  query: "API calls taking over 5 seconds",
   projectSlug: "backend",
   dataset: "spans"
 })
 
 // Find logs
 search_events({
   organizationSlug: "my-org",
-  naturalLanguageQuery: "warning logs about memory usage",
+  query: "warning logs about memory usage",
   dataset: "logs"
 })
 
 // Find request duration metrics
 search_events({
   organizationSlug: "my-org",
-  naturalLanguageQuery: "p95 request duration by transaction this week",
+  query: "p95 request duration by transaction this week",
   dataset: "metrics"
 })
 ```
@@ -125,7 +125,7 @@ find_errors({
 // After
 search_events({
   organizationSlug: "sentry",
-  naturalLanguageQuery: "unresolved errors in checkout.js"
+  query: "unresolved errors in checkout.js"
 })
 ```
 

docs/testing-remote.md

@@ -343,7 +343,7 @@ Opens at `http://localhost:6274`
 // Test search_events with AI
 {
   "organizationSlug": "your-org",
-  "naturalLanguageQuery": "errors in the last hour",
+  "query": "errors in the last hour",
   "dataset": "errors"
 }
 ```

docs/testing-stdio.md

@@ -198,7 +198,7 @@ This opens the MCP Inspector at `http://localhost:6274`
 1. **List Tools** - Verify expected tools appear
 2. **Call a tool** - Start with `whoami` (no parameters required)
 3. **Test with parameters** - Try `find_organizations()`
-4. **Test complex operations** - Try `search_events(naturalLanguageQuery="errors in the last hour")`
+4. **Test complex operations** - Try `search_events(query="errors in the last hour")`
 
 **Example test sequence:**
 ```
@@ -207,7 +207,7 @@ This opens the MCP Inspector at `http://localhost:6274`
 3. find_projects(organizationSlug="your-org")
 4. search_events(
      organizationSlug="your-org",
-     naturalLanguageQuery="errors from yesterday"
+     query="errors from yesterday"
    )
 ```
 
@@ -485,8 +485,8 @@ OPENAI_API_KEY=your-key pnpm start --access-token=TOKEN
 
 # Test search_events and search_issues work
 # In MCP Inspector:
-# - Call search_events(naturalLanguageQuery="errors in production")
-# - Call search_issues(naturalLanguageQuery="unresolved crashes")
+# - Call search_events(query="errors in production")
+# - Call search_issues(query="unresolved crashes")
 ```
 
 ### 5. Test Agent Mode

packages/mcp-core/src/internal/formatting.ts

@@ -1929,7 +1929,7 @@ export function formatIssueOutput({
   output += `- You can reference the IssueID in commit messages (e.g. \`Fixes ${issue.shortId}\`) to automatically close the issue when the commit is merged.\n`;
   output +=
     "- The stacktrace includes both first-party application code as well as third-party code, its important to triage to first-party code.\n";
-  output += `- To search for specific occurrences or filter events within this issue, use \`search_issue_events(organizationSlug='${organizationSlug}', issueId='${issue.shortId}', naturalLanguageQuery='your query')\`\n`;
+  output += `- To search for specific occurrences or filter events within this issue, use \`search_issue_events(organizationSlug='${organizationSlug}', issueId='${issue.shortId}', query='your query')\`\n`;
   if (experimentalMode) {
     output += `- To see the trail of events leading up to this error, use \`get_sentry_resource(url='${apiService.getIssueUrl(organizationSlug, issue.shortId)}', resourceType='breadcrumbs')\`\n`;
   }

packages/mcp-core/src/skillDefinitions.json

@@ -772,27 +772,22 @@
   },
   {
     "name": "search_events",
-    "description": "Search Sentry events and replays. This is the ONLY tool for counts/statistics on event datasets.\n\nProvide `naturalLanguageQuery` to let an embedded agent determine dataset, query, fields, and sort,\nor provide these directly with Sentry search syntax.\n\nSupports TWO query types:\n1. AGGREGATIONS (counts, sums, averages): 'how many errors', 'total tokens'\n2. Individual events with timestamps: 'error logs from last hour'\n\nDatasets:\n- errors: Exception/crash events with stack traces, usually grouped into issues\n- logs: Application log entries, including error-severity log messages\n- spans: Raw trace/span events for performance, AI/LLM calls, requests, and operations\n- metrics: Metric rows and aggregates, including counters, gauges, distributions, and metric values\n- profiles: Transaction and continuous profile results, profile IDs, and profiled transactions\n- replays: Session replay results such as rage clicks, dead clicks, visited pages, and replay users\nIf the user says logs, log messages, error logs, or warning logs, choose logs instead of errors.\n\nReplay searches on this tool return replay lists only. Replay count()/avg()/sum() aggregations are not supported.\n\nDO NOT USE for grouped issue lists → use search_issues\n\n<examples>\nsearch_events(organizationSlug='my-org', naturalLanguageQuery='how many errors today')\nsearch_events(organizationSlug='my-org', dataset='errors', query='level:error')\nsearch_events(organizationSlug='my-org', dataset='errors', fields=['issue', 'count()'], sort='-count()')\nsearch_events(organizationSlug='my-org', dataset='spans', query='span.op:db', sort='-span.duration')\nsearch_events(organizationSlug='my-org', dataset='replays', query='count_errors:>0', sort='-count_errors')\n</examples>\n\n<hints>\n- If the user passes a parameter in the form of name/otherName, it's likely in the format of <organizationSlug>/<projectSlug>.\n- Parse org/project notation directly without calling find_organizations or find_projects.\n- Use fields with aggregate functions like count(), avg(), sum() for statistics\n- Sort by -count() for most common, -timestamp for newest\n</hints>",
+    "description": "Search Sentry events and replays. Use for event counts/statistics.\n\n`query` can be natural language or Sentry search syntax. With an agent configured, it fixes dataset, query, fields, and sort before running.\n\nSupports TWO query types:\n1. AGGREGATIONS (counts, sums, averages): 'how many errors', 'total tokens'\n2. Individual events with timestamps: 'error logs from last hour'\n\nDatasets:\n- errors: Exception/crash events with stack traces, usually grouped into issues\n- logs: Application log entries, including error-severity log messages\n- spans: Raw trace/span events for performance, AI/LLM calls, requests, and operations\n- metrics: Metric rows and aggregates: counters, gauges, distributions, values\n- profiles: Transaction/continuous profile results, profile IDs, profiled transactions\n- replays: Session replay results: rage clicks, dead clicks, visited pages, replay users\nIf the user says logs, log messages, error logs, or warning logs, choose logs instead of errors.\n\nReplay searches return replay lists only; replay count()/avg()/sum() are not supported.\n\nDO NOT USE for grouped issue lists → use search_issues\n\n<examples>\nsearch_events(organizationSlug='my-org', query='how many errors today')\nsearch_events(organizationSlug='my-org', dataset='errors', query='level:error')\nsearch_events(organizationSlug='my-org', dataset='errors', fields=['issue', 'count()'], sort='-count()')\nsearch_events(organizationSlug='my-org', dataset='spans', query='span.op:db', sort='-span.duration')\nsearch_events(organizationSlug='my-org', dataset='replays', query='count_errors:>0', sort='-count_errors')\n</examples>\n\n<hints>\n- If the user passes a parameter in the form of name/otherName, it's likely in the format of <organizationSlug>/<projectSlug>.\n- Parse org/project notation directly without calling find_organizations or find_projects.\n- Use fields with aggregate functions like count(), avg(), sum() for statistics\n- Sort by -count() for most common, -timestamp for newest\n</hints>",
     "inputSchema": {
       "type": "object",
       "properties": {
         "organizationSlug": {
           "type": "string",
           "description": "The organization's slug. You can find a existing list of organizations you have access to using the `find_organizations()` tool."
         },
-        "naturalLanguageQuery": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Natural language description of what you want to search for. When provided, an embedded agent determines the dataset, query, fields, and sort."
-        },
         "dataset": {
           "type": "string",
           "enum": ["spans", "errors", "logs", "metrics", "profiles", "replays"],
-          "description": "Dataset to query when naturalLanguageQuery is not provided: errors, logs, spans, metrics, profiles, or replays."
+          "description": "Initial dataset hint: errors, logs, spans, metrics, profiles, or replays. The agent may correct this when configured."
         },
         "query": {
           "type": "string",
-          "description": "Sentry event search query syntax. Used when naturalLanguageQuery is not provided."
+          "description": "Natural language or Sentry event search query syntax."
         },
         "fields": {
           "anyOf": [
@@ -858,7 +853,7 @@
         },
         "statsPeriod": {
           "type": "string",
-          "description": "Time period: 1h, 24h, 7d, 14d, 30d, etc. Used when naturalLanguageQuery is not provided."
+          "description": "Initial time period hint: 1h, 24h, 7d, 14d, 30d, etc."
         },
         "regionUrl": {
           "anyOf": [
@@ -883,7 +878,7 @@
         "includeExplanation": {
           "type": "boolean",
           "default": false,
-          "description": "Include explanation of how the query was translated (only applies with naturalLanguageQuery)"
+          "description": "Include explanation of how the query was translated or repaired"
         }
       },
       "required": ["organizationSlug"],
@@ -894,7 +889,7 @@
   },
   {
     "name": "search_issue_events",
-    "description": "Search and filter events within a specific issue.\n\nProvide `naturalLanguageQuery` to let an embedded agent determine the correct filters,\nor use `query` and `sort` directly with Sentry search syntax.\n\nThe tool automatically constrains results to the specified issue.\n\nCommon Query Filters:\n- environment:production - Filter by environment\n- release:1.0.0 - Filter by release version\n- user.email:alice@example.com - Filter by user\n- trace:TRACE_ID - Filter by trace ID\n\nFor cross-issue searches use search_issues. For single issue or event details use get_sentry_resource.\n\n<examples>\nsearch_issue_events(issueId='MCP-41', organizationSlug='my-org', naturalLanguageQuery='from last hour')\nsearch_issue_events(issueId='MCP-41', organizationSlug='my-org', query='environment:production')\nsearch_issue_events(issueUrl='https://sentry.io/.../issues/123/', query='release:v1.0.0', statsPeriod='7d')\n</examples>",
+    "description": "Search and filter events within a specific issue.\n\nProvide `query` as natural language or Sentry event search syntax. When an embedded agent is configured, it fixes filters, fields, sort, and time range before running.\n\nThe tool automatically constrains results to the specified issue.\n\nCommon Query Filters:\n- environment:production - Filter by environment\n- release:1.0.0 - Filter by release version\n- user.email:alice@example.com - Filter by user\n- trace:TRACE_ID - Filter by trace ID\n\nFor cross-issue searches use search_issues. For single issue or event details use get_sentry_resource.\n\n<examples>\nsearch_issue_events(issueId='MCP-41', organizationSlug='my-org', query='from last hour')\nsearch_issue_events(issueId='MCP-41', organizationSlug='my-org', query='environment:production')\nsearch_issue_events(issueUrl='https://sentry.io/.../issues/123/', query='release:v1.0.0', statsPeriod='7d')\n</examples>",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -920,22 +915,17 @@
           "format": "uri",
           "description": "Full Sentry issue URL (e.g., 'https://sentry.io/organizations/my-org/issues/123/'). Includes both organization and issue ID."
         },
-        "naturalLanguageQuery": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Natural language description of what events to find within this issue. When provided, an embedded agent determines the correct filters, fields, sort, and time range."
-        },
         "query": {
           "type": "string",
-          "description": "Sentry event search query syntax for filtering within the issue. Used when naturalLanguageQuery is not provided."
+          "description": "Natural language or Sentry event search query syntax for filtering within the issue."
         },
         "sort": {
           "type": "string",
           "description": "Sort field (prefix with - for descending). Default: -timestamp"
         },
         "statsPeriod": {
           "type": "string",
-          "description": "Time period: 1h, 24h, 7d, 14d, 30d, etc. Used when naturalLanguageQuery is not provided."
+          "description": "Initial time period hint: 1h, 24h, 7d, 14d, 30d, etc."
         },
         "projectSlug": {
           "anyOf": [
@@ -973,7 +963,7 @@
         "includeExplanation": {
           "type": "boolean",
           "default": false,
-          "description": "Include explanation of how the query was translated (only applies with naturalLanguageQuery)"
+          "description": "Include explanation of how the query was translated or repaired"
         }
       },
       "additionalProperties": false,
@@ -983,23 +973,18 @@
   },
   {
     "name": "search_issues",
-    "description": "Search for grouped issues/problems in Sentry - returns a LIST of issues, NOT counts or aggregations.\n\nProvide `naturalLanguageQuery` to let an embedded agent determine the correct query and sort params,\nor use `query` and `sort` directly with Sentry search syntax.\n\nReturns grouped issues with metadata like title, status, and user count.\n\nCommon Query Syntax:\n- is:unresolved / is:resolved / is:ignored\n- level:error / level:warning\n- firstSeen:-24h / lastSeen:-7d\n- assigned:me / assignedOrSuggested:me\n- issueCategory:feedback\n- environment:production\n- userCount:>100\n\nDO NOT USE FOR COUNTS/AGGREGATIONS → use search_events\nDO NOT USE FOR individual events with timestamps → use search_events\nDO NOT USE FOR details about a specific issue → use get_sentry_resource\n\n<examples>\nsearch_issues(organizationSlug='my-org', naturalLanguageQuery='critical bugs from last week')\nsearch_issues(organizationSlug='my-org', query='is:unresolved is:unassigned', sort='freq')\nsearch_issues(organizationSlug='my-org', query='level:error firstSeen:-24h', projectSlugOrId='my-project')\n</examples>\n\n<hints>\n- If the user passes a parameter in the form of name/otherName, it's likely in the format of <organizationSlug>/<projectSlugOrId>.\n- Parse org/project notation directly without calling find_organizations or find_projects.\n- The projectSlugOrId parameter accepts both project slugs (e.g., 'my-project') and numeric IDs (e.g., '123456').\n</hints>",
+    "description": "Search for grouped issues/problems in Sentry - returns a LIST of issues, NOT counts or aggregations.\n\nProvide `query` as natural language or Sentry issue search syntax. When an embedded agent is configured, it fixes query and sort before running.\n\nReturns grouped issues with metadata like title, status, and user count.\n\nCommon Query Syntax:\n- is:unresolved / is:resolved / is:ignored\n- level:error / level:warning\n- firstSeen:-24h / lastSeen:-7d\n- assigned:me / assignedOrSuggested:me\n- issueCategory:feedback\n- environment:production\n- userCount:>100\n\nDO NOT USE FOR COUNTS/AGGREGATIONS → use search_events\nDO NOT USE FOR individual events with timestamps → use search_events\nDO NOT USE FOR details about a specific issue → use get_sentry_resource\n\n<examples>\nsearch_issues(organizationSlug='my-org', query='critical bugs from last week')\nsearch_issues(organizationSlug='my-org', query='is:unresolved is:unassigned', sort='freq')\nsearch_issues(organizationSlug='my-org', query='level:error firstSeen:-24h', projectSlugOrId='my-project')\n</examples>\n\n<hints>\n- If the user passes a parameter in the form of name/otherName, it's likely in the format of <organizationSlug>/<projectSlugOrId>.\n- Parse org/project notation directly without calling find_organizations or find_projects.\n- The projectSlugOrId parameter accepts both project slugs (e.g., 'my-project') and numeric IDs (e.g., '123456').\n</hints>",
     "inputSchema": {
       "type": "object",
       "properties": {
         "organizationSlug": {
           "type": "string",
           "description": "The organization's slug. You can find a existing list of organizations you have access to using the `find_organizations()` tool."
         },
-        "naturalLanguageQuery": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Natural language description of issues to search for. When provided, an embedded agent translates this into the correct query and sort params."
-        },
         "query": {
           "type": "string",
           "default": "is:unresolved",
-          "description": "Sentry issue search query syntax. Used when naturalLanguageQuery is not provided."
+          "description": "Natural language or Sentry issue search query syntax."
         },
         "sort": {
           "type": "string",
@@ -1042,7 +1027,7 @@
         "includeExplanation": {
           "type": "boolean",
           "default": false,
-          "description": "Include explanation of how the query was translated (only applies with naturalLanguageQuery)"
+          "description": "Include explanation of how the query was translated or repaired"
         }
       },
       "required": ["organizationSlug"],