diff --git a/packages/mcp-server/src/tools/use-sentry/handler.ts b/packages/mcp-server/src/tools/use-sentry/handler.ts
index fcf2de91e..d25458ed2 100644
--- a/packages/mcp-server/src/tools/use-sentry/handler.ts
+++ b/packages/mcp-server/src/tools/use-sentry/handler.ts
@@ -39,10 +39,33 @@ export default defineTool({
requiredSkills: [], // Only available in agent mode - bypasses authorization
requiredScopes: [], // No specific scopes - uses authentication token
description: [
- "Use Sentry's MCP Agent to answer questions related to Sentry (sentry.io).",
+ "Natural language interface to Sentry via an embedded AI agent.",
"",
- "You should pass the entirety of the user's prompt to the agent. Do not interpret the prompt in any way. Just pass it directly to the agent.",
+ "Use this tool when you need to:",
+ "- Perform complex multi-step operations",
+ "- Explore and analyze Sentry data with natural language",
+ "- Chain multiple operations automatically",
"",
+ "Capabilities depend on granted skills:",
+ "- inspect: Search errors/events, analyze traces, explore issues and projects",
+ "- seer: Get AI-powered debugging insights and root cause analysis",
+ "- docs: Search and retrieve Sentry documentation",
+ "- triage: Resolve, assign, comment on, and update issues",
+ "- project-management: Create/modify teams, projects, and configure DSNs",
+ "",
+ "",
+ "use_sentry(request='find unresolved errors from yesterday')",
+ "use_sentry(request='analyze the top 3 performance issues')",
+ "use_sentry(request='create a backend team and assign them to API project')",
+ "",
+ "",
+ "",
+ "- If user asks to 'use Sentry' for something, they always mean to call this tool",
+ "- Pass the user's request verbatim - do not interpret or rephrase",
+ "- The agent can chain multiple tool calls automatically",
+ "- Use trace=true parameter to see which tools were called",
+ "- For simple single-tool operations, consider calling tools directly instead",
+ "",
].join("\n"),
inputSchema: {
request: z