Docs: updating mcp tools reference page by PubChimps · Pull Request #226 · open-metadata/docs-om

PubChimps · 2026-05-07T22:22:46Z

All MCP tools now on single docs page, added new tools, revised params to match

mintlify · 2026-05-07T22:22:53Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
openmetadata	🟢 Ready	View Preview	May 7, 2026, 10:27 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

ayush-shah

Validated this reference update against the MCP implementation source of truth: openmetadata-mcp/src/main/resources/json/data/mcp/tools.json, DefaultToolContext.java, and the individual tool classes.

The consolidation is needed and directionally correct, but there are several schema/implementation mismatches that should be fixed before merge. I left the inline comments on the v1.12.x copy; please mirror the same content fixes into v1.13.x-SNAPSHOT/how-to-guides/mcp/reference.mdx because the two reference pages are currently identical in this PR.

ayush-shah · 2026-05-11T04:35:26Z

 | `fields` | string | No | Comma-separated additional fields to include |
+| `queryFilter` | string | No | Advanced: direct OpenSearch DSL JSON query |
+| `includeDeleted` | boolean | No | Include deleted entities (default: false) |
+| `includeAggregations` | boolean | No | Include aggregation/facet data (default: false) |


The implementation and schema also expose maxAggregationBuckets for search_metadata (tools.json and SearchMetadataTool). Since this page now claims to be the complete MCP tool reference, please add this optional parameter beside includeAggregations with the default/max behavior: default 10, max 50.

Added maxAggregationBuckets to search_metadata with default/max behavior in both versions in commit 02426d6.

ayush-shah · 2026-05-11T04:35:26Z

+### semantic_search

