REPO-SYNCED SPEC DOC

MCP-AQL Introspection Specification

Document Status: This document is informative. For normative requirements, see MCP-AQL Specification v1.0.0.

Support documentDraft1.0.0-draft2026-04-15

Source: spec/docs/introspection.md

Open Source MarkdownBrowse Full Spec Reference

On this page

Jump to a section

Use the outline to move through longer pages without losing your place.

  1. Abstract
  2. 1. Introduction
  3. 2. Introspection Query Types
  4. 3. Response Structures
  5. 4. Operation Discovery
  6. 5. Type Discovery
  7. 6. Implementation Guidance
  8. 7. Token Efficiency
  9. 8. Conformance Requirements
  10. References

Version: 1.0.0-draft Status: Draft Last Updated: 2026-04-15

Document Status: This document is informative. For normative requirements, see MCP-AQL Specification v1.0.0.

Abstract

This document specifies the MCP-AQL introspection system, which provides GraphQL-style discovery capabilities for operations, parameters, types, and examples at runtime. The introspection system is the only operation that MCP-AQL mandates all adapters implement, enabling AI models to discover capabilities dynamically.

1. Introduction

1.1 Purpose

The introspection system enables AI models to discover available operations at runtime rather than parsing large tool schemas upfront. This provides:

  • On-demand discovery - Query only what is needed
  • Self-documenting API - API describes itself without external documentation
  • Token efficiency - Avoid parsing many tool schemas
  • Dynamic capability detection - Discover adapter-specific operations

1.2 Design Principles

  1. Progressive disclosure - Start with summaries, drill into details
  2. Consistency - Same response structure for all queries
  3. Completeness - Sufficient information to construct valid requests
  4. Efficiency - Minimal response size while maintaining usefulness

1.3 Introspection Flow

The following diagram illustrates how an AI model discovers and uses operations:

graph TB
    subgraph "Introspection Flow"
        LLM[AI Agent]
        INTRO[introspect operation]
        RESOLVER[Introspection Handler]
        SCHEMA[Operation Registry]

        LLM --> |query: operations| INTRO
        INTRO --> RESOLVER
        RESOLVER --> |lookup| SCHEMA
        RESOLVER --> |response| LLM
    end

1.4 Adapter-Defined Content

The introspection system returns information about the adapter's operations and types. Different adapters expose different operations - MCP-AQL defines the introspection mechanism, not the operations themselves.

2. Introspection Query Types

2.1 The introspect Operation

All introspection is performed through the introspect operation as a READ-category operation. In semantic endpoint mode, adapters expose it on a documented READ-oriented endpoint family; in Single mode, it is available through the unified endpoint. This is the only operation that MCP-AQL REQUIRES all adapters to implement.

Request Format:

{
  operation: "introspect",
  params: {
    query: "<query_type>",
    name: "<optional_specific_name>"
  }
}

2.2 Query Types

Query Description Optional name Parameter
operations List all available operations Get details for a specific operation
types List all available types Get details for a specific type

2.3 Query Behavior

Without name parameter: Returns a list of all items of that type with summary information.

With name parameter: Returns detailed information for the specific item.

2.4 Basic Usage Examples

// List all operations
{
  operation: "introspect",
  params: { query: "operations" }
}

// Get details for a specific operation
{
  operation: "introspect",
  params: { query: "operations", name: "create_entity" }
}

// List all types
{
  operation: "introspect",
  params: { query: "types" }
}

// Get details for a specific type
{
  operation: "introspect",
  params: { query: "types", name: "EntityType" }
}

3. Response Structures

3.1 Standard Response Wrapper

All introspection responses MUST follow the standard MCP-AQL discriminated response format:

// Success response
{
  success: true,
  data: {
    // Introspection-specific payload
  }
}

// Failure response
{
  success: false,
  error: {
    code: "INTROSPECTION_ERROR",
    message: "Description of what went wrong"
  }
}

3.2 OperationInfo (List Item)

Summary information for an operation in list responses:

