MCP Tool List¶

This document describes the business tool capabilities currently callable through MCP on OWL MCP Server, including tool categories, permission types, usage conventions, a tool overview, and typical MCP usage paths.

Tool visibility and call results depend on the permissions of the API Key used for the current connection. If the API Key does not have permission for the relevant resources or operations, the corresponding tool call may fail or return empty results.

Tool Scope¶

The business tools executable by OWL MCP Server are continuously updated as platform capabilities evolve. The actual executable tools are subject to the tool catalog returned by list_catalogs and list_tools.

This document covers the following business categories:

Permission Types¶

Usage Conventions¶

In facade mode, the MCP client should call tools in the following order:

1. Call list_catalogs to view available categories.
2. Call list_tools with catalog_id to view the business tools and parameters under that category.
3. Call exec_tool with tool_name and parameters to execute the business tool.

In static mode, the client can directly call the business tools returned by tools/list without going through the three wrapper tools. Regardless of the mode used, the tool parameters and permission requirements remain the same.

Tool Overview¶

Account¶

Use the following tools for same-organization discovery. The workspace_uuid obtained can be used as the workspace_uuids parameter of owl.data.same_org.trace.query for cross-workspace Trace queries.

Note: In the returned result, workspace_uuid is the value to pass as the subsequent workspace_uuids parameter; workspace_id is used only for list pagination. Do not pass it to the Trace query tool.

Catalog¶

Used for entity type discovery, entity queries, entity details retrieval, and topology relationship queries in the unified resource catalog.

Note: Dashboard tools (owl.dashboard.create / owl.dashboard.replace / owl.dashboard.get) are available only in OWL CLI and do not appear in the MCP tool list. For related usage, see the OWL CLI documentation.

Data¶

As of v1.5.0, owl.metric/rum/apm/network/profile/logging/billing.list and owl.infrastructure.list/get must be passed 13-digit millisecond-level start_time / end_time values, and the time window must not exceed 7 days. The time range for owl.llm.list is optional; when both are omitted, the last 24 hours are used.

The dql_namespace returned by owl.data.show_dql_namespace is a query alias, not the backend raw type name. Pass it to dql_namespace when calling owl.data.query; when calling the simple query or log Pattern analysis tools, pass the same value unchanged to namespace.

Authorized query workspaces are discovered through owl.workspace.data_authorized.list, which supports region_code, search, page_index, and page_size, with independent pagination per site. Pass the workspace_uuid and region_code to the workspace_uuids and target_region parameters of owl.data.simple_query to query multiple authorized workspaces within the same target site. For details, see Cross-workspace query notes.

Used for DQL namespace exploration, data source and field discovery, read-only SQL for external data sources, Log Index discovery, SLO queries, log Pattern analysis, same-organization cross-workspace Trace queries, and simplified data queries for MCP clients. The MCP side currently provides simplified query and query helper tools; it does not include full DQL or PromQL custom execution tools.

For owl.data.same_org.trace.query, when workspace_uuids is omitted or passed as an empty array, only the current workspace is queried. When the same-organization cross-workspace query feature is disabled, only the current workspace can be queried; passing UUIDs of other workspaces returns a parameter error.

Errors¶

Used for querying the Error Center issue list and for adding, querying, and updating comments.

Event¶

Used for event center list queries and event detail retrieval.

• owl.event.list requires start_time and end_time; the optional values of status are fatal, critical, error, warning, and nodata; the default value of limit is 20, and the maximum is 100. The returned items may include the event dimension tag field df_dimension_tags.
• The timeRange of owl.event.get is an optional two-element array [start, end], where both elements are 13-digit millisecond timestamps, and end must be greater than start. The parameter name is timeRange; do not change it to time_range.

Incident¶

owl.incident.get accepts an incident UUID (incident_*) and returns details plus related_event_refs. Related references have a default and maximum page size of 100. Read subsequent pages according to page_info.has_more and next_page_index, then call owl.event.get based on the event references. Do not treat the incident UUID as an event document ID. The total number of references may differ from the total event count reported by the incident; retain and explain missing evidence.

Used for incident list and details, related event references, incident comments, operation logs, and On-Call schedule queries.

Infrastructure¶

Used for infrastructure object list and details queries, covering resource objects such as hosts, containers, and processes.

LLM¶

Used for querying the list of LLM observability applications.

Workspace¶

Used for discovering the authorization scope of cross-workspace data queries, and for querying the current workspace member list with keyword search by name or email.

owl.member.list is retained as a compatibility alias for explicit calls and is not listed as a standalone tool. The CLI must be upgraded to a version that supports aliases and then run owl sync.

Monitor¶

Used for monitor list queries, detail retrieval, creation or update, and external event reception.

Notes¶

Used to manage notes visible to the current API Key account.

