Tool Reference

Tool Reference

The Blindata MCP server provides several specialized tools for different data exploration and analysis needs. Each tool is designed to work seamlessly with AI assistants supporting MCP, allowing you to access and analyze your Blindata data through natural language queries.

Available Tools

Universal Search Tool

The most versatile tool for finding resources across your Blindata instance.

Tool Name: universal_search

Parameters:

  • search (string, optional): The search query text. When empty, the tool can still filter by resource types.
  • resource_types (array, optional): List of specific resource types to filter by
  • search_mode (enum, optional): Search mode (AUTO, HYBRID, SEMANTIC, FTS, EXACT_MATCH)

The search parameter accepts any text query that will be matched against resource names, descriptions, and metadata. The resource_types parameter allows you to filter results to specific resource types by providing an array of type names. The search_mode parameter controls the search algorithm, with AUTO being the default that automatically selects the best mode (HYBRID → FTS → EXACT_MATCH).

Supported Resource Types for Filtering:

  • LOGICAL_NAMESPACE, DATA_CATEGORY, LOGICAL_FIELD
  • GOVERNANCE_POLICY_SUITE, GOVERNANCE_POLICY
  • DATA_PRODUCT_DOMAIN, DATA_PRODUCT
  • SYSTEM, PHYSICAL_ENTITY, PHYSICAL_FIELD
  • QUALITY_SUITE, QUALITY_CHECK
  • DATA_ACTOR, PROCESSING, TASK

Usage Examples:

# Find customer-related data products
universal_search(
    search="customer data products",
    resource_types=["DATA_PRODUCT"],
    search_mode="SEMANTIC"
)

# Results:
{
    "resources": [
        {
            "id": "dp_customer_analytics_001",
            "name": "Customer Analytics Dataset",
            "type": "DATA_PRODUCT",
            ...
        },
        ...
    ],
}

 

Fetch Resource Details Tool

Retrieve detailed metadata and contextual information for a specific resource using its unique identifier.

Tool Name: fetch_resource_details

Parameters:

Name Type Required Description
resource_identifier string Yes The unique ID of the resource. Typically obtained from a search operation.
resource_type enum Yes Specifies the type of resource to retrieve. Ensures proper resolution.

Description:

The fetch_resource_details tool allows you to retrieve in-depth information about a specific resource within Blindata.

Supported Resource Types:

The following resource types are supported by fetch_resource_details:

  • LOGICAL_NAMESPACE, DATA_CATEGORY, LOGICAL_FIELD
  • GOVERNANCE_POLICY_SUITE, GOVERNANCE_POLICY
  • DATA_PRODUCT_DOMAIN, DATA_PRODUCT
  • SYSTEM, PHYSICAL_ENTITY, PHYSICAL_FIELD
  • QUALITY_SUITE, QUALITY_CHECK
  • DATA_ACTOR, PROCESSING, TASK

Usage Example:

# Retrieve details of a specific data product
fetch_resource_details(
    resource_identifier="dc17a8a6-b8df-44b9-b906-b155a8df674c",
    resource_type="DATA_PRODUCT"
)

# Example Response:
{
    "data": {
        "uuid": "dc17a8a6-b8df-44b9-b906-b155a8df674c",
        "name": "customerAnalytics",
        "displayName": "Customer Analytics Dataset",
        "identifier": "urn:dpds:blindata:dataproducts:customerAnalytics:1",
        "description": "Comprehensive customer behavior analytics for business intelligence",
        "ports": [],
        ...
    }
}

 

Get Relationships Tool

This tool enables you to navigate between related entities within Blindata, uncovering how data elements are connected through metadata relationships. It supports graph-based exploration, helping you analyze dependencies, trace linkages, and gain a deeper understanding of your data ecosystem.

Tool Name: get_relationships

Parameters:

  • filter_resource_id (string, required): The unique identifier of the filter resource
  • filter_resource_type (enum, required): The type of the filter resource
  • result_resource_type (enum, required): The type of result resources to find

The filter_resource_id parameter specifies the unique identifier of the resource you want to filter by. The filter_resource_type parameter defines the type of the filter resource to ensure proper relationship mapping. The result_resource_type parameter indicates what type of result resources you want to discover, allowing you to explore specific types of connections within your data ecosystem.