-**Description**: Retrieve detailed information about a specific entity using its fully qualified name.
+**Description**: Find data assets by meaning using vector search ([setup guide](../../../deployment/semantic-search#enable-semantic-search-openmetadata-deployment-guide)). Use for exploratory queries where you don't know exact names. Returns conceptually related assets even when no keywords match.


The relative page path is right, but the hash looks stale. The target page heading is # Enable Semantic Search, so this should likely link to ../../../deployment/semantic-search#enable-semantic-search. Mintlify link checks often validate the page path without catching a bad fragment.

Updated the semantic search setup link fragment to #enable-semantic-search in both pages in commit 02426d6.

ayush-shah · 2026-05-11T04:35:26Z

+    "arguments": {
+      "query": "revenue forecasting and financial reporting",
+      "filters": {
+        "entity_type": ["table", "dashboard"],


This filter key should be entityType, not entity_type. SemanticSearchTool passes filter keys through to VectorSearchQueryBuilder, and that builder only handles entityType; unknown keys are ignored, so this example would silently fail to filter by entity type.

Updated semantic search filter docs/examples to use entityType (not entity_type) in both versions in commit 02426d6.

ayush-shah · 2026-05-11T04:35:26Z

+    "arguments": {
+      "entityType": "table",
+      "fqn": "mysql_prod.ecommerce.public.customer_orders",
+      "patch": [


patch is documented here as a JSON array, but both tools.json and PatchEntityTool expect patch to be a JSON array string. PatchEntityTool casts params.get("patch") to String before parsing it with Json.createReader(...), so this example would fail as written. Please either stringify the patch in the example or update the schema/implementation to accept arrays.

Updated patch_entity example so patch is a JSON array string as required by the current implementation, in both pages in commit 02426d6.

ayush-shah · 2026-05-11T04:35:26Z

+| `name` | string | Yes | Name of the term |
+| `description` | string | Yes | Definition of the term |
+| `parentTerm` | string | No | FQN of the parent term (for nested/hierarchical terms) |
+| `owners` | array | No | List of owner usernames or emails |


create_glossary_term also supports optional reviewers in both tools.json and GlossaryTermTool. Please add it to the parameter table so the consolidated reference stays aligned with the actual tool schema.

Added optional reviewers to create_glossary_term parameter tables in both versions in commit 02426d6.

ayush-shah · 2026-05-11T04:35:26Z

+
+**Description**: Create a new metric entity in OpenMetadata to track and standardize business KPIs.
+
+> See the Sandbox/Collate tool schema for required parameters specific to your OpenMetadata version.


This placeholder leaves create_metric effectively undocumented. The actual schema has required name, metricExpressionLanguage, and metricExpressionCode, plus optional fields like metricType, granularity, unitOfMeasurement, owners, reviewers, relatedMetrics, tags, and domains. Please add a parameter table and at least one valid example instead of deferring to the tool schema.

Replaced the placeholder with a full create_metric parameter table and valid example in both versions in commit 02426d6.

ayush-shah · 2026-05-11T04:35:26Z

+
+**Description**: Create a data quality test case for a table or column. For column tests, ensure the column's data type is listed in the test definition's `supportedDataTypes`.
+
+> See the Sandbox/Collate tool schema for the full parameter list, as parameters vary by test definition.


This section needs a real parameter table and example. tools.json exposes name, fqn, columnName, entityType, testDefinitionName, description, and parameterValues; clients see name, fqn, testDefinitionName, and parameterValues as required. Without those details, users cannot construct a valid create_test_case call from the reference page.

Added a full create_test_case parameter table (including required fields) and a valid example in both versions in commit 02426d6.

ayush-shah · 2026-05-11T04:35:26Z

+
+### root_cause_analysis
+
+**Description**: Trace a data quality failure back to its origin by traversing data quality lineage across pipeline hops.


root_cause_analysis is listed as an available tool but is missing its required and optional params. The schema requires fqn and entityType, and supports upstreamDepth, downstreamDepth, queryFilter, and includeDeleted. Please add a parameter table and example so this is usable as a reference.

Added root_cause_analysis required/optional parameters and a usable example in both versions in commit 02426d6.

ayush-shah

Revalidated current head fd97a6a7.

Validation:

rtk mint broken-links: passed.
git diff --check origin/main...refs/remotes/pr/226: reports new blank line at EOF in both v1.12.x/how-to-guides/mcp/reference.mdx and v1.13.x-SNAPSHOT/how-to-guides/mcp/reference.mdx.

The earlier schema/implementation review on this same head still applies; please also remove the EOF blank lines before merge.

ayush-shah · 2026-05-13T10:23:36Z

@copilot go through the open comments, validate them and fix those

Agent-Logs-Url: https://github.com/open-metadata/docs-om/sessions/d5aa7e03-8401-49c5-b0a6-dbc438aac06b Co-authored-by: ayush-shah <40225091+ayush-shah@users.noreply.github.com>

Copilot · 2026-05-13T10:29:19Z

Validated this reference update against the MCP implementation source of truth: openmetadata-mcp/src/main/resources/json/data/mcp/tools.json, DefaultToolContext.java, and the individual tool class...

Applied all requested schema/implementation alignment fixes and mirrored them to v1.13.x-SNAPSHOT/how-to-guides/mcp/reference.mdx in commit 02426d6.

Revalidated current head fd97a6a7.

Validation:...

Removed the EOF blank-line issue and addressed the earlier schema alignment points in both reference files in commit 02426d6.

@copilot go through the open comments, validate them and fix those

Reviewed all open actionable comments, validated them, and applied the requested fixes in commit 02426d6.

updating mcp tools reference page

50f3896

mintlify Bot deployed to staging May 7, 2026 22:27 View deployment

update docs.json to remove 2nd mcp tools page

e33a61e

mintlify Bot deployed to staging May 7, 2026 22:37 View deployment

add links to mcp ref page

e586360

mintlify Bot deployed to staging May 7, 2026 23:20 View deployment

add link to semantic search setup

fd97a6a

mintlify Bot deployed to staging May 7, 2026 23:31 View deployment

ayush-shah requested changes May 11, 2026

View reviewed changes

ayush-shah reviewed May 11, 2026

View reviewed changes

Copilot started work on behalf of ayush-shah May 13, 2026 10:23 View session

Docs: Align MCP tool reference schema details (#226)

02426d6

Agent-Logs-Url: https://github.com/open-metadata/docs-om/sessions/d5aa7e03-8401-49c5-b0a6-dbc438aac06b Co-authored-by: ayush-shah <40225091+ayush-shah@users.noreply.github.com>

Copilot finished work on behalf of ayush-shah May 13, 2026 10:30

Copilot AI requested a review from ayush-shah May 13, 2026 10:30


		Description: Create a new metric entity in OpenMetadata to track and standardize business KPIs.

		> See the Sandbox/Collate tool schema for required parameters specific to your OpenMetadata version.


		Description: Create a data quality test case for a table or column. For column tests, ensure the column's data type is listed in the test definition's `supportedDataTypes`.

		> See the Sandbox/Collate tool schema for the full parameter list, as parameters vary by test definition.


		### root_cause_analysis

		Description: Trace a data quality failure back to its origin by traversing data quality lineage across pipeline hops.

Conversation

PubChimps commented May 7, 2026

Uh oh!

mintlify Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ayush-shah left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 13, 2026

Choose a reason for hiding this comment

Uh oh!

ayush-shah left a comment

Choose a reason for hiding this comment

Uh oh!

ayush-shah commented May 13, 2026

Uh oh!

Copilot AI commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mintlify Bot commented May 7, 2026 •

edited

Loading

Copilot AI commented May 13, 2026 •

edited

Loading