interface OperationInfo {
  name: string;               // Operation identifier (e.g., "create_entity")
  semantic_category: string;  // Standard category (e.g., "CREATE")
  endpoint: string;           // Exposed endpoint family (e.g., "query", "create")
  description: string;        // Brief description
}

3.3 OperationDetails (Detail Response)

Complete information for a specific operation:

interface OperationDetails {
  name: string;                    // Operation identifier
  semantic_category: string;       // Standard category
  endpoint: string;                // Exposed endpoint family
  mcpTool: string;                 // Actual MCP tool name (e.g., "mcp_aql_query")
  description: string;             // Detailed description
  permissions: EndpointPermissions;
  parameters: ParameterInfo[];     // Parameter definitions (see note below)
  returns: TypeInfo;               // Return type information
  examples: OperationExample[];    // Example invocations
  computed_fields?: ComputedFieldInfo[];
  aggregation_support?: AggregationSupport;
  relationship_capabilities?: RelationshipCapabilities;
}

interface EndpointPermissions {
  readOnly: boolean;    // Whether operation modifies state
  destructive: boolean; // Whether operation removes state
}

interface OperationExample {
  description?: string; // Human-readable description of the example
  request: object;      // Example request object
}

interface ComputedFieldInfo {
  name: string;
  type: string;
  description?: string;
  filterable?: boolean;
  sortable?: boolean;
}

interface AggregationSupport {
  supported: boolean;
  default_mode?: "summary_only" | "include_items";
  functions?: string[];
  groupable_fields?: string[];
  numeric_fields?: string[];
}

interface RelationshipCapabilities {
  supported: boolean;
  directions?: Array<"incoming" | "outgoing" | "both">;
  relationship_types?: string[];
  max_depth?: number;
}

Terminology Note: The parameters array here describes the definitions of accepted parameters. At request time, callers provide parameter values via the params object (see Section 4.1 of the normative spec). The keys of params correspond to the name field of each ParameterInfo entry.

3.4 ParameterInfo

Parameter definition with optional constraint metadata:

interface ParameterInfo {
  // Core fields (required)
  name: string;        // Parameter name (snake_case recommended)
  type: string;        // Type name (e.g., "string", "number", "boolean", "array", "object")
  required: boolean;   // Whether parameter is required

  // Documentation (optional)
  description?: string; // Parameter description
  default?: unknown;    // Default value if any

  // Constraint fields (optional) - enable client-side validation and LLM guidance
  enum?: unknown[];     // Allowed values for this parameter
  minimum?: number;     // Minimum value for numeric parameters (inclusive)
  maximum?: number;     // Maximum value for numeric parameters (inclusive)
  minLength?: number;   // Minimum length for string parameters
  maxLength?: number;   // Maximum length for string parameters
  pattern?: string;     // Regex pattern for string validation
  format?: string;      // Semantic format hint (e.g., "date-time", "email", "uri", "uuid")
  items?: object;       // Schema for array element types (nested ParameterInfo)

  // Security (optional)
  sensitive?: boolean;  // Whether parameter contains sensitive data (passwords, API keys)
}

3.4.1 Constraint Field Usage

Constraint fields are the highest-value properties in the introspection system - they prevent LLM hallucination by telling agents exactly what values are valid.

Field Type Purpose
enum array Lists all valid values; LLM can select from these
minimum/maximum number Numeric bounds; LLM can generate values in range
minLength/maxLength integer String length limits
pattern string Regex pattern for validation
format string Semantic format hint (date-time, email, uri, uuid)
items object Element schema for array parameters
sensitive boolean Flag for passwords/API keys; clients SHOULD mask input

Example with constraints:

{
  "name": "page_size",
  "type": "integer",
  "required": false,
  "description": "Number of items per page",
  "default": 25,
  "minimum": 1,
  "maximum": 100
}
{
  "name": "status",
  "type": "string",
  "required": true,
  "description": "Filter by status",
  "enum": ["pending", "active", "completed", "cancelled"]
}
{
  "name": "api_key",
  "type": "string",
  "required": true,
  "description": "API key for authentication",
  "sensitive": true
}

3.5 TypeInfo (List Item)

Summary information for a type:

