fix(mcp): missing isDeployed in contract breaking settings, parameter overrides lack of clarity (#5164)

* fix(mcp): missing isDeployed in contract breaking settings, parameter overrides lack of clarity

* address comments

* address ux concern

* address stray 404

* address stale fallback based on live state

* fix

* fix more things

* simplify state mgmt

* add tooltip for server selection

Author: icecrasher321

apps/docs/content/docs/en/workflows/deployment/mcp.mdx

@@ -82,8 +82,8 @@ Once your workflow is deployed, you can expose it as an MCP tool:
   />
 </div>
 
-3. Configure the tool name and description
-4. Add descriptions for each parameter (helps AI understand inputs)
+3. Configure the tool name and description (the description defaults to the workflow's description)
+4. Review the parameter descriptions (prefilled from your Start block inputs) and override any per tool
 5. Select which MCP servers to add it to
 6. Click **Save Tool**
 
@@ -97,10 +97,14 @@ The workflow must be deployed before it can be added as an MCP tool.
 Use lowercase letters, numbers, and underscores. The name should be descriptive and follow MCP naming conventions (e.g., `search_documents`, `send_email`).
 
 ### Description
-Write a clear description of what the tool does. This helps AI assistants understand when to use the tool.
+Write a clear description of what the tool does. This helps AI assistants understand when to use the tool. If you leave it blank, the tool falls back to the workflow's description.
 
 ### Parameters
-Your workflow's input format fields become tool parameters. Add descriptions to each parameter to help AI assistants provide correct values.
+Your workflow's input format fields become tool parameters. Each parameter's description defaults to the description set on that input in the Start block; edit it here to override it for this tool (the Start block stays the default source). Descriptions help AI assistants provide correct values.
+
+<Callout type="info">
+Parameter descriptions live on your Start block inputs. A deployed tool picks up Start block changes the next time you redeploy the workflow; use a per-tool override only when a tool needs a different description than the default.
+</Callout>
 
 ## Connecting MCP Clients
 
@@ -220,7 +224,7 @@ Workflows execute using the same deployment version as API calls, ensuring consi
   { question: "How do I authenticate MCP client connections?", answer: "Include your API key in the X-API-Key header when connecting via mcp-remote or other HTTP-based MCP transports. The server validates authentication using hybrid auth that supports both session-based and API key-based access." },
   { question: "Can I add the same workflow to multiple MCP servers?", answer: "Yes. When configuring a workflow as an MCP tool, you can select multiple MCP servers to add it to. Each server exposes its own URL, so you can organize tools into different servers for different use cases or clients." },
   { question: "What naming conventions should I follow for tool names?", answer: "Use lowercase letters, numbers, and underscores only. The name should be descriptive and follow MCP naming conventions, such as search_documents or send_email. This helps AI assistants understand and correctly invoke your tools." },
-  { question: "How are workflow inputs mapped to MCP tool parameters?", answer: "Your workflow's input format fields automatically become MCP tool parameters. You can add descriptions to each parameter in the MCP configuration to help AI assistants understand what values to provide." },
+  { question: "How are workflow inputs mapped to MCP tool parameters?", answer: "Your workflow's input format fields automatically become MCP tool parameters. Each parameter's description defaults to the description set on that input in the Start block, and you can override it per tool in the MCP configuration to help AI assistants understand what values to provide." },
 ]} />
 
 

apps/sim/app/api/mcp/serve/[serverId]/route.ts

@@ -53,6 +53,7 @@ import {
   MCP_TOOL_BRIDGE_ACTOR_HEADER,
   MCP_TOOL_BRIDGE_HEADER,
 } from '@/lib/mcp/constants'
+import { getMeaningfulWorkflowDescription } from '@/lib/mcp/workflow-tool-schema'
 import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
 
 const logger = createLogger('WorkflowMcpServeAPI')
@@ -601,8 +602,11 @@ async function handleToolsList(
         toolName: workflowMcpTool.toolName,
         toolDescription: workflowMcpTool.toolDescription,
         parameterSchema: workflowMcpTool.parameterSchema,
+        workflowName: workflow.name,
+        workflowDescription: workflow.description,
       })
       .from(workflowMcpTool)
