feat(mcp): Add a display title to every tool

docs/contributing/adding-tools.md

@@ -72,6 +72,7 @@ import type { ServerContext } from "../../types";
 
 export default defineTool({
   name: "your_tool_name",
+  title: "Your Tool Name",
   description: [
     "One-line summary.",
     "",
@@ -103,6 +104,14 @@ export default defineTool({
 });
 ```
 
+### Title
+
+**REQUIRED**: Every tool sets `title`, a short Title Case display name such as
+`"Search Issues"`. The server exports it as the MCP tool `title`, which clients
+show instead of the snake_case `name`. Titles must be unique across tools;
+`tools.test.ts` enforces this. Deprecated aliases add a ` (Deprecated)`
+suffix, for example `"Search AI Conversations (Deprecated)"`.
+
 ### Safety Annotations
 
 **REQUIRED**: Every tool must declare `readOnlyHint`, `destructiveHint`, and

packages/mcp-core/scripts/generate-definitions.ts

@@ -76,6 +76,7 @@ type DefinitionTool = {
         availableToolNames?: ReadonlySet<string>;
         directToolNames?: ReadonlySet<string>;
       }) => string);
+  title: string;
   inputSchema: Record<string, ZodTypeAny>;
   outputSchema?: ZodTypeAny;
   skills: string[];
@@ -159,6 +160,7 @@ function generateToolDefinitions({
     const surface: ToolSurface = isDirect ? "direct" : "catalog";
     return {
       name: t.name,
+      title: t.title,
       description: toolTypesModule.resolveDescription(t.description, {
         experimentalMode,
         availableToolNames,

packages/mcp-core/scripts/measure-token-cost.ts

@@ -55,6 +55,7 @@ Examples:
 
 type ToolDefinition = {
   name: string;
+  title: string;
   description: string | ((context: { experimentalMode: boolean }) => string);
   inputSchema: Record<string, ZodTypeAny>;
   experimental?: boolean;
@@ -87,6 +88,7 @@ function formatToolsForMCP(tools: Record<string, ToolDefinition>) {
 
     return {
       name: tool.name,
+      title: tool.title,
       description: toolTypesModule.resolveDescription(tool.description, {
         experimentalMode: false,
       }),

packages/mcp-core/src/internal/fresh-reads.test.ts

@@ -10,6 +10,7 @@ function probeTool() {
   const calls: { params: Record<string, unknown>; fresh: boolean }[] = [];
   const tool = withFreshReadInput({
     name: "probe",
+    title: "Probe",
     description: "Probe",
     inputSchema: { id: z.string() },
     skills: ["inspect"],

packages/mcp-core/src/internal/tool-helpers/default-organization.test.ts

@@ -13,6 +13,7 @@ import type { CredentialRouter, ServerContext } from "../../types";
 
 const requiredOrgTool: ToolConfig<any> = {
   name: "required_org_tool",
+  title: "Required Org Tool",
   description: "required_org_tool description",
   skills: ["inspect"],
   requiredScopes: [],

packages/mcp-core/src/server-capabilities.test.ts

@@ -16,6 +16,7 @@ const context: ServerContext = {
 const tools: Record<string, ToolConfig> = {
   static_tool: {
     name: "static_tool",
+    title: "Static Tool",
     description: "A tool fixed for the lifetime of the server",
     inputSchema: {},
     skills: ["inspect"],

packages/mcp-core/src/server.all-tools.test.ts

@@ -80,6 +80,22 @@ describe.skipIf(!EXPOSE_ALL_TOOLS)("buildServer with EXPOSE_ALL_TOOLS", () => {
     expect(toolNames).toContain("create_project");
   });
 
+  it("exports each tool's title in tools/list", async () => {
+    const listed = await withClient(
+      getContext(),
+      async (client) => (await client.listTools()).tools,
+    );
+    const titles = new Map(
+      Object.values(tools).map((tool) => [tool.name, tool.title]),
+    );
+
+    expect(listed.length).toBeGreaterThan(0);
+    for (const tool of listed) {
+      expect(tool.title, tool.name).toBe(titles.get(tool.name));
+      expect(tool.title?.trim(), tool.name).toBeTruthy();
+    }
+  });
+
   it("lists the replacements of deprecated tools instead of the tools", async () => {
     const toolNames = await listToolNames(getContext());
     const deprecatedTools = Object.values(tools).filter(

packages/mcp-core/src/server.test.ts

@@ -173,6 +173,7 @@ describe("buildServer", () => {
     options: Partial<ToolConfig> = {},
   ): ToolConfig => ({
     name,
+    title: `${name} title`,
     description: `${name} description`,
     inputSchema: {},
     skills: ["inspect"],

packages/mcp-core/src/server.ts

@@ -394,6 +394,7 @@ function configureServer({
     });
 
     const toolRegistration = {
+      title: tool.title,
       description: resolvedDescription,
       inputSchema: filteredInputSchema,
       outputSchema: tool.outputSchema,

packages/mcp-core/src/toolDefinitions.ts

@@ -7,6 +7,8 @@ export type ToolDefinitionSurface = "direct" | "catalog";
 
 export interface ToolDefinition {
   name: string;
+  // Human-readable display name
+  title: string;
   description: string;
   // Full JSON Schema object for parameters
   inputSchema: unknown;

packages/mcp-core/src/tools/catalog/add-issue-note.ts

@@ -36,6 +36,7 @@ function formatComment(comment: IssueComment): string {
 
 export default defineTool({
   name: "add_issue_note",
+  title: "Add Issue Note",
   skills: ["triage"],
   requiredScopes: ["event:write"],
   description: [

packages/mcp-core/src/tools/catalog/add-team-to-project.ts

@@ -33,6 +33,7 @@ function mapTeam(team: Team) {
 
 export default defineTool({
   name: "add_team_to_project",
+  title: "Add Team to Project",
   skills: ["project-management"],
   requiredScopes: ["project:write", "team:read", "org:read"],
   description: [

packages/mcp-core/src/tools/catalog/analyze-issue-with-seer.ts

@@ -31,6 +31,7 @@ import type { ServerContext } from "../../types";
 
 export default defineTool({
   name: "analyze_issue_with_seer",
+  title: "Analyze Issue with Seer",
   skills: ["seer"], // Only available in seer skill
   requiredScopes: [], // No Sentry API scopes required - authorization via 'seer' skill
   description: [

packages/mcp-core/src/tools/catalog/create-alert-rule.ts

@@ -22,6 +22,7 @@ import { resolveAlertRuleConnections } from "../support/alert-rule-connections";
 
 export default defineTool({
   name: "create_alert_rule",
+  title: "Create Alert Rule",
   skills: ["project-management"],
   requiredScopes: ["org:read", "project:read", "alerts:write"],
   description: [

packages/mcp-core/src/tools/catalog/create-dsn.ts

@@ -20,6 +20,7 @@ export const createDsnOutputSchema = z.object({
 
 export default defineTool({
   name: "create_dsn",
+  title: "Create DSN",
   skills: ["project-management"], // Only available in project-management skill
   requiredScopes: ["project:write"],
   description: [

packages/mcp-core/src/tools/catalog/create-metric-monitor.ts

@@ -22,6 +22,7 @@ import { assertProjectRefWithinConstraint } from "./support/project-constraints"
 
 export default defineTool({
   name: "create_metric_monitor",
+  title: "Create Metric Monitor",
   skills: ["project-management"],
   requiredScopes: ["org:read", "project:read", "alerts:write"],
   description: [

packages/mcp-core/src/tools/catalog/create-monitor.ts

@@ -110,6 +110,7 @@ function toMonitorSummary(
 
 export default defineTool({
   name: "create_monitor",
+  title: "Create Cron Monitor",
   skills: ["project-management"],
   requiredScopes: ["org:read", "project:read", "alerts:write"],
   description: [

packages/mcp-core/src/tools/catalog/create-project.ts

@@ -108,6 +108,7 @@ async function getOrCreateClientKey({
 
 export default defineTool({
   name: "create_project",
+  title: "Create Project",
   skills: ["project-management"], // Only available in project-management skill
   requiredScopes: ["project:write", "team:read", "org:read"],
   description: [

packages/mcp-core/src/tools/catalog/create-team.ts

@@ -16,6 +16,7 @@ export const createTeamOutputSchema = z.object({
 
 export default defineTool({
   name: "create_team",
+  title: "Create Team",
   skills: ["project-management"], // Only available in project-management skill
   requiredScopes: ["team:write"],
   description: [

packages/mcp-core/src/tools/catalog/create-uptime-monitor.ts

@@ -27,6 +27,7 @@ export const createUptimeMonitorOutputSchema = z.object({
 
 export default defineTool({
   name: "create_uptime_monitor",
+  title: "Create Uptime Monitor",
   skills: ["project-management"],
   requiredScopes: ["project:write"],
   description: [

packages/mcp-core/src/tools/catalog/delete-alert-rule.ts

@@ -13,6 +13,7 @@ import { validateAlertRuleProjectScope } from "../support/alert-rule-connections
 
 export default defineTool({
   name: "delete_alert_rule",
+  title: "Delete Alert Rule",
   skills: ["project-management"],
   requiredScopes: ["org:read", "project:read", "alerts:write"],
   description: [

packages/mcp-core/src/tools/catalog/delete-metric-monitor.ts

@@ -11,6 +11,7 @@ import {
 
 export default defineTool({
   name: "delete_metric_monitor",
+  title: "Delete Metric Monitor",
   skills: ["project-management"],
   requiredScopes: ["org:read", "project:read", "alerts:write"],
   description: [

packages/mcp-core/src/tools/catalog/delete-monitor-environment.ts

@@ -20,6 +20,7 @@ export const deleteMonitorEnvironmentOutputSchema = z.object({
 
 export default defineTool({
   name: "delete_monitor_environment",
+  title: "Delete Cron Monitor Environment",
   skills: ["project-management"],
   requiredScopes: ["project:write"],
   description: [

packages/mcp-core/src/tools/catalog/delete-uptime-monitor.ts

@@ -19,6 +19,7 @@ export const deleteUptimeMonitorOutputSchema = z.object({
 
 export default defineTool({
   name: "delete_uptime_monitor",
+  title: "Delete Uptime Monitor",
   skills: ["project-management"],
   requiredScopes: ["project:write"],
   description: [

packages/mcp-core/src/tools/catalog/find-alert-rules.ts

@@ -99,6 +99,7 @@ function getOwner(owner: unknown): string | null {
 
 export default defineTool({
   name: "find_alert_rules",
+  title: "Find Alert Rules",
   skills: ["inspect"],
   requiredScopes: ["org:read", "project:read"],
   description: [

packages/mcp-core/src/tools/catalog/find-dashboards.ts

@@ -223,6 +223,7 @@ async function listProjectVisibleDashboards({
 
 export default defineTool({
   name: "find_dashboards",
+  title: "Find Dashboards",
   skills: ["inspect"],
   requiredScopes: ["org:read"],
   description: [

packages/mcp-core/src/tools/catalog/find-dropped-events.ts

@@ -62,6 +62,7 @@ export const findDroppedEventsOutputSchema = z.object({
 
 export default defineTool({
   name: "find_dropped_events",
+  title: "Find Dropped Events",
   skills: ["inspect"],
   requiredScopes: ["event:read"],
   description: [

packages/mcp-core/src/tools/catalog/find-dsns.ts

@@ -22,6 +22,7 @@ export const findDsnsOutputSchema = z.object({
 
 export default defineTool({
   name: "find_dsns",
+  title: "Find DSNs",
   skills: ["project-management"], // DSN management is part of project setup
   requiredScopes: ["project:read"],
   description: [

packages/mcp-core/src/tools/catalog/find-metric-monitors.ts

@@ -23,6 +23,7 @@ export const findMetricMonitorsOutputSchema = z.object({
 
 export default defineTool({
   name: "find_metric_monitors",
+  title: "Find Metric Monitors",
   skills: ["inspect"],
   requiredScopes: ["org:read", "project:read"],
   description: [

packages/mcp-core/src/tools/catalog/find-monitors.ts

@@ -137,6 +137,7 @@ function getSchedule(monitor: Monitor) {
 
 export default defineTool({
   name: "find_monitors",
+  title: "Find Cron Monitors",
   skills: ["inspect"],
   requiredScopes: ["org:read"],
   description: [

packages/mcp-core/src/tools/catalog/find-organizations.ts

@@ -135,6 +135,7 @@ async function listAcrossAccounts(
 
 export default defineTool({
   name: "find_organizations",
+  title: "Find Organizations",
   skills: ALL_SKILLS, // Foundational tool - available to all skills
   requiredScopes: ["org:read"],
   description: [

packages/mcp-core/src/tools/catalog/find-projects.ts

@@ -27,6 +27,7 @@ export const findProjectsOutputSchema = z.object({
 
 export default defineTool({
   name: "find_projects",
+  title: "Find Projects",
   skills: ALL_SKILLS, // Foundational tool - available to all skills
   requiredScopes: ["project:read"],
   description: [

packages/mcp-core/src/tools/catalog/find-releases.ts

@@ -45,6 +45,7 @@ export const findReleasesOutputSchema = z.object({
 
 export default defineTool({
   name: "find_releases",
+  title: "Find Releases",
   skills: ["inspect"], // Only available in inspect skill
   requiredScopes: ["project:read"],
   description: [

packages/mcp-core/src/tools/catalog/find-teams.ts

@@ -27,6 +27,7 @@ export const findTeamsOutputSchema = z.object({
 
 export default defineTool({
   name: "find_teams",
+  title: "Find Teams",
   skills: ["inspect", "triage", "project-management"], // Team viewing and management
   requiredScopes: ["team:read"],
   description: [

packages/mcp-core/src/tools/catalog/find-uptime-monitors.ts

@@ -22,6 +22,7 @@ export const findUptimeMonitorsOutputSchema = z.object({
 
 export default defineTool({
   name: "find_uptime_monitors",
+  title: "Find Uptime Monitors",
   skills: ["inspect"],
   requiredScopes: ["org:read", "project:read"],
   description: [

packages/mcp-core/src/tools/catalog/get-agent-conversation-details.ts

@@ -660,6 +660,7 @@ function buildConversationArtifact(
 
 export default defineTool({
   name: "get_agent_conversation_details",
+  title: "Get Agent Conversation Details",
   skills: ["inspect", "triage", "seer"],
   requiredScopes: ["event:read", "project:read"],
 

packages/mcp-core/src/tools/catalog/get-alert-options.ts

@@ -50,6 +50,7 @@ export const getAlertOptionsOutputSchema = z.object({
 
 export default defineTool({
   name: "get_alert_options",
+  title: "Get Alert Options",
   skills: ["inspect"],
   requiredScopes: ["org:read", "project:read"],
   description: [

packages/mcp-core/src/tools/catalog/get-alert-rule.ts

@@ -51,6 +51,7 @@ function describeMatch(match: AlertRuleMatch): string {
 
 export default defineTool({
   name: "get_alert_rule",
+  title: "Get Alert Rule",
   skills: ["inspect"],
   requiredScopes: ["org:read", "project:read"],
   description: [

packages/mcp-core/src/tools/catalog/get-dashboard-details.ts

@@ -13,6 +13,7 @@ import {
 
 export default defineTool({
   name: "get_dashboard_details",
+  title: "Get Dashboard Details",
   skills: ["inspect"],
   requiredScopes: ["org:read"],
   description: [

packages/mcp-core/src/tools/catalog/get-doc.ts

@@ -9,6 +9,7 @@ import { USER_AGENT } from "../../version";
 
 export default defineTool({
   name: "get_doc",
+  title: "Get Sentry Doc",
   skills: ["inspect", "docs"], // Docs is retained for legacy docs-only grants.
   requiredScopes: [],
   description: [

packages/mcp-core/src/tools/catalog/get-event-attachment.ts

@@ -83,6 +83,7 @@ function formatOversizedAttachment(
 
 export default defineTool({
   name: "get_event_attachment",
+  title: "Get Event Attachment",
   skills: ["inspect"], // Only available in inspect skill
   requiredScopes: ["event:read"],
   description: [

packages/mcp-core/src/tools/catalog/get-event-stacktrace.ts

@@ -16,6 +16,7 @@ import { fetchAndFormatEventStacktrace } from "../support/event-stacktrace";
 
 export default defineTool({
   name: "get_event_stacktrace",
+  title: "Get Event Stacktrace",
   skills: ["inspect", "triage", "seer"],
   requiredScopes: ["event:read"],
   description: [

packages/mcp-core/src/tools/catalog/get-issue-activity.ts

@@ -60,6 +60,7 @@ function formatActivity(activity: IssueActivity | IssueComment): string {
 
 export default defineTool({
   name: "get_issue_activity",
+  title: "Get Issue Activity",
   skills: ["inspect", "triage"],
   requiredScopes: ["event:read"],
   description: [

packages/mcp-core/src/tools/catalog/get-issue-breadcrumbs.ts

@@ -19,6 +19,7 @@ import type { ServerContext } from "../../types";
 
 export default defineTool({
   name: "get_issue_breadcrumbs",
+  title: "Get Issue Breadcrumbs",
   skills: ["inspect", "triage"],
   requiredScopes: ["event:read"],
   description: [