Skip to main content
Glama
tejpalvirk

Qualitative Researcher MCP Server

by tejpalvirk

Qualitative Researcher MCP Server

An MCP server implementation that provides tools for managing qualitative research knowledge graphs, enabling structured representation of research projects, participants, interviews, observations, codes, themes, and findings. This server helps qualitative researchers organize their data, track their analysis process, develop themes, and generate insights from rich textual data.

Features

  • Persistent Research Context: Maintain a structured knowledge graph of research entities and relationships across multiple analysis sessions

  • Study Session Management: Track research analysis sessions with unique IDs and record progress over time

  • Thematic Analysis: Organize and track emergent themes across data sources

  • Coding Framework: Manage hierarchical coding structures and track code applications

  • Participant Management: Track participant data, demographics, and contributions

  • Data Source Organization: Organize interviews, observations, and documents

  • Research Question Tracking: Link data to specific research questions

  • Memo Writing: Document analytical insights throughout the research process

  • Chronological Data Analysis: Explore data in temporal sequence

  • Code Co-occurrence Analysis: Identify relationships between different codes

  • Methodology Documentation: Track methodological decisions and approaches

Related MCP server: Quantitative Researcher MCP Server

Entities

The Qualitative Researcher MCP Server recognizes the following entity types:

  • project: Overall research study

  • participant: Research subjects

  • interview: Formal conversation with participants

  • observation: Field notes from observational research

  • document: External materials being analyzed

  • code: Labels applied to data segments

  • codeGroup: Categories or families of related codes

  • memo: Researcher's analytical notes

  • theme: Emergent patterns across data

  • quote: Notable excerpts from data sources

  • literature: Academic sources

  • researchQuestion: Formal questions guiding the study

  • finding: Results or conclusions

  • status: Entity status values (active, completed, pending, abandoned)

  • priority: Priority level values (high, low)

Relationships

Entities can be connected through the following relationship types:

  • participated_in: Links participants to interviews/observations

  • codes: Shows which codes apply to which data

  • contains: Hierarchical relationship (e.g., codegroup contains codes)

  • supports: Data supporting a theme or finding

  • contradicts: Data contradicting a theme or finding

  • answers: Data addressing a research question

  • cites: References to literature

  • followed_by: Temporal sequence

  • related_to: General connection

  • reflects_on: Memo reflecting on data/code/theme

  • compares: Comparative relationship

  • conducted_by: Person who conducted data collection

  • transcribed_by: Person who transcribed data

  • part_of: Entity is part of another entity

  • derived_from: Entity is derived from another entity

  • collected_on: Data collection date

  • analyzes: Analysis relationship

  • triangulates_with: Triangulation between data sources

  • has_status: Links entities to their current status (active, completed, pending, abandoned)

  • has_priority: Links entities to their priority level (high, low)

  • precedes: Indicates that one analysis activity comes before another in a sequence

Available Tools

The Qualitative Researcher MCP Server provides these tools for interacting with research knowledge:

startsession

Starts a new qualitative research session, generating a unique session ID and displaying current research projects, recent data collection, emergent themes, and previous sessions. Shows status information via has_status relations, priority levels via has_priority relations, and identifies research activities ready to be worked on next based on sequential process relationships.

loadcontext

Loads detailed context for a specific entity (project, participant, interview, etc.), displaying relevant information based on entity type. Includes status information, priority levels, and sequential process relationships.

endsession

Records the results of a research session through a structured, multi-stage process:

  1. summary: Records session summary, duration, and project focus

  2. interviewData: Documents new interview data processed during the session

  3. memos: Records analytical memos created during the session

  4. codingActivity: Tracks new and revised codes applied to data

  5. themes: Documents emergent or developed themes from analysis

  6. statusUpdates: Records changes to entity status values

  7. projectStatus: Updates overall project status, priority assignments, and sequential relationships

  8. assembly: Final assembly of all session data

buildcontext

Creates new entities, relations, or observations in the knowledge graph:

  • entities: Add new research entities (projects, participants, interviews, status, priority, etc.)

  • relations: Create relationships between entities (including has_status, has_priority, precedes)

  • observations: Add observations to existing entities

deletecontext

Removes entities, relations, or observations from the knowledge graph:

  • entities: Remove research entities

  • relations: Remove relationships between entities (including status, priority, and sequential relations)

  • observations: Remove specific observations from entities

advancedcontext

Retrieves information from the knowledge graph:

  • graph: Get the entire knowledge graph

  • search: Search for nodes based on query criteria

  • nodes: Get specific nodes by name

  • related: Find related entities

  • status: Find entities with a specific status value (active, completed, pending, abandoned)

  • priority: Find entities with a specific priority value (high, low)

  • sequence: Identify sequential relationships for analysis activities

Domain-Specific Functions

The Qualitative Researcher MCP Server includes specialized domain functions for qualitative research:

  • getProjectOverview: Comprehensive view of a project including research questions, methodology, participants, data sources

  • getParticipantProfile: Detailed profile of a participant including demographics, interviews, and quotes

  • getThematicAnalysis: Analysis of themes with supporting codes and data

  • getCodedData: View all data segments tagged with a specific code

  • getResearchQuestionAnalysis: Organize data by research questions with related findings

  • getChronologicalData: View data in temporal sequence

  • getCodeCooccurrence: Analyze where multiple codes appear together

  • getMemosByFocus: Retrieve all memos related to a specific entity

  • getMethodologyDetails: Review methodological approach, sampling, and analysis techniques

  • getRelatedEntities: Find entities related to a specific entity by relationship type

  • getStatusOverview: View all entities with a specific status (active, completed, pending, abandoned)

  • getPriorityItems: Identify high-priority research tasks and activities

  • getAnalysisSequence: Visualize the sequence of analysis activities based on precedes relations

Example Prompts

Starting a Session

Let's start a new qualitative research session for my Health Behavior Study project.

Loading Research Context

Load the context for the Health Behavior Study project so I can see the current state of my analysis.

Recording Session Results

I've just finished analyzing interview data for my Health Behavior Study. I identified two new themes related to social support, coded three new interviews, and wrote memos about emerging patterns in participant responses. I've marked the initial coding phase as complete and set the thematic analysis as high priority. The project is progressing well, and I'm beginning to reach theoretical saturation.

Managing Research Knowledge

Create a new code called "Family Support" that's part of the "Social Support" code group in the Health Behavior Study project. Set its status to active and make it precede the "Social Network Analysis" activity.
Update the status of the "Participant Recruitment" process to "completed" and add an observation that we've reached our target sample size.