Supported Resource Types:

All resource types are supported for both filter and result parameters:

  • Logical Model: LOGICAL_NAMESPACE, DATA_CATEGORY, LOGICAL_FIELD, LOGICAL_RELATION, LOGICAL_PREDICATE
  • Physical Model: SYSTEM, PHYSICAL_ENTITY, PHYSICAL_FIELD, PHYSICAL_CONSTRAINT
  • Data Products: DATA_PRODUCT, DATA_PRODUCT_DOMAIN
  • Data Quality: QUALITY_SUITE, QUALITY_CHECK, QUALITY_RESULT
  • Governance: GOVERNANCE_POLICY_SUITE, GOVERNANCE_POLICY, GOVERNANCE_POLICY_ADOPTION, GOVERNANCE_POLICY_EVALUATION
  • Processing: DATA_ACTOR, PROCESSING, TASK
  • Settings: USER, TEAM, STEWARDSHIP_ROLE, RESPONSIBILITY
  • Social: ISSUE, COMMENTS

Usage Examples:

# Find all data categories related to a logical namespace
get_relationships(
    filter_resource_id="11223344-5566-7788-99aa-bbccddeeff00",
    filter_resource_type="LOGICAL_NAMESPACE",
    result_resource_type="DATA_CATEGORY"
)

# Results:
{
    "related_objects":
    [
        {
            "createdAt": "2025-04-10T08:15:30.123Z",
            "updatedAt": "2025-04-15T14:22:45.456Z",
            "teamCode": null,
            "uuid": "83d8c6f1-1f9d-4b20-bb65-9c4a12345678",
            "name": "ItemBrand",
            "displayName": "Item Brand",
            "description": "The brand associated with the item",
            "clearance": null,
            "dataClass": "Inventory Metadata"
        },
        {
            "createdAt": "2025-04-11T10:42:10.789Z",
            "updatedAt": "2025-04-17T09:38:15.321Z",
            "teamCode": null,
            "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "ItemType",
            "displayName": "Item Type",
            "description": "Specifies the type or category of item",
            "clearance": null,
            "dataClass": "Inventory Metadata"
        },
        ...
    ],
    "count": 8,
    "via":"explicit_filter:namespaceUuid"
}

 

Traverse Tool

Explore multi-hop lineage, ontology, or data product dependency graphs from a known seed resource. The tool returns a graph structure with parent nodes, attribute or port subnodes, and edges—replacing many sequential relationship and detail calls with a single exploration.

Tool Name: traverse

Parameters:

  • resource_identifier (string, required): UUID of the seed resource
  • resource_type (enum, required): Type of the seed resource (see supported seed types below)
  • direction (enum, optional): Traversal direction — upstream, downstream, or all (default: all)
  • depth (integer, optional): Maximum hops from the seed, 1–10 (default: 3)
  • size (integer, optional): Maximum new nodes discovered per hop, 1–50 (default: 10)

The resource_identifier and resource_type parameters define the starting point of the graph. The direction parameter controls whether to follow upstream dependencies, downstream consumers, or both. The depth parameter limits how many hops the exploration extends from the seed, while the size parameter caps graph breadth per hop.

When to use traverse vs other tools:

Use traverse Use get_relationships instead
Multi-hop lineage, ontology, or dependency paths from a seed A flat list of all related resources of one target type
Graph output (nodes + edges) for impact or narrative analysis A simple related_objects list when the result type is already known

Use fetch_resource_details for full resource bodies (SQL, complete metadata). Use universal_search when the seed ID or type is unknown.

Supported Seed Types:

  • Lineage: PHYSICAL_ENTITY, PHYSICAL_FIELD
  • Ontology: DATA_CATEGORY, LOGICAL_FIELD
  • Data products: DATA_PRODUCT, DATA_PRODUCT_PORT

Response structure:

The tool returns a canonical graph envelope with four top-level keys:

  • nodes: Parent resources with resource_type, resource_identifier, name, and optional description, schema (physical entities), namespace (data categories), or domain (data products). Child attributes, columns, or ports appear in nested subnodes.
  • edges: Links between parent nodes, with optional source_subnode and target_subnode for field-, attribute-, or port-level connections. Lineage edges reference DATA_FLOW resources; ontology edges reference LOGICAL_RELATION resources. Data product mesh edges omit link resource identity and express port-to-port or system-to-port dependencies only.
  • context: Deduplicated shared payloads keyed by references on edges. For lineage, entries use keys like query_statement:<uuid> and contain the transformation SQL (queryText). Ontology and data product responses typically leave context empty because relation or dependency details appear on the edges themselves.
  • summary: Counts of nodes and edges in the returned graph.