interface TypeInfo {
  name: string;         // Type identifier
  kind: TypeKind;       // "enum" | "object" | "scalar" | "union"
  description?: string; // Brief description
}

3.6 TypeDetails (Detail Response)

Complete information for a specific type:

interface TypeDetails extends TypeInfo {
  values?: string[];         // For enum types: allowed values
  fields?: ParameterInfo[];  // For object types: field definitions
  members?: string[];        // For union types: member type names
}

4. Operation Discovery

4.1 Listing All Operations

Request:

{
  operation: "introspect",
  params: { query: "operations" }
}

Response (example from a resource management adapter):

{
  "success": true,
  "data": {
    "_protocol": {
      "version": "1.0.0-alpha.1",
      "conformance": "level-1",
      "mode": "semantic",
      "capabilities": {
        "batch": false,
        "field_selection": true,
        "warnings": true
      }
    },
    "operations": [
      {
        "name": "create_entity",
        "semantic_category": "CREATE",
        "endpoint": "manage",
        "description": "Create a new entity"
      },
      {
        "name": "list_entities",
        "semantic_category": "READ",
        "endpoint": "query",
        "description": "List entities with filtering and pagination"
      },
      {
        "name": "get_entity",
        "semantic_category": "READ",
        "endpoint": "query",
        "description": "Get an entity by identifier"
      },
      {
        "name": "update_entity",
        "semantic_category": "UPDATE",
        "endpoint": "manage",
        "description": "Update entity properties"
      },
      {
        "name": "delete_entity",
        "semantic_category": "DELETE",
        "endpoint": "manage",
        "description": "Delete an entity"
      },
      {
        "name": "execute_workflow",
        "semantic_category": "EXECUTE",
        "endpoint": "operate",
        "description": "Start execution of a workflow"
      },
      {
        "name": "introspect",
        "semantic_category": "READ",
        "endpoint": "query",
        "description": "Discover available operations and types"
      }
    ]
  }
}

For the standard CRUDE profile, which remains the default when no alternate semantic-endpoint profile is configured, the endpoint field SHOULD use the lowercase endpoint-family name rather than the MCP tool name:

{
  "success": true,
  "data": {
    "operations": [
      {
        "name": "create_entity",
        "semantic_category": "CREATE",
        "endpoint": "create",
        "description": "Create a new entity"
      },
      {
        "name": "list_entities",
        "semantic_category": "READ",
        "endpoint": "read",
        "description": "List entities with filtering and pagination"
      },
      {
        "name": "update_entity",
        "semantic_category": "UPDATE",
        "endpoint": "update",
        "description": "Update entity properties"
      },
      {
        "name": "delete_entity",
        "semantic_category": "DELETE",
        "endpoint": "delete",
        "description": "Delete an entity"
      },
      {
        "name": "execute_workflow",
        "semantic_category": "EXECUTE",
        "endpoint": "execute",
        "description": "Start execution of a workflow"
      }
    ]
  }
}

4.1.1 Protocol Metadata

The _protocol object in operations list responses provides version and capability information:

Field Type Required Description
version string MUST MCP-AQL spec version (semver format)
conformance string SHOULD Conformance level ("level-1", "level-2")
mode string SHOULD Endpoint mode ("semantic", "single", "all")
capabilities object MAY Feature flags for optional capabilities

"semantic" is the preferred mode value for both the standard CRUDE profile and alternate semantic-endpoint profiles. Earlier drafts may have described the standard profile as "crude", but current introspection metadata SHOULD report "semantic".

Capabilities flags:

Capability Description
batch Supports batch operations
field_selection Supports field selection in responses
aggregations Supports server-side aggregation controls
computed_fields Exposes adapter-declared computed fields
pagination Supports cursor-based pagination
relationship_queries Supports graph and relationship traversal
warnings Includes warnings array in responses
confirmation Supports confirmation token flow
dangerous_operations Has danger level classification

Clients can use protocol metadata to:

  • Adapt behavior to protocol version
  • Detect available features before use
  • Enable graceful degradation for older adapters