Usage

This MCP server enables qualitative researchers to:

  • Maintain Analytical Continuity: Keep track of analysis progress across multiple research sessions

  • Develop Coding Frameworks: Build, refine, and apply coding structures to qualitative data

  • Track Thematic Development: Observe how themes emerge and evolve during analysis

  • Manage Rich Data Sources: Organize and connect interview transcripts, field notes, and documents

  • Support Theoretical Development: Document theoretical insights through the memo writing process

  • Prepare Research Findings: Connect findings to supporting evidence and research questions

  • Enhance Methodological Rigor: Document methodological decisions and analysis process

  • Track Research Progress: Monitor entity status throughout the research lifecycle

  • Prioritize Research Tasks: Identify and focus on high-priority research activities

  • Sequence Analysis Activities: Plan and visualize the logical order of research and analytical steps

Configuration

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

Install from GitHub and run with npx

{
  "mcpServers": {
    "qualitativeresearch": {
      "command": "npx",
      "args": [
        "-y",
        "github:tejpalvirk/qualitativeresearch"
      ]
    }
  }
}

Install globally and run directly

First, install the package globally:

npm install -g github:tejpalvirk/qualitativeresearch

Then configure Claude Desktop:

{
  "mcpServers": {
    "qualitativeresearch": {
      "command": "contextmanager-qualitativeresearch"
    }
  }
}

docker

{
  "mcpServers": {
    "qualitativeresearch": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "mcp/qualitativeresearch"
      ]
    }
  }
}

Building

From Source

# Clone the repository
git clone https://github.com/tejpalvirk/contextmanager.git
cd contextmanager

# Install dependencies
npm install

# Build the server
npm run build

# Run the server
cd qualitativeresearch
node qualitativeresearch_index.js

Docker:

docker build -t mcp/qualitativeresearch -f qualitativeresearch/Dockerfile .

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Environment Variables

The Qualitative Research MCP Server supports the following environment variables to customize where data is stored:

  • MEMORY_FILE_PATH: Path where the knowledge graph data will be stored

    • Can be absolute or relative (relative paths use current working directory)

    • Default: ./qualitativeresearch/memory.json

  • SESSIONS_FILE_PATH: Path where session data will be stored

    • Can be absolute or relative (relative paths use current working directory)

    • Default: ./qualitativeresearch/sessions.json

Example usage:

# Store data in the current directory
MEMORY_FILE_PATH="./qualitative-memory.json" SESSIONS_FILE_PATH="./qualitative-sessions.json" npx github:tejpalvirk/contextmanager-qualitativeresearch

# Store data in a specific location (absolute path)
MEMORY_FILE_PATH="/path/to/data/qualitative-memory.json" npx github:tejpalvirk/contextmanager-qualitativeresearch

# Store data in user's home directory
MEMORY_FILE_PATH="$HOME/contextmanager/qualitative-memory.json" npx github:tejpalvirk/contextmanager-qualitativeresearch

Available Tools

6 tools
advancedcontextA

A sophisticated query tool for exploring, analyzing, and retrieving complex information from the qualitative research knowledge graph.

When to use this tool:

  • Retrieving a comprehensive view of your entire research knowledge structure

  • Searching for specific research entities across your qualitative data corpus

  • Getting detailed information about particular research projects, participants, or analytical elements

  • Exploring relationships between research components (codes, themes, quotes)

  • Analyzing code frequencies and distributions across your data

  • Retrieving interview or observation transcripts for analysis

  • Accessing memo content for reflection on the research process

  • Generating codebooks or analytical frameworks for documentation

  • Finding connections between different aspects of your research

  • Creating research reports or summaries from your data

  • Exploring thematic structures and their evidentiary basis

  • Identifying entities by status to track research progress

  • Filtering tasks by priority to manage research workflow

  • Analyzing sequential relationships between research processes

Key features:

  • Offers specialized operations for querying different aspects of qualitative research data

  • Retrieves complete or filtered views of the research knowledge graph

  • Provides flexible search capabilities across all research entities

  • Supports detailed exploration of specific entities by name

  • Generates specialized views for projects, participants, codes, and themes

  • Retrieves content and metadata for interviews, transcripts, and memos

  • Creates codebooks and thematic frameworks for documentation

  • Identifies related entities to explore connections within your research

  • Returns consistently structured JSON responses for easy processing

  • Facilitates depth and breadth exploration of qualitative data

  • Supports status-based filtering of research entities

  • Enables priority-based task management

  • Provides sequential process analysis capabilities

Parameters explained:

  1. type: The type of query operation to perform

  • Accepts one of the specialized operations: "graph", "search", "nodes", "project", "participant", "codes", "themes", "transcript", "memo", "analysis", "codebook", "related", "status", "priority", "sequence"

  • Determines how the params parameter is interpreted

  1. params: Operation-specific parameters (structure varies by type):

  • For "graph": No parameters needed (retrieves the full research knowledge graph)

  • For "search": Object containing:

    • query: Search string to find entities (supports entity type filters)

  • For "nodes": Object containing:

    • names: Array of entity names to retrieve

  • For "project": Object containing:

    • projectName: Name of the project to retrieve details for

  • For "participant": Object containing:

    • participantName: Name of the participant to retrieve profile for

  • For "codes": Object containing:

    • projectName: (Optional) Project name to filter codes by

  • For "themes": Object containing:

    • projectName: (Optional) Project name to filter themes by

  • For "transcript": Object containing:

    • participantName: Participant associated with the transcript

    • interviewId: (Optional) Specific interview identifier

  • For "memo": Object containing:

    • memoName: Name of the memo to retrieve

  • For "analysis": Object containing:

    • projectName: Project name to retrieve analysis artifacts for

  • For "codebook": Object containing:

    • projectName: Project name to generate codebook for

  • For "related": Object containing:

    • entityName: Name of the entity to find related entities for

  • For "status": Object containing:

    • statusValue: The status value to filter by (e.g., "planning", "data_collection", "analysis")

  • For "priority": Object containing:

    • priorityValue: The priority value to filter by (e.g., "high", "low")

  • For "sequence": Object containing:

    • entityName: Name of the entity to find sequential relationships for

