{"record":{"id":"597d9410468d2945","repo":"mastra-ai/mastra","slug":"agent-agent-name-key-agentkey-must-ha","errorCode":null,"errorMessage":"Agent '${agent.name}' (key: '${agentKey}') must have a non-empty description to be used in an MCPServer.","messagePattern":"Agent '(.+?)' \\(key: '(.+?)'\\) must have a non-empty description to be used in an MCPServer\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/server/server.ts","lineNumber":1495,"sourceCode":"    agentsConfig?: Record<string, Agent>,\n    definedConvertedTools?: Record<string, InternalCoreTool>,\n  ): Record<string, InternalCoreTool> {\n    const agentTools: Record<string, InternalCoreTool> = {};\n    if (!agentsConfig) {\n      return agentTools;\n    }\n\n    for (const agentKey in agentsConfig) {\n      const agent = agentsConfig[agentKey];\n      if (!agent || !('generate' in agent)) {\n        this.logger.warn('Invalid agent instance, skipping', { agentKey });\n        continue;\n      }\n\n      const agentDescription = agent.getDescription();\n\n      if (!agentDescription) {\n        throw new Error(\n          `Agent '${agent.name}' (key: '${agentKey}') must have a non-empty description to be used in an MCPServer.`,\n        );\n      }\n\n      const agentToolName = `ask_${agentKey}`;\n      if (definedConvertedTools?.[agentToolName] || agentTools[agentToolName]) {\n        this.logger.warn('Duplicate tool name, skipping agent', { tool: agentToolName, agentKey });\n        continue;\n      }\n\n      const agentToolDefinition = createTool({\n        id: agentToolName,\n        description: `Ask agent '${agent.name}' a question. Agent description: ${agentDescription}`,\n        inputSchema: {\n          type: 'object' as const,\n          properties: {\n            message: { type: 'string', description: 'The question or input for the agent.' },\n          },","sourceCodeStart":1477,"sourceCodeEnd":1513,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/server/server.ts#L1477-L1513","documentation":"When an MCPServer is constructed with agents, each agent is exposed as an MCP tool named `ask_<agentKey>`. MCP tools require descriptions, so the server demands every included agent have a non-empty description (via agent.getDescription()). This Error is thrown during server setup when an agent's description is empty or undefined.","triggerScenarios":"new MCPServer({ agents: { myAgent: agent } }) where the Agent was created without a description (or with an empty string), and the server starts and iterates agents to build the ask_* tools.","commonSituations":"Agent added to an MCPServer after being defined for direct use only (descriptions feel optional there); a refactor or migration dropped the description field; description conditionally computed and evaluating to '' at startup; copy-pasted agent config missing the description.","solutions":["Add a non-empty description to the Agent via new Agent({ ..., description: '...' }) or setDescription()","Remove that agent from the MCPServer's agents map if it should not be exposed as a tool","Add a startup assertion/test that every agent passed to MCPServer has a description"],"exampleFix":"// before\nnew MCPServer({\n  agents: { weatherAgent: new Agent({ name: 'weather', instructions: '...' }) },\n});\n// after\nnew MCPServer({\n  agents: {\n    weatherAgent: new Agent({\n      name: 'weather',\n      instructions: '...',\n      description: 'Answers weather questions for any city.',\n    }),\n  },\n});","handlingStrategy":"validation","validationCode":"for (const [key, agent] of Object.entries(agentsMap)) {\n  if (!agent.getDescription()) {\n    throw new Error(`Agent '${key}' has no description; add one before registering on an MCPServer.`);\n  }\n}","typeGuard":"function hasDescription(agent) {\n  return typeof agent.getDescription === 'function' && typeof agent.getDescription() === 'string' && agent.getDescription().length > 0;\n}","tryCatchPattern":"try {\n  const server = new MCPServer({ name, version, agents });\n  await server.start();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('non-empty description')) {\n    // log which agent (parse key from message) and fix its definition\n  } else throw e;\n}","preventionTips":["Make descriptions mandatory in your Agent factory functions","Add a unit test asserting every agent passed to MCPServer has a description","Only register agents intended for external MCP exposure"],"tags":["mcp","agent","configuration","missing-description"],"backgroundTag":"missing-required-config","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}