Operation detail responses MAY also expose richer query-language metadata:

  • computed_fields for adapter-declared derived values
  • aggregation_support for supported aggregation functions and fields
  • relationship_capabilities for traversal vocabulary and depth limits

4.2 Getting Operation Details

Request:

{
  operation: "introspect",
  params: { query: "operations", name: "create_entity" }
}

Response:

{
  "success": true,
  "data": {
    "operation": {
      "name": "create_entity",
      "semantic_category": "CREATE",
      "endpoint": "manage",
      "mcpTool": "mcp_aql_manage",
      "description": "Create a new entity of any type",
      "permissions": {
        "readOnly": false,
        "destructive": false
      },
      "parameters": [
        {
          "name": "entity_name",
          "type": "string",
          "required": true,
          "description": "Entity name",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$"
        },
        {
          "name": "entity_type",
          "type": "string",
          "required": true,
          "description": "Type of entity to create",
          "enum": ["resource", "item", "config", "workflow"]
        },
        {
          "name": "description",
          "type": "string",
          "required": true,
          "description": "Entity description",
          "maxLength": 500
        },
        {
          "name": "priority",
          "type": "integer",
          "required": false,
          "description": "Priority level",
          "default": 5,
          "minimum": 1,
          "maximum": 10
        },
        {
          "name": "metadata",
          "type": "object",
          "required": false,
          "description": "Additional metadata"
        }
      ],
      "returns": {
        "name": "Entity",
        "kind": "object",
        "description": "Newly created entity"
      },
      "examples": [
        {
          "description": "Create a resource entity",
          "request": {
            "operation": "create_entity",
            "element_type": "resource",
            "params": {
              "entity_name": "MyResource",
              "description": "A sample resource"
            }
          }
        }
      ]
    }
  }
}

4.3 Unknown Operation

When querying for an operation that does not exist, implementations MUST return a success response with null data:

Request:

{
  operation: "introspect",
  params: { query: "operations", name: "nonexistent_operation" }
}

Response:

{
  "success": true,
  "data": {
    "operation": null
  }
}

5. Type Discovery

5.1 Listing All Types

Request:

{
  operation: "introspect",
  params: { query: "types" }
}

Response:

{
  "success": true,
  "data": {
    "types": [
      {
        "name": "EntityType",
        "kind": "enum",
        "description": "Available entity types"
      },
      {
        "name": "SemanticCategory",
        "kind": "enum",
        "description": "Standard semantic categories for operation classification"
      },
      {
        "name": "OperationInput",
        "kind": "object",
        "description": "Standard input structure for all MCP-AQL operations"
      },
      {
        "name": "OperationResult",
        "kind": "union",
        "description": "Standard result type for all operations"
      },
      {
        "name": "OperationSuccess",
        "kind": "object",
        "description": "Successful operation result"
      },
      {
        "name": "OperationFailure",
        "kind": "object",
        "description": "Failed operation result"
      }
    ]
  }
}

5.2 Getting Type Details

5.2.1 Enum Type

Request:

{
  operation: "introspect",
  params: { query: "types", name: "EntityType" }
}

Response:

{
  "success": true,
  "data": {
    "type": {
      "name": "EntityType",
      "kind": "enum",
      "description": "Available entity types",
      "values": ["resource", "item", "config", "workflow"]
    }
  }
}

5.2.2 Object Type

Request:

{
  operation: "introspect",
  params: { query: "types", name: "OperationInput" }
}

Response:

{
  "success": true,
  "data": {
    "type": {
      "name": "OperationInput",
      "kind": "object",
      "description": "Standard input structure for all MCP-AQL operations",
      "fields": [
        {
          "name": "operation",
          "type": "string",
          "required": true,
          "description": "The operation to perform"
        },
        {
          "name": "element_type",
          "type": "string",
          "required": false,
          "description": "Element type for element operations"
        },
        {
          "name": "params",
          "type": "object",
          "required": false,
          "description": "Operation-specific parameters"
        }
      ]
    }
  }
}

5.2.3 Union Type

Request:

{
  operation: "introspect",
  params: { query: "types", name: "OperationResult" }
}