Operation details:

  • graph: Returns the complete research knowledge graph with all entities and relationships

  • search: Performs text-based search across entity names and observations

  • nodes: Retrieves detailed information about specific entities by name

  • project: Returns comprehensive project information including participants, interviews, codes, and findings

  • participant: Generates a participant profile with demographic information and associated data

  • codes: Lists all codes, optionally filtered by project, with reference counts and descriptions

  • themes: Returns all themes, optionally filtered by project, with associated codes and descriptions

  • transcript: Retrieves interview transcript content for specific participant/interview combinations

  • memo: Returns the full content of an analytical memo with metadata

  • analysis: Collects all analysis artifacts (codes, themes, memos) for a specific project

  • codebook: Generates a structured codebook for a project with code definitions and examples

  • related: Identifies all entities directly connected to a specific entity

  • status: Retrieves all entities with a specific status value

  • priority: Retrieves all entities with a specific priority value

  • sequence: Identifies sequential relationships for a specific entity showing preceding and following entities

Status and Priority Information:

  • Status queries return entities organized by their current research stage

  • Priority queries help identify critical research tasks and elements

  • Status values include: planning, data_collection, analysis, writing, complete, scheduled, conducted, transcribed, coded, analyzed, emerging, developing, established, preliminary, draft, final, active, in_progress

  • Priority values include: high, low

Sequential Process Information:

  • Sequence queries identify entities that come before or after in a research process

  • Sequential relationships help visualize the research workflow

  • The sequence operation shows both incoming and outgoing precedes relations

Return information:

  • JSON response with a consistent structure:

    • success: Boolean indicating whether the operation succeeded

    • Additional fields depend on the operation type:

      • graph: Complete knowledge graph

      • results: For search operations

      • nodes: For specific entity retrieval

      • project/participant/etc.: For specialized views

      • status/priority: Lists of entities with specified status/priority values

      • sequence: Preceding and following entities in research processes

  • Error information when operations fail

You should:

  • Start with broad queries ("graph", "search") to explore your research corpus

  • Use specific entity queries ("nodes", "project", "participant") for detailed information

  • Combine search and related queries to discover connections in your data

  • Generate codebooks and project overviews for documentation and reporting

  • Use transcript retrieval to access primary data when needed

  • Explore thematic structures through themes and related entity queries

  • Review memos to track your analytical process over time

  • Filter code and theme queries by project for more focused results

  • Use search with entity type filters to find specific types of research elements

  • Use status queries to identify all entities at a particular research stage

  • Use priority queries to focus on high-priority research tasks

  • Use sequence queries to understand process flows in your research methodology

ParametersJSON Schema
NameRequiredDescriptionDefault
typeYesType of get operation
paramsYesParameters for the get operation, structure varies by type

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure and does so comprehensively. It explains the JSON response structure, error handling, specialized operations, search capabilities, filtering options, and various query behaviors. It provides extensive context about what the tool returns and how it processes different query types, far exceeding minimum requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While well-structured with clear sections, the description is excessively long (over 800 words) with repetitive content. The 'Key features' section largely restates what's in other sections, and some operational details could be more concise. However, the information is front-loaded with purpose and usage guidelines, and each section serves a distinct purpose despite the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex query tool with 2 parameters, no annotations, and no output schema, the description provides exceptional completeness. It covers all query operations, parameter semantics, response formats, error handling, usage patterns, and behavioral characteristics. The description fully compensates for the lack of structured metadata and provides everything needed to understand and use this tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema description coverage, the description adds substantial value beyond the schema. It provides detailed explanations of all 15 possible 'type' values (schema only lists 12), describes the varying 'params' structures for each type with specific examples, explains how parameters are interpreted differently based on type, and provides operational details for each query type that aren't captured in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is a 'sophisticated query tool for exploring, analyzing, and retrieving complex information from the qualitative research knowledge graph.' It specifies the exact resource (qualitative research knowledge graph) and distinguishes from siblings like buildcontext, deletecontext, loadcontext by focusing on querying rather than modifying or managing sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes an explicit 'When to use this tool' section with 14 specific scenarios, plus a 'You should' section with 12 actionable recommendations. It provides clear guidance on when to use different query types (e.g., 'Start with broad queries...', 'Use specific entity queries...') and distinguishes this tool from sibling tools by focusing on query operations rather than context management or session control.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

buildcontextA

A versatile tool for constructing and enhancing the qualitative research knowledge graph by adding new research elements, relationships, and observations.

When to use this tool:

  • Creating new research entities (projects, participants, interviews, observations, codes, themes, memos, etc.)

  • Establishing relationships between research elements (e.g., connecting participants to projects, codes to data segments)

  • Adding observations, notes, or content to existing research entities

  • Building the research corpus incrementally as data collection and analysis progress

  • Organizing and structuring qualitative data within your research framework

  • Documenting emerging themes, codes, and analytical insights during research

  • Creating research questions and linking them to findings

  • Building code hierarchies and thematic frameworks

  • Setting status values for research activities and entities

  • Assigning priorities to research tasks and activities

  • Defining sequential relationships between research processes

Key features:

  • Creates three distinct types of knowledge graph elements: entities, relations, and observations

  • Supports specialized qualitative research entity types (projects, participants, interviews, observations, documents, codes, etc.)

  • Validates entity and relation types against predefined standards for the qualitative research domain

  • Handles batch creation of multiple entities or relations in a single operation

  • Returns confirmation with details of created elements

  • Ensures proper data typing and structure for the qualitative research knowledge graph

  • Enables comprehensive documentation of the research process

  • Supports status and priority assignment through entity-relation model

  • Enables sequential relationships through precedes relation

Parameters explained:

  1. type: The type of creation operation to perform

  • Accepts: "entities", "relations", or "observations"

  • Determines how the data parameter is interpreted

  1. data: The content to add to the knowledge graph (structure varies by type):

  • For "entities": An array of objects, each containing:

    • name: Unique identifier for the entity

    • entityType: One of the valid entity types (project, participant, interview, observation, document, code, codeGroup, memo, theme, quote, literature, researchQuestion, finding, status, priority)

    • observations: Array of strings containing notes or properties about the entity

  • For "relations": An array of objects, each containing:

    • from: Name of the source entity

    • to: Name of the target entity

    • relationType: The type of relationship between entities (e.g., "participated_in", "codes", "has_status", "has_priority")

  • For "observations": Either a single object or an array of objects, each containing:

    • entityName: Name of the entity to add observations to

    • contents: Array of strings with new observations to add

