Exploratory MCP Tools v2

Exploratory MCP tools are a set of three Workflows that help an agent when it needs to discover an unfamiliar data model in order to select records.

Three-tool shape

List entities returns the available business entities with stable names and short descriptions.
Describe entity accepts one entity name and returns its fields, types, relationships, and supported query capabilities.
Query entity accepts a validated entity plus constrained filters, projection, ordering, and page limits.

This progression lets the agent learn the provider contract without exposing one unrestricted query language or returning the entire schema in every call.

Constrain discovery

Allowlist entity names and supported operators. Apply a small default and hard maximum result size. Require explicit paging tokens or offsets and return them in a stable envelope. Exclude secret, credential, and sensitive fields unless the use case and authorization explicitly require them.

Do not pass provider-native SQL or arbitrary scripts from an MCP argument into a data system. Convert the typed request into parameterized provider operations.

Keep the tools read-only

Separate exploration from mutation. A query tool should not infer that a matching record may be updated. Expose a separate utility tool for each approved business action so users and clients can recognize the side effect.

Observe usage

Log the entity, bounded filter summary, page size, result count, and safe caller context. Redact sensitive filter values and avoid materializing large result sets only for logging.

Example: discover and query orders

For an order explorer, define these example application contracts:

Tool	Example input	Example result
List entities	`{}`	`{"entities":[{"name":"orders","description":"Customer sales orders"}]}`
Describe entity	`{"entity":"orders"}`	`{"fields":[{"name":"orderId","type":"string"},{"name":"status","type":"string"}],"operators":["eq"],"maxPageSize":50}`
Query entity	`{"entity":"orders","filter":{"field":"status","operator":"eq","value":"Open"},"fields":["orderId","status"],"pageSize":10}`	`{"items":[{"orderId":"A100","status":"Open"}],"nextPageToken":null}`

Author these shapes as the MCP Workflows' contracts and implement the validation and provider mapping behind them. The field names and page limit are choices for this example, not built-in platform defaults.

Test the three calls in sequence, then request an unlisted entity, field, or operator and confirm that the query is rejected before reaching the provider. An agent can discover the supported order fields and retrieve a bounded page without being given credentials or unrestricted query access.