Response:

{
  "success": true,
  "data": {
    "type": {
      "name": "OperationResult",
      "kind": "union",
      "description": "Standard result type for all operations",
      "members": ["OperationSuccess", "OperationFailure"]
    }
  }
}

5.3 Protocol Types

MCP-AQL defines these protocol-level types that adapters SHOULD include in their type registry:

Type Name Kind Description
SemanticCategory enum Standard categories: CREATE, READ, UPDATE, DELETE, EXECUTE
OperationInput object Standard input structure
OperationResult union Success or failure result
OperationSuccess object Successful result with data
OperationFailure object Failed result with error
EndpointPermissions object Permission flags for operations

Adapters define their own domain-specific types in addition to these.

6. Implementation Guidance

6.1 Schema-Driven Architecture

Implementations SHOULD maintain a single source of truth for operation definitions. The introspection system derives its responses from this source:

graph LR
    subgraph "Introspection Source Resolution"
        OP[Operation Name]
        SCHEMA[Operation Schema<br/>Single Source of Truth]
        RESPONSE[Introspection Response]

        OP --> SCHEMA
        SCHEMA --> RESPONSE
    end

6.2 Introspection Handler Architecture

A conforming implementation typically includes these components:

classDiagram
    class IntrospectionHandler {
        +resolve(params) IntrospectionResult
        -listOperations() OperationInfo[]
        -getOperationDetails(name) OperationDetails
        -listTypes() TypeInfo[]
        -getTypeDetails(name) TypeDetails
        +getOperationsByEndpointFamily() Record
        +getOperationsBySemanticCategory() Record
        +getSummary() string
    }

    class OperationRegistry {
        +getOperation(name) OperationSchema
        +getAllOperations() OperationSchema[]
        +isValidOperation(name) boolean
    }

    class TypeRegistry {
        +getType(name) TypeDefinition
        +getAllTypes() TypeDefinition[]
        +isValidType(name) boolean
    }

    IntrospectionHandler --> OperationRegistry : queries
    IntrospectionHandler --> TypeRegistry : queries

6.3 Utility Methods

Implementations MAY provide utility methods for documentation and tooling:

Operations by Endpoint Family:

// Returns operations grouped by exposed endpoint family
getOperationsByEndpointFamily(): Record<string, OperationInfo[]>

Operations by Semantic Category:

// Returns operations grouped by standard semantic category
getOperationsBySemanticCategory(): Record<SemanticCategory, OperationInfo[]>

Summary Generation:

// Returns a human-readable summary of all operations
getSummary(): string

// Example output:
// MCP-AQL Operations:
//   manage: create_entity, update_entity, delete_entity
//   query: list_entities, get_entity, introspect
//   operate: execute_workflow
//
// Semantic Categories:
//   CREATE: create_entity
//   READ: list_entities, get_entity, introspect
//   UPDATE: update_entity
//   DELETE: delete_entity
//   EXECUTE: execute_workflow
//
// Types: EntityType, SemanticCategory, OperationInput, OperationResult
//
// Use introspect with name parameter for details.

7. Token Efficiency

7.1 Discovery Pattern

The introspection system enables a token-efficient discovery pattern:

Step 1: List operations (~50 tokens response)
   { operation: "introspect", params: { query: "operations" } }

Step 2: Get details for relevant operation (~100 tokens response)
   { operation: "introspect", params: { query: "operations", name: "create_entity" } }

Step 3: Execute operation
   { operation: "create_entity", params: { ... } }

7.2 Comparison with Discrete Tools

Approach Upfront Cost Per-Operation Cost Total (10 ops)
Discrete tools ~29,600 tokens 0 ~29,600
MCP-AQL + introspect ~1,100 tokens ~150 tokens ~2,600

7.3 Caching Recommendations

A session is the lifetime of a single MCP connection (see Section 2.3 of the core specification).

Implementations SHOULD:

  • Cache introspection responses for the duration of the MCP connection (session)
  • Return consistent results for the same query within a session
  • Invalidate all cached introspection data when the session ends
  • Invalidate cache mid-session only when server configuration changes