Valid entity types:

  • project: Overall research study

  • participant: Research subjects

  • interview: Formal conversation with participants

  • observation: Field notes from observational research

  • document: External materials being analyzed

  • code: Labels applied to data segments

  • codeGroup: Categories or families of related codes

  • memo: Researcher's analytical notes

  • theme: Emergent patterns across data

  • quote: Notable excerpts from data sources

  • literature: Academic sources

  • researchQuestion: Formal questions guiding the study

  • finding: Results or conclusions

  • status: Entity status values

  • priority: Entity priority values

Valid relation types:

  • participated_in: Links participants to interviews/observations

  • codes: Shows which codes apply to which data

  • contains: Hierarchical relationship

  • supports: Data supporting a theme or finding

  • contradicts: Data contradicting a theme or finding

  • answers: Data addressing a research question

  • cites: References to literature

  • followed_by: Temporal sequence

  • related_to: General connection

  • reflects_on: Memo reflecting on data/code/theme

  • compares: Comparative relationship

  • has_status: Links entity to its status

  • has_priority: Links entity to its priority

  • precedes: Entity comes before another entity in sequence

Status information:

  • Valid status values include: planning, data_collection, analysis, writing, complete, scheduled, conducted, transcribed, coded, analyzed, emerging, developing, established, preliminary, draft, final, active, in_progress

  • Status is assigned through the has_status relation type

Priority information:

  • Valid priority values: high, low

  • Priority is assigned through the has_priority relation type

Return information:

  • JSON response indicating success or failure

  • For successful operations:

    • Success flag set to true

    • Details of created elements in the "created" field (for entities/relations) or "added" field (for observations)

  • For failed operations:

    • Success flag set to false

    • Error message describing the issue

Error handling:

  • Validates entity types against the predefined list for qualitative research

  • Validates relation types against acceptable standards

  • Returns descriptive error messages for invalid inputs

  • Gracefully handles type mismatches and formatting errors

You should:

  • Use consistent naming conventions for entities to facilitate relationships and retrieval

  • Begin by creating projects and participants before more specific research elements

  • Add detailed observations to entities to enhance context and retrievability

  • Create relationships to build a comprehensive network of interconnected research data

  • Use has_status relations to track the progress of research activities

  • Use has_priority relations to indicate important research elements

  • Use the precedes relation to establish sequences in research processes

  • Use observations to document the evolution of codes, themes, and analytical thinking

  • Regularly update entity observations as your understanding evolves

  • Build hierarchical structures using relations (e.g., codes within code groups, themes connecting multiple codes)

  • Document the full research journey by adding memos tied to specific analytical moments

  • Link quotes to codes, themes, and findings to maintain evidential chains

ParametersJSON Schema
NameRequiredDescriptionDefault
typeYesType of creation operation: 'entities', 'relations', or 'observations'
dataYesData for the creation operation, structure varies by type but must be an array

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it's a creation tool (implying mutation), validates entity and relation types, handles batch operations, returns confirmation details, ensures data typing, and includes error handling with descriptive messages. However, it lacks explicit mention of permissions or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (e.g., 'When to use', 'Key features', 'Parameters explained'), but it is overly verbose at approximately 700 words. Some sections, like the detailed lists of valid types, could be condensed without losing clarity, making it less front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (2 parameters, no annotations, no output schema), the description is highly complete. It covers purpose, usage, parameters, valid types, status/priority info, return details, error handling, and best practices, providing all necessary context for an agent to use the tool effectively without an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description adds significant value beyond the schema. It explains the 'type' parameter's three options and details the 'data' parameter's structure for each type, including valid entity types, relation types, status values, and priority values, providing comprehensive semantic context not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: constructing and enhancing a qualitative research knowledge graph by adding new research elements, relationships, and observations. It specifies the verb ('constructing and enhancing') and resource ('qualitative research knowledge graph'), distinguishing it from siblings like deletecontext or loadcontext.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes an explicit 'When to use this tool' section with 12 specific scenarios, such as creating entities, establishing relationships, and adding observations. It also provides a 'You should' section with 12 actionable guidelines, like using consistent naming conventions and beginning with projects and participants, offering clear context and alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

deletecontextA

A precise tool for removing elements from the qualitative research knowledge graph, enabling researchers to maintain data accuracy and refine their analytical framework.

When to use this tool:

  • Removing incorrect or duplicate research entities

  • Deleting erroneous relationships between research elements

  • Clearing outdated observations from research entities

  • Restructuring your research framework as analysis evolves

  • Removing pilot or test data that shouldn't be included in final analysis

  • Cleaning up the knowledge graph during research refinement phases

  • Eliminating deprecated codes, themes, or concepts that no longer fit your analytical framework

  • Removing sensitive information that should not be retained

  • Reorganizing your analytical structure by removing and recreating elements

  • Updating status assignments when research activities change state

  • Modifying priority assignments as research focus shifts

  • Restructuring sequential relationships between research processes

Key features:

  • Provides targeted deletion capabilities for three distinct types of knowledge graph elements: entities, relations, and observations

  • Maintains knowledge graph integrity during deletion operations

  • Supports batch deletion of multiple items in a single operation

  • Returns clear confirmation of deletion results

  • Preserves the overall structure of the research knowledge graph while removing specific elements

  • Performs validation to ensure deletion requests are properly formatted

  • Handles status and priority relation management

  • Supports modification of sequential process relationships

Parameters explained:

  1. type: The type of deletion operation to perform

  • Accepts: "entities", "relations", or "observations"

  • Determines how the data parameter is interpreted

  1. data: The elements to remove from the knowledge graph (structure varies by type):

  • For "entities": Array of entity names to delete

    • Example: ["Participant_A", "Interview_3"]

  • For "relations": Array of relation objects, each containing:

    • from: Name of the source entity

    • to: Name of the target entity

    • relationType: Type of relationship to remove (e.g., "participated_in", "codes", "has_status", "has_priority", "precedes")

  • For "observations": Array of objects, each containing:

    • entityName: Name of the entity to remove observations from

    • indices: Array of numeric indices identifying which observations to remove

Deletion behavior by type:

  • Entities: Removes the specified entities and all their associated relations from the knowledge graph

  • Relations: Removes only the specified relationships, leaving the connected entities intact

  • Observations: Removes specific observations from entities while preserving the entities themselves

Status and Priority Management:

  • When deleting status or priority entities, be aware of the impact on entities that reference them

  • For changing an entity's status or priority, first delete the existing has_status or has_priority relation, then create a new one

  • Consider the research workflow implications when removing status entities or relations

  • Deletion of a status entity will remove all has_status relations pointing to it