Usage Examples:

# Explore upstream lineage from a physical entity
traverse(
    resource_identifier="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    resource_type="PHYSICAL_ENTITY",
    direction="upstream",
    depth=3,
    size=10
)

# Results:
{
    "nodes": [
        {
            "resource_type": "PHYSICAL_ENTITY",
            "resource_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "payment",
            "schema": "finance",
            "subnodes": [
                {
                    "resource_type": "PHYSICAL_FIELD",
                    "resource_identifier": "field-a-uuid",
                    "name": "customer_id"
                }
            ]
        },
        {
            "resource_type": "PHYSICAL_ENTITY",
            "resource_identifier": "entity-b-uuid",
            "name": "invoice",
            "schema": "finance",
            "subnodes": [
                {
                    "resource_type": "PHYSICAL_FIELD",
                    "resource_identifier": "field-b-uuid",
                    "name": "customer_id"
                }
            ]
        }
    ],
    "edges": [
        {
            "resource_type": "DATA_FLOW",
            "resource_identifier": "df-uuid-1",
            "name": "Payment to Invoice",
            "source": "entity-b-uuid",
            "target": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "source_subnode": "field-b-uuid",
            "target_subnode": "field-a-uuid",
            "context_ref": "query_statement:qs-uuid-1"
        }
    ],
    "context": {
        "query_statement:qs-uuid-1": {
            "queryText": "SELECT customer_id FROM payment"
        }
    },
    "summary": {
        "node_count": 2,
        "edge_count": 1
    }
}

# Explore downstream ontology from a data category
traverse(
    resource_identifier="concept-a-uuid",
    resource_type="DATA_CATEGORY",
    direction="downstream",
    depth=3,
    size=10
)

# Explore upstream data product dependencies from a port
traverse(
    resource_identifier="consumer-in-port-uuid",
    resource_type="DATA_PRODUCT_PORT",
    direction="upstream",
    depth=3
)

 

Get JSON Schema Tool

Retrieve the JSON schema definition for a Blindata resource type before creating or updating it with write_resource.

Tool Name: get_json_schema

Parameters:

Name Type Required Description
resource_type enum Yes The resource type for which to retrieve the JSON schema.

Description:

The get_json_schema tool returns the bundled JSON schema for the requested resource type. Use it to inspect property definitions, validation rules, required fields, and schema version before calling write_resource.

The returned schema includes:

  • Property definitions and types
  • Required fields and validation rules
  • Field descriptions and metadata
  • resourceType and version metadata used by the write workflow

If no schema is available for a resource type, the tool returns an error and that type cannot be created or updated through MCP.

Supported Resource Types:

Business Glossary (logical model):

  • DATA_CATEGORY
  • LOGICAL_FIELD
  • LOGICAL_PREDICATE
  • LOGICAL_NAMESPACE
  • LOGICAL_RELATION

Data Catalog (physical model):

  • PHYSICAL_ENTITY
  • PHYSICAL_FIELD

Usage Example:

# Inspect the schema before creating or updating a logical field
get_json_schema(
    resource_type="LOGICAL_FIELD"
)

# Example Response:
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "LogicalField",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "The logical field name"
        },
        "description": {
            "type": "string",
            "description": "The logical field description"
        },
        "dataType": {
            "type": "string",
            "description": "The data type of the field"
        },
        "dataCategory": {
            "type": "object",
            "properties": {
                "uuid": {"type": "string"}
            }
        }
    },
    "required": ["name"],
    "resourceType": "LOGICAL_FIELD",
    "version": "1.0.0"
}

 

Write Resource Tool

Create or update one or more Blindata resources of the same type in a single MCP call.

Tool Name: write_resource

Parameters:

Name Type Required Description
resource_object object or array Yes A single resource dict, or a list of dicts for batch create/update.
resource_type enum Yes The resource type to write. All items in a batch must share this type.