• For owl.nbook_note.list, the default value of page_index is 1, the default value of page_size is 20, and the maximum is 100.
• owl.nbook_note.get is the only note tool that returns the Markdown body content, but it does not return path, etag, or version; list, add, and modify return only summaries, without content, path, ETag, or version information; the delete response retains the backend's original minimal structure.
• type supports normal and runbook. owl.nbook_note.list can filter by type; when omitted, the type is not filtered. owl.nbook_note.add can set type; when omitted, the backend creates a normal note. The responses of get and modify include type, but get, modify, and delete do not accept a type parameter, and the type of an existing note cannot be modified.
• owl.nbook_note.add requires title and content and does not accept path; created_source is always set to ai by the server, and the creator account is taken from the current API Key.
• owl.nbook_note.modify requires at least one of title, content, tags, or tag_kv in addition to note_uuid; when content is omitted, the original body is retained.
• Get, modify, and delete all use the note_uuid returned by the list. Do not pass backend-managed fields such as path, etag, if_match, version, creator, or created_source.
• tagkv_query is the TagKV expression string used by the list tool; tag_kv is the key-value object used by the creation and modification tools. Do not mix them up.

Pipeline¶

Used for Pipeline list queries and sample validation.

mdsearch¶

Used for searching the unified documentation corpus, reading full documents by id or path, and browsing the corpus directory structure. Supports Chinese, English, and mixed queries.

MCP Usage Paths¶

The following steps use the default facade mode as an example. If static mode is enabled on the server, you can directly call the business tools with the same names without going through exec_tool.

Data Query Questions¶

Applies to questions such as "Query Metrics, logs, RUM, APM, Network, or Profile data".

1. Use exec_tool to call owl.data.show_dql_namespace to confirm the data namespace.
2. Based on the data domain, use exec_tool to call discovery tools:
3. Metrics: owl.metric.list
4. RUM: owl.rum.list
5. APM: owl.apm.list
6. Network: owl.network.list
7. Profile: owl.profile.list
8. Logs: owl.logging.list
9. Cloud billing: owl.billing.list
10. Log Indexes: owl.log_index.list
11. Field catalog: owl.field_schema.get
12. After obtaining the necessary source, field, and index, use exec_tool to call owl.data.simple_query to run the query.

External Data Source Query¶

1. When only a connector data source ID or name is available, first call owl.external_datasource.list; prefer exact match on datasource_id, otherwise exact match on name, and resolve the unique datasource_uuid. Do not guess when there are zero or multiple matches.
2. When tables or fields are unclear, execute restricted discovery statements only when the capabilities returned by the data source allow it. Func MySQL currently declares only select/with; use information_schema.tables/columns queries with limited fields and row counts, and do not attempt undeclared SHOW/DESCRIBE/EXPLAIN statements.
3. When querying raw rows, use a deterministic ORDER BY and SQL LIMIT; max_rows is only response protection. truncated=true means the result is incomplete.
4. datasource_id is used only for discovery; queries must submit the datasource_uuid returned by the list. Do not submit DSNs, passwords, connection URLs, server IDs, or workspace identifiers.

Incident Troubleshooting Questions¶

Applies to questions such as "Query incidents, track incident handling progress, and add incident comments".

1. When the incident UUID is known, use exec_tool to call owl.incident.get; when the target is not determined, first call owl.incident.list.
2. Read all related event references according to the returned pagination information, then call owl.event.get to obtain event content.
3. Use owl.incident_comment.list to view comments and owl.incident_operation.list to view operation logs.
4. When additional handling information is needed, use exec_tool to call owl.incident_comment.add.

Resource Object Location Questions¶

Applies to questions such as "Query details of infrastructure objects like hosts, containers, and processes".

1. Use exec_tool to call owl.infrastructure.list to find the target object.
2. Based on the identifier information in the returned result, use exec_tool to call owl.infrastructure.get to obtain the object details.

Cross-Workspace Trace Query Questions¶

Applies to questions such as "Query a Trace across multiple workspaces in the same organization by trace_id".

1. Query the Trace directly in the current workspace; when another same-organization workspace is needed and its UUID is not determined, use exec_tool to call owl.account.workspace.same_org.list to discover candidate workspaces.
2. Take workspace_uuid from the returned result (do not take workspace_id).
3. Use exec_tool to call owl.data.same_org.trace.query, pass the required trace_id, and pass the selected workspace_uuid values as workspace_uuids; when omitted or passed as an empty array, only the current workspace is queried.
4. For additional filtering, use a where_clause without outer curly braces, and do not add the trace_id condition again. Do not fall back to owl.data.simple_query for cross-workspace Trace queries.

Note Management Questions¶

Applies to questions such as "Search, read, create, modify, or delete notes".

1. Use exec_tool to call owl.nbook_note.list to search notes and obtain note_uuid.
2. When the Markdown body needs to be read, call owl.nbook_note.get.
3. Call owl.nbook_note.add to create a note, and owl.nbook_note.modify to update one.
4. Call owl.nbook_note.delete to delete a note. add, modify, and delete are write tools and should be manually confirmed by the client before execution.

Monitor Management Questions¶

Applies to questions such as "Query monitors, create or update monitors, and send external events".

1. Use exec_tool to call owl.monitor.list to query monitors.
2. Based on the rule_uuid in the returned result, use exec_tool to call owl.monitor.get to view monitor details.
3. To create or update a monitor, use exec_tool to call owl.monitor.upsert.
4. To send an external event, use exec_tool to call owl.monitor.receive.