Sequential Process Management:

  • Removing precedes relations affects the logical flow of research processes

  • Consider restructuring sequential relationships after deletion to maintain process continuity

  • When reorganizing research phases, update all affected precedes relations

Safety considerations:

  • Entity deletion is permanent and will also remove all relationships involving those entities

  • Consider exporting or backing up your research knowledge graph before performing large-scale deletions

  • For sensitive operations, consider removing specific observations rather than entire entities

  • When removing codes or themes, consider the impact on your analytical framework

  • Status changes should be carefully managed to maintain accurate research progress tracking

  • Changes to sequential relationships may affect dependent research activities

Return information:

  • JSON response indicating success or failure

  • For successful operations:

    • Success flag set to true

    • Confirmation message

  • For failed operations:

    • Success flag set to false

    • Error message describing the issue

You should:

  • Be specific in your deletion requests to avoid unintended data loss

  • Use relations deletion when you want to disconnect entities without removing them

  • For observations, provide the exact indices to ensure only the intended content is removed

  • When restructuring your analysis, consider how deletions will affect related elements

  • Use deletecontext in conjunction with buildcontext to refine and evolve your research framework

  • Regularly review your knowledge graph for elements that may need to be removed or updated

  • Consider the cascading effects of entity deletion on your overall research structure

  • Use observation deletion for minor corrections rather than removing entire entities

  • When updating entity status, delete the old has_status relation before creating a new one

  • Maintain logical consistency when modifying sequential process relationships

ParametersJSON Schema
NameRequiredDescriptionDefault
typeYesType of deletion operation: 'entities', 'relations', or 'observations'
dataYesData for the deletion operation, structure varies by type but must be an array

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and delivers comprehensive behavioral disclosure. It details deletion permanence ('Entity deletion is permanent'), cascading effects, validation processes, batch capabilities, return format, safety considerations, and specific behavioral traits for each deletion type including impact on related elements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While well-structured with clear sections, the description is excessively long with redundant information. Many points are repeated across sections (e.g., safety considerations appear multiple times). Some sentences in the 'You should' section could be consolidated or eliminated without losing essential guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with no annotations and no output schema, the description provides exceptional completeness. It covers purpose, usage scenarios, parameter semantics, behavioral details, safety considerations, return format, and integration with sibling tools. Every aspect needed for safe and effective use is addressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, establishing a baseline of 3. The description adds substantial value with a dedicated 'Parameters explained' section that elaborates on how the 'data' parameter structure varies by type, provides examples, and explains interpretation differences. It also includes 'Deletion behavior by type' that clarifies semantic implications.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'removing elements from the qualitative research knowledge graph' with specific verbs ('removing', 'deleting', 'clearing') and distinguishes it from siblings by focusing on deletion operations. It explicitly mentions using it 'in conjunction with buildcontext' for refinement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive explicit guidance with a dedicated 'When to use this tool' section listing 12 specific scenarios, plus additional 'You should' recommendations. It distinguishes when to use different deletion types and mentions alternatives like using 'observation deletion for minor corrections rather than removing entire entities'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

endsessionA

A multi-stage tool for documenting qualitative research sessions, recording analysis progress, tracking coding activities, and creating a structured record of research evolution.

When to use this tool:

  • Concluding a qualitative research analysis session

  • Documenting interview data collection activities

  • Recording newly created analytical memos

  • Tracking coding activities and code applications

  • Documenting emerging themes and theoretical constructs

  • Updating overall project status and progress

  • Creating a structured record of research activities

  • Establishing a formal conclusion to a focused research period

  • Building a historical record of project development

  • Documenting observations and insights from a research session

  • Updating status values for research activities and entities

  • Assigning or modifying priority levels for research tasks

  • Establishing or modifying sequential relationships between research processes

Key features:

  • Provides a structured, multi-stage workflow for research session documentation

  • Records interview data collection in the knowledge graph

  • Captures newly created analytical memos

  • Tracks coding activities across data sources

  • Documents emerging themes and their connections to codes

  • Updates project status information

  • Maintains session continuity with unique session IDs

  • Supports revision of previous stages when needed

  • Offers a comprehensive assembly stage that consolidates all session information

  • Organizes qualitative research activity into a coherent narrative

  • Manages status progression of research activities

  • Tracks priority assignments for research tasks

  • Documents sequential relationships between research processes

The endsession tool uses a sequential, multi-stage approach with typically 8 stages:

  1. Summary Stage: Records basic session information

  2. Interview Data Stage: Documents new interviews conducted

  3. Memos Stage: Records new analytical memos created

  4. Coding Activity Stage: Documents code applications and coding work

  5. Themes Stage: Records emerging themes and theoretical insights

  6. Status Updates Stage: Records changes to entity status values

  7. Project Status Stage: Updates the overall project status

  8. Assembly Stage: Consolidates all information and finalizes the session record

Parameters explained:

  1. sessionId: Required - Unique identifier for the research session

  • Obtained from the startsession tool

  • Example: "qual_1234567890_abc123"

  1. stage: Required - Current stage of the endsession workflow

  • Accepts: "summary", "interviewData", "memos", "codingActivity", "themes", "statusUpdates", "projectStatus", or "assembly"

  • Each stage has specific data requirements and processing logic

  1. stageNumber: Required - The sequence number of the current stage

  • Starts at 1 and typically progresses through the stages

  • Used to track progress through the session documentation workflow

  1. totalStages: Required - Total number of stages planned for this workflow

  • Typically 8 for the complete workflow

  • Provides context for the progress within the overall process

  1. analysis: Optional - Text analysis or observations for the current stage

  • Descriptive text explaining the work done in this stage

  • Example: "Analyzed interview transcripts and identified recurring patterns"

  1. stageData: Optional - Stage-specific structured data

  • Structure varies by stage type:

    • summary: { summary: "Session summary text", duration: "3 hours", project: "ProjectName" }

    • interviewData: { interviews: [{ participant: "P001", notes: "Interview notes", date: "2023-04-15" }] }

    • memos: { memos: [{ topic: "Emerging patterns", content: "Detailed memo text" }] }

    • codingActivity: { codes: [{ code: "coping_strategy", dataItem: "Interview_P001", note: "Applied to discussion of stress management" }] }

    • themes: { themes: [{ name: "Social Support", codes: ["family_support", "peer_networks"], description: "The role of social connections in coping" }] }

    • statusUpdates: { statusUpdates: [{ entityName: "Interview_P003", newStatus: "transcribed", note: "Completed transcription" }, { entityName: "Code_Resilience", newStatus: "established", note: "Well-supported by data" }] }

    • projectStatus: { projectStatus: "data_analysis", projectObservation: "Making good progress on initial coding", priorityUpdates: [{ entityName: "Transcribe_P004", priority: "high", note: "Critical for thematic development" }], sequenceUpdates: [{ before: "Coding_Phase1", after: "Theme_Development", note: "Ready to move from coding to theme creation" }] }

    • assembly: No stageData needed - automatically assembled from previous stages

  1. nextStageNeeded: Required - Whether additional stages are needed after this one

  • Boolean value (true/false)

  • Set to false on the final stage to complete the session

  1. isRevision: Optional - Whether this is revising a previous stage

  • Boolean value (true/false)

  • Default: false

  1. revisesStage: Optional - If revising, which stage number is being revised

  • Required when isRevision is true

  • Indicates which previous stage is being updated