Description:

The write_resource tool validates each item against the bundled JSON schema for the given resource_type, then issues POST requests (create) or PUT requests (update) to the appropriate Blindata API endpoint. Schemas are loaded server-side—the client does not pass a schema object to this tool.

Create vs update (per item):

  • Create: omit uuid, or leave it empty.
  • Update: include a non-empty uuid; the tool calls PUT /…/{uuid} with the validated body.

Batch writes:

Pass resource_object as a list to create or update multiple resources of the same type in one call. The server processes items sequentially and returns a per-item result list plus a summary. Batch size is capped (default 40 items per call) to stay within the MCP tool-call time budget—split larger jobs into multiple calls.

Workflow:

  1. Call get_json_schema(resource_type=…) to inspect required and optional fields.
  2. Build one dict, or a list of dicts, that conforms to the schema.
  3. Call write_resource(resource_object=…, resource_type=…).

Important Guidelines:

  1. Schema-first: always call get_json_schema before writing. If the schema is unavailable, the resource type cannot be modified through MCP.
  2. Required fields: include every field marked as required in the schema. Do not invent values for missing user input.
  3. Optional fields: omit optional properties when no value is provided.
  4. Resource references: for nested references (for example dataCategory, namespace, system, physicalEntity), pass only the referenced resource UUID unless the schema requires additional fields.
  5. Data Catalog scope: PHYSICAL_ENTITY and PHYSICAL_FIELD are writable. SYSTEM is not—entities and fields reference an existing system by UUID.

Supported Resource Types:

Business Glossary (logical model):

  • DATA_CATEGORY
  • LOGICAL_FIELD
  • LOGICAL_PREDICATE
  • LOGICAL_NAMESPACE
  • LOGICAL_RELATION

Data Catalog (physical model):

  • PHYSICAL_ENTITY
  • PHYSICAL_FIELD

Usage Examples:

Creating a single resource:

# Step 1: inspect the schema
get_json_schema(resource_type="LOGICAL_FIELD")

# Step 2: create the resource
write_resource(
    resource_object={
        "name": "Customer ID",
        "description": "Unique identifier for customers",
        "dataType": "VARCHAR",
        "dataCategory": {"uuid": "existing-category-uuid"}
    },
    resource_type="LOGICAL_FIELD"
)

# Example Response:
{
    "resourceType": "LOGICAL_FIELD",
    "results": [
        {
            "index": 0,
            "uuid": "new-logical-field-uuid",
            "status": "201",
            "success": true,
            "data": {
                "uuid": "new-logical-field-uuid",
                "name": "Customer ID",
                "description": "Unique identifier for customers",
                "dataType": "VARCHAR"
            },
            "error": null
        }
    ],
    "summary": {"total": 1, "succeeded": 1, "failed": 0}
}

Updating an existing Data Catalog entity:

get_json_schema(resource_type="PHYSICAL_ENTITY")

write_resource(
    resource_object={
        "uuid": "existing-entity-uuid",
        "name": "customers",
        "schema": "sales",
        "description": "Customer master table",
        "system": {"uuid": "existing-system-uuid"}
    },
    resource_type="PHYSICAL_ENTITY"
)

Batch update (same resource type):

write_resource(
    resource_object=[
        {
            "uuid": "field-uuid-1",
            "name": "customer_id",
            "description": "Primary customer identifier",
            "physicalEntity": {"uuid": "existing-entity-uuid"}
        },
        {
            "uuid": "field-uuid-2",
            "name": "email",
            "description": "Customer email address",
            "physicalEntity": {"uuid": "existing-entity-uuid"}
        }
    ],
    resource_type="PHYSICAL_FIELD"
)

Error Handling:

The tool returns structured errors at two levels:

Call-level errors (no results array):

  • Schema unavailable or incomplete for the requested resource_type
  • Empty batch list, invalid item type in a batch, or batch exceeds the configured maximum
  • Missing API endpoint mapping for the resource type

Per-item errors (inside results):

  • JSON Schema validation failures
  • Missing uuid on an update attempt
  • Blindata API errors for that specific item

When a batch contains mixed outcomes, successful items are committed and failed items are reported individually in results with summary.succeeded and summary.failed counts.

Updated on 10 Jun 2026