8. Conformance Requirements

8.1 MUST Requirements

Conforming implementations MUST:

  1. Implement the introspect operation as a READ-category operation on a documented endpoint family
  2. Support both operations and types query types
  3. Return OperationInfo for all supported operations when listing
  4. Return OperationDetails when querying a specific operation by name
  5. Return TypeInfo for all supported types when listing
  6. Return TypeDetails when querying a specific type by name
  7. Include accurate parameter information with required flags
  8. Use consistent type names across all responses
  9. Return null for the item (not an error) when querying a non-existent operation or type
  10. Follow the discriminated response format ({ success, data } or { success, error })
  11. Include _protocol object in operations list responses with at least the version field

8.1.1 Introspection Accuracy (MUST)

Introspection responses MUST accurately reflect the actual parameter names, types, and behaviors accepted by the implementation:

  1. Parameter names in introspection MUST match the names expected by the operation handler
  2. Parameter types in introspection MUST match the types accepted by the operation handler
  3. Required/optional status in introspection MUST match the actual handler behavior

8.1.2 Parameter Completeness (MUST)

For every operation, implementations MUST ensure introspection completeness:

  1. Every parameter accepted by the handler implementation MUST appear in introspection metadata
  2. Required parameters MUST appear with required: true
  3. Optional parameters MUST appear with required: false
  4. Feature parameters (e.g., fields, limit, offset) MUST appear with full type information

Conformance Test:

FOR EACH operation in introspection:
  1. Get documented parameters from introspection
  2. Attempt operation with each documented parameter
  3. Attempt operation with known cross-cutting parameters (fields, limit, offset)
  4. Compare accepted vs documented parameters

FAIL IF: Operation accepts parameters not in introspection
WARN IF: Introspection documents parameters not accepted

8.1.3 Error Message Quality (MUST)

Error responses MUST NOT expose internal implementation details:

  1. Error messages MUST NOT include programming language error messages
  2. Error messages MUST NOT include stack traces
  3. Error messages MUST NOT include internal class/object names or file paths

8.2 SHOULD Requirements

Conforming implementations SHOULD:

  1. Include usage examples for all operations
  2. Provide meaningful descriptions for all parameters
  3. Document default values in parameter info
  4. Return each operation's endpoint family and semantic category in list responses
  5. Include the protocol types (SemanticCategory, OperationResult, etc.)
  6. Implement caching for introspection responses
  7. Include the introspect operation in the operations list
  8. Derive introspection data from a single source of truth (operation schema)

8.2.1 Unknown Parameter Handling (SHOULD)

Implementations SHOULD handle unrecognized parameters explicitly:

  1. Accept parameters at documented locations, OR
  2. Return a warning or error when unrecognized parameters are provided
  3. Implementations SHOULD NOT silently ignore parameters

8.2.2 Element-Type Constraints (SHOULD)

Introspection responses SHOULD document element-type-specific constraints:

  1. Read-only or append-only fields SHOULD be documented
  2. Required nesting (e.g., "tags must be in metadata.tags") SHOULD be documented
  3. Operations that don't apply to certain element types SHOULD be noted

8.2.3 Error Message Guidance (SHOULD)

Error responses SHOULD include actionable information:

  1. A clear description of what went wrong
  2. The correct action the user should take
  3. Reference to the appropriate operation if applicable

Recommended Error Message Format:

Missing required parameter '{paramName}'. Expected: {type} ({description})

Examples:

Missing required parameter 'name'. Expected: string (the name of the memory to operate on)
Missing required parameter 'source'. Expected: string (URL or file path to import from)

8.2.4 Deprecated Parameters (SHOULD)

  1. Deprecated parameters SHOULD appear in introspection with a deprecation notice
  2. Deprecated parameters SHOULD include migration guidance in the description

8.3 MAY Requirements

Conforming implementations MAY:

  1. Define additional custom types
  2. Include additional metadata in responses
  3. Support additional query types beyond operations and types
  4. Provide filtering/pagination for large operation lists
  5. Include utility methods for documentation generation
  6. Support field selection on introspection responses

References