Status and Priority Management:

  • The statusUpdates stage allows for batch updates to entity status values

  • Valid status values include: planning, data_collection, analysis, writing, complete, scheduled, conducted, transcribed, coded, analyzed, emerging, developing, established, preliminary, draft, final, active, in_progress

  • Priority assignments (high, low) can be modified in the projectStatus stage

  • Status changes are tracked to maintain a history of research progression

  • Priority changes help reallocate focus as research needs evolve

Sequential Process Management:

  • The projectStatus stage allows for defining or modifying sequential relationships

  • The precedes relation is used to establish logical ordering between research activities

  • Sequential updates help maintain a coherent research workflow

  • Process sequences can be visualized through the loadcontext tool

When the endsession workflow completes (assembly stage with nextStageNeeded: false), the tool:

  1. Records the session completion in persistent storage

  2. Creates a formatted summary of all session information

  3. Updates the status, priority, and sequential relationships for relevant entities

  4. Preserves the record of research activities for future reference

Return information:

  • JSON response with the following structure:

    • success: Boolean indicating whether the operation succeeded

    • stageCompleted: The stage that was just completed

    • nextStageNeeded: Whether more stages are required

    • stageResult: The processed result of the current stage

    • endSessionArgs: (Only in assembly stage) Consolidated arguments for the session

    • sessionRecorded: (Final stage only) Whether the session was recorded

    • summaryMessage: (Final stage only) Formatted summary of all recorded information

    • error: (Only on failure) Error message describing the issue

You should:

  • Complete all stages in order for comprehensive session documentation

  • Provide specific details in each stage for accurate research documentation

  • Document interview data with participant identifiers and key notes

  • Create descriptive titles for analytical memos

  • Be specific about which codes were applied to which data items

  • Connect emerging themes to their supporting codes

  • Update status values to reflect progress in research activities

  • Assign appropriate priorities to focus attention on critical tasks

  • Define logical sequences between research processes with precedes relations

  • Include relevant observations for project status updates

  • If making a revision, specify which stage is being revised

  • Only mark nextStageNeeded as false on the final assembly stage

  • Review the final summary message to confirm all session details were recorded properly

  • Use the unique session ID consistently across all stages

ParametersJSON Schema
NameRequiredDescriptionDefault
sessionIdYesThe unique session identifier obtained from startsession
stageYesCurrent stage of analysis: 'summary', 'themes', 'codes', 'memos', 'participantInsights', or 'assembly'
stageNumberYesThe sequence number of the current stage (starts at 1)
totalStagesYesTotal number of stages in the workflow (typically 6 for standard workflow)
analysisNoText analysis or observations for the current stage
stageDataNoStage-specific data structure - format depends on the stage type: - For 'summary' stage: { summary: "Session summary text", duration: "3 hours", project: "Project Name" } - For 'themes' stage: { themes: [{ name: "Theme1", codes: ["code1", "code2"], description: "Theme description" }] } - For 'codes' stage: { codes: [{ name: "Code1", description: "Code meaning", quotes: ["Quote text"] }] } - For 'memos' stage: { memos: [{ title: "Memo title", content: "Detailed memo text", tags: ["tag1", "tag2"] }] } - For 'participantInsights' stage: { insights: [{ participant: "P1", observation: "Key insight about participant" }] } - For 'assembly' stage: no stageData needed - automatic assembly of previous stages
nextStageNeededYesWhether additional stages are needed after this one (false for final stage)
isRevisionNoWhether this is revising a previous stage
revisesStageNoIf revising, which stage number is being revised

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's multi-stage sequential workflow, revision capabilities, status/priority management, and what happens upon completion (e.g., records in persistent storage, creates formatted summary). It details valid status values and priority levels. However, it lacks explicit mention of error conditions, rate limits, or authentication requirements, though these may be inferred from context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, usage, features, stages, parameters, management, completion, returns, instructions). However, it is excessively long (over 800 words) with repetitive elements (e.g., 'Key features' and 'The endsession tool uses...' both list stages). Some details, like the 13-item usage list, could be more concise. While informative, it risks overwhelming the reader with verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's high complexity (9 parameters, nested objects, multi-stage workflow) and no annotations or output schema, the description is exceptionally complete. It covers purpose, usage, behavioral traits, parameter semantics, return structure, and practical instructions. The detailed explanation of stages, status values, and completion outcomes provides all necessary context for an agent to invoke the tool correctly, fully compensating for the lack of structured metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema description coverage, the description adds significant value beyond the schema. It provides a detailed 'Parameters explained' section with examples for each parameter, clarifies stage-specific data structures with concrete examples (e.g., interviewData structure), explains the purpose of each stage, and notes dependencies like sessionId from startsession. This compensates for the schema's generic descriptions and enhances understanding of complex nested objects.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'documenting qualitative research sessions, recording analysis progress, tracking coding activities, and creating a structured record of research evolution.' It specifies a multi-stage workflow with 8 distinct stages, distinguishing it from sibling tools like startsession (which presumably initiates sessions) and loadcontext (which visualizes sequences). The verb+resource combination is explicit and comprehensive.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool with a dedicated 'When to use this tool' section listing 13 specific scenarios (e.g., 'Concluding a qualitative research analysis session,' 'Documenting interview data collection activities'). It implicitly distinguishes from alternatives by focusing on session conclusion rather than initiation (startsession) or context management (loadcontext, buildcontext). The guidance is thorough and context-specific.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

