clarify_intent

Instructions

Implementation Reference

• src/index.ts:756-823 (handler)

  The primary handler function that implements the execution logic for the 'clarify_intent' tool. It parses input arguments, builds a user-facing message and dynamic elicitation schema (including options if provided), sends an elicitation request to the user, and returns the response or error.

  private async handleClarifyIntent(args: Record<string, unknown>) {
    const request_summary =
      typeof args.request_summary === "string"
        ? args.request_summary
        : "Unknown request";
    const ambiguity =
      typeof args.ambiguity === "string" ? args.ambiguity : "Unknown ambiguity";
    const options = Array.isArray(args.options) ? args.options : undefined;
  
    let message = `I need to clarify your intent:\n\n**My understanding**: ${request_summary}\n\n**What's unclear**: ${ambiguity}`;
  
    const schema: ElicitationSchema = {
      type: "object",
      properties: {},
      required: ["clarification"],
    };
  
    // Add selected_option FIRST if options exist (for better UX - selection before free text)
    if (options && options.length > 0) {
      message += `\n\n**Options**:\n${options.map((opt: unknown, i: number) => `${i + 1}. ${String(opt)}`).join("\n")}`;
      schema.properties.selected_option = {
        type: "string",
        title: "Select Option",
        description: "Which option best matches your intent?",
        enum: options.map((opt) => String(opt)),
      };
    }
  
    // Add clarification field AFTER options (better UX - free text input comes after selection)
    schema.properties.clarification = {
      type: "string",
      title: "Additional clarification",
      description: "Please provide any additional details or explanation",
    };
  
    const elicitationParams: ElicitationParams = {
      message,
      requestedSchema: schema,
    };
  
    try {
      const response = await this.sendElicitationRequest(elicitationParams);
  
      if (response.action === "accept") {
        return {
          content: [
            {
              type: "text",
              text: `User clarification:\n${JSON.stringify(response.content, null, 2)}`,
            },
          ],
        };
      } else {
        return {
          content: [
            {
              type: "text",
              text: `User ${response.action}ed the clarification request.`,
            },
          ],
        };
      }
    } catch (error) {
      return this.createErrorResponse(
        `Clarification request failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/index.ts:288-317 (registration)

  The factory function that creates and returns the Tool object for 'clarify_intent', including its name, description, and inputSchema definition.

  private createClarifyIntentTool(): Tool {
    return {
      name: "clarify_intent",
      description:
        "Ask user to clarify their intent when the request is ambiguous or could be interpreted multiple ways",
      inputSchema: {
        type: "object",
        properties: {
          request_summary: {
            type: "string",
            description:
              "Summary of what the AI understood from the user's request",
          },
          ambiguity: {
            type: "string",
            description: "Description of what is unclear or ambiguous",
          },
          options: {
            type: "array",
            items: {
              type: "string",
            },
            description:
              "Possible interpretations or options for the user to choose from",
          },
        },
        required: ["request_summary", "ambiguity"],
      },
    };
  }

• src/index.ts:293-315 (schema)

  The input schema defining the expected parameters for the clarify_intent tool: required request_summary and ambiguity, optional options array.

  inputSchema: {
    type: "object",
    properties: {
      request_summary: {
        type: "string",
        description:
          "Summary of what the AI understood from the user's request",
      },
      ambiguity: {
        type: "string",
        description: "Description of what is unclear or ambiguous",
      },
      options: {
        type: "array",
        items: {
          type: "string",
        },
        description:
          "Possible interpretations or options for the user to choose from",
      },
    },
    required: ["request_summary", "ambiguity"],
  },

• src/index.ts:522-523 (registration)

  The dispatch switch case in executeToolCall that routes calls to the 'clarify_intent' tool to its handler function.

  case "clarify_intent":
    return await this.handleClarifyIntent(args);

• src/index.ts:231-242 (registration)

  The getToolDefinitions method that registers clarify_intent by calling createClarifyIntentTool() and including it in the list of available tools.

  private getToolDefinitions(): Tool[] {
    return [
      this.createAskYesNoTool(),
      this.createConfirmActionTool(),
      this.createClarifyIntentTool(),
      this.createVerifyUnderstandingTool(),
      this.createCollectRatingTool(),
      this.createElicitCustomTool(),
      this.createSearchLogsTool(),
      this.createAnalyzeLogsTool(),
    ];
  }