+      .innerJoin(workflow, eq(workflowMcpTool.workflowId, workflow.id))
       .where(
         and(
           eq(workflowMcpTool.serverId, serverId),
@@ -629,7 +633,10 @@ async function handleToolsList(
         )
         return {
           name: tool.toolName,
-          description: tool.toolDescription || `Execute workflow: ${tool.toolName}`,
+          description:
+            tool.toolDescription?.trim() ||
+            getMeaningfulWorkflowDescription(tool.workflowDescription, tool.workflowName) ||
+            `Execute workflow: ${tool.toolName}`,
           inputSchema: {
             type: 'object' as const,
             properties: schema?.properties || {},

apps/sim/app/api/mcp/workflow-servers/[id]/tools/[toolId]/route.ts

@@ -114,6 +114,7 @@ export const PATCH = withRouteHandler(
           actorEmail: userEmail,
           toolName: body.toolName,
           toolDescription: body.toolDescription,
+          parameterDescriptionOverrides: body.parameterDescriptionOverrides,
           parameterSchema: body.parameterSchema,
         })
         if (!result.success || !result.tool) {

apps/sim/app/api/mcp/workflow-servers/[id]/tools/route.ts

@@ -64,6 +64,7 @@ export const GET = withRouteHandler(
             toolName: workflowMcpTool.toolName,
             toolDescription: workflowMcpTool.toolDescription,
             parameterSchema: workflowMcpTool.parameterSchema,
+            parameterDescriptionOverrides: workflowMcpTool.parameterDescriptionOverrides,
             createdAt: workflowMcpTool.createdAt,
             updatedAt: workflowMcpTool.updatedAt,
             workflowName: workflow.name,
@@ -122,6 +123,7 @@ export const POST = withRouteHandler(
           workflowId: body.workflowId,
           toolName: body.toolName,
           toolDescription: body.toolDescription,
+          parameterDescriptionOverrides: body.parameterDescriptionOverrides,
           parameterSchema: body.parameterSchema,
         })
         if (!result.success || !result.tool) {

apps/sim/app/workspace/[workspaceId]/settings/components/workflow-mcp-servers/workflow-mcp-servers.tsx

@@ -4,7 +4,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
 import { Check, Clipboard, Plus, Server } from 'lucide-react'
-import { useParams } from 'next/navigation'
+import { useParams, useSearchParams } from 'next/navigation'
 import {
   Badge,
   Button,
@@ -186,7 +186,7 @@ function ServerDetailView({ workspaceId, serverId, onBack }: ServerDetailViewPro
         workspaceId,
         serverId,
         toolId: toolToView.id,
-        toolDescription: editingDescription.trim() || undefined,
+        toolDescription: editingDescription.trim(),
         parameterSchema: updatedSchema,
       })
       setToolToView(null)
@@ -395,15 +395,22 @@ function ServerDetailView({ workspaceId, serverId, onBack }: ServerDetailViewPro
           <Tooltip.Root>
             <Tooltip.Trigger asChild>
               <div className='inline-flex'>
-                <Chip disabled>Add Workflows</Chip>
+                <Chip leftIcon={Plus} variant='primary' disabled>
+                  Add Workflows
+                </Chip>
               </div>
             </Tooltip.Trigger>
             <Tooltip.Content>
               All deployed workflows have been added to this server.
             </Tooltip.Content>
           </Tooltip.Root>
         ) : (
-          <Chip onClick={() => setShowAddWorkflow(true)} disabled={!canAddWorkflow}>
+          <Chip
+            leftIcon={Plus}
+            variant='primary'
+            onClick={() => setShowAddWorkflow(true)}
+            disabled={!canAddWorkflow}
+          >
             Add Workflows
           </Chip>
         )}
@@ -430,34 +437,9 @@ function ServerDetailView({ workspaceId, serverId, onBack }: ServerDetailViewPro
               <div className='min-h-[300px] pt-4'>
                 {activeServerTab === 'workflows' && (
                   <div className='flex flex-col gap-4.5'>
-                    <div className='flex items-center justify-between'>
-                      <span className='font-medium text-[var(--text-primary)] text-sm'>
-                        Workflows
-                      </span>
-                      {showAddDisabledTooltip ? (
-                        <Tooltip.Root>
-                          <Tooltip.Trigger asChild>
-                            <div className='inline-flex'>
-                              <Chip leftIcon={Plus} variant='primary' disabled>
-                                Add Workflow
-                              </Chip>
-                            </div>
-                          </Tooltip.Trigger>
-                          <Tooltip.Content>
-                            All deployed workflows have been added to this server.
-                          </Tooltip.Content>
-                        </Tooltip.Root>
-                      ) : (
-                        <Chip
-                          leftIcon={Plus}
-                          variant='primary'
-                          onClick={() => setShowAddWorkflow(true)}
-                          disabled={!canAddWorkflow}
-                        >
-                          Add Workflow
-                        </Chip>
-                      )}
-                    </div>
+                    <span className='font-medium text-[var(--text-primary)] text-sm'>
+                      Workflows
+                    </span>
 
                     {tools.length === 0 ? (
                       <p className='text-[var(--text-muted)] text-sm'>
@@ -915,6 +897,7 @@ function ServerDetailView({ workspaceId, serverId, onBack }: ServerDetailViewPro
 export function WorkflowMcpServers() {
   const params = useParams()
   const workspaceId = params.workspaceId as string
+  const searchParams = useSearchParams()
 
   const { data: servers = [], isLoading, error } = useWorkflowMcpServers(workspaceId)
   const { data: deployedWorkflows = [], isLoading: isLoadingWorkflows } =
@@ -923,7 +906,9 @@ export function WorkflowMcpServers() {
 
   const [searchTerm, setSearchTerm] = useState('')
   const [showAddModal, setShowAddModal] = useState(false)
-  const [selectedServerId, setSelectedServerId] = useState<string | null>(null)
+  const [selectedServerId, setSelectedServerId] = useState<string | null>(() =>
+    searchParams.get('mcpServerId')
+  )
   const [serverToDelete, setServerToDelete] = useState<WorkflowMcpServer | null>(null)
   const [deletingServers, setDeletingServers] = useState<Set<string>>(() => new Set())