loadcontextA

A sophisticated tool for retrieving rich, contextual information about qualitative research entities, providing structured insights tailored to different research components.

When to use this tool:

  • Retrieving detailed information about research projects, participants, interviews, and analytical elements

  • Exploring thematic analyses and research findings

  • Reviewing participant profiles and interview transcripts

  • Examining code definitions and their connections to data

  • Analyzing emerging themes and their supporting evidence

  • Investigating research questions and related findings

  • Reviewing analytical memos and their connections to data

  • Preparing for coding sessions by establishing contextual understanding

  • Exploring relationships between codes, themes, and concepts

  • Getting a comprehensive overview of project progress and insights

  • Tracking research activities by their current status

  • Managing tasks based on their assigned priorities

  • Understanding sequential relationships between research processes

Key features:

  • Provides richly formatted, context-aware information about research entities

  • Adapts output format based on entity type (project, participant, interview, code, theme, memo, researchQuestion)

  • Presents both direct entity information and related research elements

  • Shows research design, methodology, and analysis progression

  • Tracks entity views within the current research session

  • Formats information in a structured, readable markdown format

  • Highlights relationships between research elements

  • Presents supporting quotes and evidence for themes and codes

  • Shows co-occurrence patterns between codes where available

  • Includes status information for tracking research progress

  • Displays priority assignments for critical research elements

  • Visualizes sequential relationships between research processes

Parameters explained:

  1. entityName: Required - The name of the entity to retrieve context for

  • Example: "Health Behavior Study", "Participant_P001", "Interview_20230315"

  1. entityType: Optional - The type of entity being retrieved

  • Default: "project"

  • Helps the system format the output appropriately

  • Common types include: "project", "participant", "interview", "code", "theme", "memo", "researchQuestion", "status", "priority"

  1. sessionId: Optional - The current session identifier

  • Typically provided by startsession

  • Used for tracking entity views within the session

Each entity type returns specialized context information:

  • Project: Shows project status, description, research design, research questions, data collection stats, recent interviews, analysis progress (themes), and findings

  • Participant: Displays demographic information, interview history, observation records, notable quotes, and research memos

  • Interview: Shows project affiliation, participant, date, transcript content, applied codes, and notable quotes

  • Code: Displays definition, status, creation date, code group affiliations, supporting quotes, sources, associated themes, and code co-occurrence data

  • Theme: Shows description, status, creation date, project affiliation, supporting codes, example quotes, and analytical memos

  • Memo: Displays topic, date, project affiliation, content, and related entities

  • Research Question: Shows the question text, project affiliation, related findings, themes, and supporting quotes

  • Status: Shows all entities assigned this status value, organized by entity type

  • Priority: Shows all entities assigned this priority value, organized by entity type

  • Other Entity Types: Shows observations and relationship information for other entity types

Status and Priority Information:

  • All entity displays include status information when available via has_status relations

  • Priority assignments are shown for tasks and other prioritized elements

  • Valid status values include: planning, data_collection, analysis, writing, complete, scheduled, conducted, transcribed, coded, analyzed, emerging, developing, established, preliminary, draft, final, active, in_progress

  • Valid priority values include: high, low

Sequential Process Relationships:

  • Entity displays show preceding and following entities through precedes relations

  • Process sequences are visualized to show workflow between research activities

  • Research phases and activities display their position in the overall research process

Return information:

  • Formatted markdown text with hierarchical structure

  • Sections adapted to the specific entity type

  • Related entities shown with their descriptions and connections

  • Status and priority information prominently displayed

  • Sequential relationships clearly indicated

  • Error messages if the entity doesn't exist or can't be retrieved

You should:

  • Specify the exact entity name for accurate retrieval

  • Provide the entity type when possible for optimally formatted results

  • Start with project entities to get a high-level overview of research

  • Use participant context to understand individual perspectives

  • Examine interview context to see coding applied to raw data

  • Review code context to understand analytical categories

  • Explore theme context to see patterns and theoretical constructs

  • Use research question context to track progress toward answering key inquiries

  • Examine memo context to review analytical insights

  • Check status entities to see all research elements at the same stage

  • Review priority entities to identify critical research tasks

  • Explore sequential relationships to understand research process flow

  • After retrieving context, follow up on specific entities of interest

  • Use in conjunction with startsession to maintain session tracking

  • Remember that this tool only retrieves existing information; use buildcontext to add new entities

ParametersJSON Schema
NameRequiredDescriptionDefault
entityNameYes
entityTypeNo
sessionIdNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does an excellent job disclosing behavioral traits. It explains the tool adapts output format based on entity type, tracks entity views within sessions, returns formatted markdown, shows relationships between elements, includes status/priority information, and visualizes sequential processes. It also clarifies error behavior when entities don't exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While well-structured with clear sections, the description is excessively long (over 800 words) with repetitive information. Many sentences in the 'Key features' and 'You should' sections could be consolidated. The front-loaded purpose statement is good, but the description could be significantly more concise without losing essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations, no output schema, and 0% schema coverage, the description provides comprehensive context. It details what information each entity type returns, explains status/priority systems, describes sequential relationships, and specifies the return format. The main gap is not explicitly stating this is a read-only operation, though it's implied by 'only retrieves existing information'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and 3 parameters, the description fully compensates by providing detailed parameter explanations. It clearly explains entityName (required, with examples), entityType (optional, default value, common types), and sessionId (optional, purpose, typical source). The description adds substantial meaning beyond what the bare schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'retrieving rich, contextual information about qualitative research entities' and distinguishes it from sibling tools by specifying it only retrieves existing information while 'buildcontext' adds new entities. The verb 'retrieving' is specific and the resource 'qualitative research entities' is well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive explicit guidance on when to use this tool, including a dedicated 'When to use this tool' section with 13 specific scenarios, plus a 'You should' section with 15 actionable recommendations. It clearly distinguishes from alternatives by stating 'use buildcontext to add new entities' and mentions using 'in conjunction with startsession'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

startsessionA

A comprehensive tool for initializing a new qualitative research session, providing structured information about ongoing research projects, participants, analytical elements, and recent research activities.

When to use this tool:

  • Beginning a new research analysis session

  • Getting oriented to your current research state across multiple projects

  • Planning which research elements to focus on in the current session

  • Reviewing recent research activities and progress

  • Identifying active research projects and their status

  • Exploring available participants for analysis

  • Reviewing your most frequently used codes

  • Accessing recent analytical memos

  • Establishing research context before diving into specific analysis tasks

  • Re-engaging with your research after time away

  • Prioritizing high-priority research tasks

  • Tracking the status of various research activities

  • Understanding sequential research processes

