get_subject_phenotypes

Instructions

Implementation Reference

• src/handlers/reference-handlers.ts:756-829 (handler)

  The main handler function getSubjects() that implements the tool logic: fetches subject phenotype data from GTEx API and formats detailed demographics output based on number of subjects.

  async getSubjects(args: any) {
    const result = await this.apiClient.getSubjects(
      args.datasetId || 'gtex_v8',
      args.sex,
      args.ageBrackets,
      args.hardyScale,
      args.subjectIds
    );
  
    if (result.error) {
      return {
        content: [{
          type: "text",
          text: `Error retrieving subject information: ${result.error}`
        }],
        isError: true
      };
    }
  
    const subjects = result.data || [];
    if (subjects.length === 0) {
      return {
        content: [{
          type: "text",
          text: "No subjects found matching the specified criteria."
        }]
      };
    }
  
    let output = `**Subject Information (${subjects.length} subjects)**\n`;
    output += `Dataset: ${subjects[0]?.datasetId}\n\n`;
  
    if (subjects.length <= 50) {
      // Detailed view for smaller result sets
      subjects.forEach((subject, index) => {
        output += `${(index + 1).toString().padStart(3)}. **${subject.subjectId}**\n`;
        output += `     • Age: ${subject.ageBracket}\n`;
        output += `     • Sex: ${subject.sex}\n`;
        output += `     • Hardy Scale: ${subject.hardyScale}\n`;
      });
    } else {
      // Summary view for large result sets
      const sexGroups = this.groupBy(subjects, 'sex');
      const ageGroups = this.groupBy(subjects, 'ageBracket');
      const hardyGroups = this.groupBy(subjects, 'hardyScale');
  
      output += `**Demographics Summary:**\n`;
      output += `• **By Sex:**\n`;
      Object.entries(sexGroups).forEach(([sex, count]) => {
        output += `  - ${sex}: ${count} subjects (${((count / subjects.length) * 100).toFixed(1)}%)\n`;
      });
  
      output += `• **By Age Bracket:**\n`;
      Object.entries(ageGroups).forEach(([age, count]) => {
        output += `  - ${age} years: ${count} subjects (${((count / subjects.length) * 100).toFixed(1)}%)\n`;
      });
  
      output += `• **By Hardy Scale:**\n`;
      Object.entries(hardyGroups).forEach(([hardy, count]) => {
        output += `  - ${hardy}: ${count} subjects (${((count / subjects.length) * 100).toFixed(1)}%)\n`;
      });
    }
  
    if (result.paging_info && result.paging_info.totalNumberOfItems > subjects.length) {
      output += `\n**Note:** Showing ${subjects.length} of ${result.paging_info.totalNumberOfItems} total results.\n`;
    }
  
    return {
      content: [{
        type: "text",
        text: output
      }]
    };
  }

• src/index.ts:745-750 (registration)

  Tool registration in the main dispatch handler: maps 'get_subject_phenotypes' calls to referenceHandlers.getSubjects().

  if (name === "get_subject_phenotypes") {
    return await referenceHandlers.getSubjects({
      subjectIds: args?.subjectId ? [args.subjectId] : undefined,
      datasetId: args?.datasetId
    });
  }

• src/index.ts:479-496 (schema)

  Input schema definition for the get_subject_phenotypes tool, including parameters for subjectId (optional) and datasetId (default gtex_v8).

  {
    name: "get_subject_phenotypes",
    description: "Get subject phenotype data and demographics",
    inputSchema: {
      type: "object",
      properties: {
        subjectId: {
          type: "string",
          description: "GTEx subject ID (optional, for specific subject)"
        },
        datasetId: {
          type: "string",
          description: "GTEx dataset ID (default: gtex_v8)", 
          default: "gtex_v8"
        }
      }
    }
  },