mastra-ai/mastra · error · Error

Agent '${agent.name}' (key: '${agentKey}') must have a non-e

Error message

Agent '${agent.name}' (key: '${agentKey}') must have a non-empty description to be used in an MCPServer.

What it means

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.

Source

Thrown at packages/mcp/src/server/server.ts:1495

    agentsConfig?: Record<string, Agent>,
    definedConvertedTools?: Record<string, InternalCoreTool>,
  ): Record<string, InternalCoreTool> {
    const agentTools: Record<string, InternalCoreTool> = {};
    if (!agentsConfig) {
      return agentTools;
    }

    for (const agentKey in agentsConfig) {
      const agent = agentsConfig[agentKey];
      if (!agent || !('generate' in agent)) {
        this.logger.warn('Invalid agent instance, skipping', { agentKey });
        continue;
      }

      const agentDescription = agent.getDescription();

      if (!agentDescription) {
        throw new Error(
          `Agent '${agent.name}' (key: '${agentKey}') must have a non-empty description to be used in an MCPServer.`,
        );
      }

      const agentToolName = `ask_${agentKey}`;
      if (definedConvertedTools?.[agentToolName] || agentTools[agentToolName]) {
        this.logger.warn('Duplicate tool name, skipping agent', { tool: agentToolName, agentKey });
        continue;
      }

      const agentToolDefinition = createTool({
        id: agentToolName,
        description: `Ask agent '${agent.name}' a question. Agent description: ${agentDescription}`,
        inputSchema: {
          type: 'object' as const,
          properties: {
            message: { type: 'string', description: 'The question or input for the agent.' },
          },

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Add a non-empty description to the Agent via new Agent({ ..., description: '...' }) or setDescription()
  2. Remove that agent from the MCPServer's agents map if it should not be exposed as a tool
  3. Add a startup assertion/test that every agent passed to MCPServer has a description

Example fix

// before
new MCPServer({
  agents: { weatherAgent: new Agent({ name: 'weather', instructions: '...' }) },
});
// after
new MCPServer({
  agents: {
    weatherAgent: new Agent({
      name: 'weather',
      instructions: '...',
      description: 'Answers weather questions for any city.',
    }),
  },
});
Defensive patterns

Strategy: validation

Validate before calling

for (const [key, agent] of Object.entries(agentsMap)) {
  if (!agent.getDescription()) {
    throw new Error(`Agent '${key}' has no description; add one before registering on an MCPServer.`);
  }
}

Type guard

function hasDescription(agent) {
  return typeof agent.getDescription === 'function' && typeof agent.getDescription() === 'string' && agent.getDescription().length > 0;
}

Try / catch

try {
  const server = new MCPServer({ name, version, agents });
  await server.start();
} catch (e) {
  if (e instanceof Error && e.message.includes('non-empty description')) {
    // log which agent (parse key from message) and fix its definition
  } else throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/597d9410468d2945. Report an issue: GitHub.