Key features:

  • Generates a unique session identifier for tracking research activities

  • Retrieves and displays recent research sessions with summaries

  • Lists active research projects with status and phase information

  • Provides a sample of research participants with demographic information

  • Presents your most frequently used codes with reference counts

  • Highlights recent analytical memos with type and summary information

  • Formats information in an easily scannable format for quick orientation

  • Integrates with the loadcontext tool for deeper exploration

  • Maintains continuity between research sessions

  • Tracks research session history for progress review

  • Displays high-priority research tasks needing attention

  • Shows status information for key research activities

  • Presents sequential relationships between research processes

Parameters explained: No parameters required - the tool automatically retrieves all relevant context.

Return information:

  • A unique session identifier

  • Recent research sessions (up to 3) with:

    • Date

    • Project name

    • Brief summary

  • Active research projects with:

    • Project name

    • Current status

    • Research phase

  • Sample participants (up to 5) with:

    • Participant name

    • Demographic information

    • Participation status

  • Top codes (up to 10) with:

    • Code name

    • Reference count

    • Code group

  • Recent memos (up to 3) with:

    • Memo name

    • Creation date

    • Memo type

    • Brief summary

  • High-priority research tasks (up to 5) with:

    • Task name

    • Current status

    • Associated project

  • Upcoming research activities (up to 3) with:

    • Activity name

    • Scheduled date

    • Prerequisite activities

    • Current status

Status and Priority Information:

  • Research activities are displayed with their current status values

  • High-priority tasks are prominently highlighted for attention

  • Valid status values include: planning, data_collection, analysis, writing, complete, scheduled, conducted, transcribed, coded, analyzed, emerging, developing, established, preliminary, draft, final, active, in_progress

  • Priority values (high, low) help indicate which tasks need immediate attention

Sequential Process Information:

  • Upcoming activities show prerequisite tasks that must be completed first

  • Research phases are presented in their logical sequence

  • The precedes relation is used to determine activity ordering

  • Sequential relationships help visualize the research workflow

Session Workflow:

  1. Start a research session with startsession

  2. Review the provided context to decide what to focus on

  3. Use loadcontext to retrieve detailed information about specific research elements

  4. Conduct your analysis, adding new elements with buildcontext as needed

  5. End the session with endsession to record your research progress

You should:

  • Begin each focused research period with startsession to establish context

  • Review recent sessions to maintain continuity in your research

  • Identify active projects that require attention

  • Note available participants for interview analysis

  • Consider frequently used codes that may indicate important patterns

  • Review recent memos to reconnect with your analytical thinking

  • Prioritize high-priority tasks for immediate attention

  • Check the status of research activities to maintain progress awareness

  • Consider sequential relationships when planning your research activities

  • Use the session ID when using other tools to maintain session tracking

  • After completing a session, record your progress using endsession

  • Establish a regular cadence of research sessions to maintain momentum

  • Use the structured overview to make deliberate choices about where to focus your analytical effort

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains what the tool does: generates a session ID, retrieves and displays various research elements (projects, participants, codes, memos, tasks, activities), formats information for orientation, and integrates with loadcontext. It details return information structure, status/priority values, sequential processes, and session workflow. However, it doesn't explicitly mention potential limitations like data freshness or error conditions, keeping it from a perfect score.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is excessively long (over 600 words) with repetitive sections (e.g., 'Key features' and 'Return information' overlap, 'You should' reiterates earlier points). While well-structured with headings, it includes unnecessary details like specific status value lists and step-by-step workflows that could be condensed. The core purpose and usage are clear but buried in verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (initializing research sessions with multiple data types) and lack of annotations/output schema, the description is exceptionally complete. It covers purpose, usage, behavioral details, return information structure, status/priority systems, sequential processes, workflow integration with siblings, and actionable guidelines. No critical gaps exist for an agent to understand and use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0 parameters with 100% coverage, so the baseline is 4. The description adds value by explicitly stating 'No parameters required - the tool automatically retrieves all relevant context,' which clarifies the parameterless nature beyond what the empty schema implies. This prevents confusion about missing inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's purpose as 'initializing a new qualitative research session' and 'providing structured information about ongoing research projects, participants, analytical elements, and recent research activities.' It clearly distinguishes this from sibling tools like loadcontext (for deeper exploration) and endsession (for recording progress), establishing it as the entry point for research sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a dedicated 'When to use this tool' section with 13 specific scenarios (e.g., 'Beginning a new research analysis session,' 'Getting oriented to your current research state'), and a 'You should' section with 13 actionable guidelines (e.g., 'Begin each focused research period with startsession,' 'Use the session ID when using other tools'). It explicitly positions startsession as the first step in a workflow that includes loadcontext and endsession, providing clear alternatives and sequencing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.0.0
    • Changedstartsession1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
  2. 6 tool updates
    • First observedadvancedcontext
    • First observedbuildcontext
    • First observeddeletecontext
    • First observedendsession
    • First observedloadcontext
    • First observedstartsession

TDQS

A4.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: advancedcontext for querying, buildcontext for creating, deletecontext for deleting, loadcontext for retrieving detailed context, startsession for session initialization, and endsession for session documentation. There is no overlap in functionality; each tool serves a unique role in the qualitative research workflow.

Naming Consistency5/5

All tool names follow a consistent pattern: they are compound words ending with 'context' or 'session' (advancedcontext, buildcontext, deletecontext, loadcontext, startsession, endsession). This naming scheme is uniform and predictable, making it easy for agents to understand the tool set's structure.

Tool Count5/5

With 6 tools, the server is well-scoped for qualitative research management. The tools cover the full lifecycle: initialization (startsession), creation (buildcontext), querying (advancedcontext, loadcontext), deletion (deletecontext), and session documentation (endsession). Each tool earns its place without redundancy or gaps.

Completeness5/5

The tool set provides complete CRUD/lifecycle coverage for qualitative research. It supports creating, reading (via advancedcontext and loadcontext), updating (implicitly through buildcontext for modifications), and deleting elements. Additionally, startsession and endsession handle session management, ensuring no dead ends in the research workflow.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tejpalvirk/qualitativeresearch'

If you have feedback or need assistance with the MCP directory API, please join our Discord server