diagnose_issue

Instructions

Implementation Reference

• src/tools/diagnose-issue.ts:335-384 (handler)

  Main handler function for the diagnose_issue tool. Takes symptom, feature, errorMessage, and platform args. Searches knownIssues for matching symptoms and returns diagnosis results or generic troubleshooting advice.

  export async function diagnoseIssue(
    args: Record<string, unknown>
  ): Promise<{ content: Array<{ type: "text"; text: string }> }> {
    const { symptom, feature, errorMessage, platform } = args as unknown as DiagnoseIssueArgs;
  
    if (!symptom) {
      return {
        content: [
          {
            type: "text",
            text: "Please describe the issue you're experiencing in the `symptom` parameter.",
          },
        ],
      };
    }
  
    // Find matching issues
    const searchTerms = symptom.toLowerCase();
    const matchedIssues = knownIssues.filter((issue) =>
      issue.symptoms.some((s) => searchTerms.includes(s.toLowerCase()))
    );
  
    // Also filter by feature if provided
    const featureIssues = feature
      ? matchedIssues.filter(
          (issue) =>
            issue.title.toLowerCase().includes(feature) ||
            issue.symptoms.some((s) => s.includes(feature))
        )
      : matchedIssues;
  
    const relevantIssues = featureIssues.length > 0 ? featureIssues : matchedIssues;
  
    if (relevantIssues.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: buildGenericDiagnosis(symptom, feature, errorMessage, platform),
          },
        ],
      };
    }
  
    const output = buildDiagnosisOutput(relevantIssues, platform);
  
    return {
      content: [{ type: "text", text: output }],
    };
  }

• src/tools/diagnose-issue.ts:3-8 (schema)

  TypeScript interface defining the input arguments for the diagnose_issue tool: symptom (required), feature, errorMessage, and platform (optional).

  interface DiagnoseIssueArgs {
    symptom: string;
    feature?: SdkFeature;
    errorMessage?: string;
    platform?: "ios" | "android" | "web" | "unknown";
  }

• src/tools/diagnose-issue.ts:10-16 (schema)

  TypeScript interface defining the structure of known issues: title, symptoms list, causes list, solutions list, and optional code example.

  interface Issue {
    title: string;
    symptoms: string[];
    causes: string[];
    solutions: string[];
    codeExample?: string;
  }

• src/tools/index.ts:150-178 (registration)

  Registration of the diagnose_issue tool in the tools array with its name, description, and input schema (JSON Schema format).

  {
    name: "diagnose_issue",
    description:
      "Diagnose common @appolabs/appo SDK integration issues. Provides diagnosis with solutions and code fixes.",
    inputSchema: {
      type: "object",
      properties: {
        symptom: {
          type: "string",
          description: "Description of the issue or error",
        },
        feature: {
          type: "string",
          enum: SDK_FEATURES,
          description: "SDK feature related to the issue (if known)",
        },
        errorMessage: {
          type: "string",
          description: "Exact error message (if available)",
        },
        platform: {
          type: "string",
          enum: ["ios", "android", "web", "unknown"],
          description: "Platform where issue occurs",
        },
      },
      required: ["symptom"],
    },
  },

• src/tools/index.ts:196-197 (registration)

  Route in handleToolCall switch statement that dispatches to the diagnoseIssue handler when the tool name matches 'diagnose_issue'.

  case "diagnose_issue":
    return diagnoseIssue(args);