Check connectivity and authentication to the ServiceNow instance.

Call this tool at the start of any workflow to verify that:

1. ServiceNow credentials are configured

2. The instance is reachable

3. The authenticated user has valid access

Returns the instance URL, authenticated username, and directly-assigned roles (inherited roles are not included). No parameters required.

Returns: JSON object with "connected" (bool), "instance_url", "authenticated_as", and "roles" (list of directly-assigned role names), or an error if connection fails.

TEMPORARY diagnostic tool. Probe any ServiceNow table to check access.

Note: This is a diagnostic tool intended for troubleshooting only. Table names are validated and dangerous query patterns (javascript:, gs.*, eval) are blocked before the request is sent.

Args: table: Table to probe (e.g. sys_hub_step_instance). query: Optional encoded query filter. limit: Max records to return (default 3).

Search CMDB configuration items with structured filters.

Builds an encoded query from the provided parameters and returns matching CIs. Name filtering uses STARTSWITH by default for performance (indexed operation).

Examples: search_cis(ci_class="cmdb_ci_linux_server", operational_status="1") search_cis(ci_class="cmdb_ci_win_server", name_filter="prod", display_value="true") search_cis(ci_class="cmdb_ci_server", location="New York", limit=50) search_cis(ci_class="cmdb_ci_server", display_value="all") # both sys_id and display name per reference field

Typical workflow: suggest_table → search_cis → get_ci_details → get_ci_relationships

Args: ci_class: CMDB table/class to query (e.g. cmdb_ci_server, cmdb_ci_linux_server). Defaults to cmdb_ci (all CI types). name_filter: Filter CIs whose name starts with this value. Leave empty for no name filter. operational_status: Filter by operational status numeric code. Valid values: "1" = Operational, "2" = Non-Operational, "3" = Repair in Progress, "4" = DR Standby, "5" = Ready, "6" = Retired, "7" = Pipeline, "8" = Catalog. os_filter: Filter by operating system (STARTSWITH match on the os field). location: Filter by location display value (STARTSWITH match). limit: Maximum number of results to return (1-1000, default 25). offset: Pagination offset for retrieving subsequent pages of results. fields: Specific fields to return. Defaults to sys_id, name, sys_class_name, operational_status, ip_address, location, sys_updated_on. display_value: Controls how reference fields (location, company, assigned_to, etc.) are returned. "" (default) returns raw sys_id values. "true" returns human-readable display values (e.g. "New York" instead of a sys_id). "all" returns both as {"value": sys_id, "display_value": "New York"}. Use "true" when presenting data to users; use "all" when you need both the sys_id (for API calls) and the display name.

Returns: JSON object with "count" (results on this page), "records" (list of CI dicts), "total_count", "has_more", "next_offset", and "suggested_next". When display_value="all", each reference field in a record is returned as {"value": sys_id, "display_value": label} instead of a plain sys_id string.

Execute a raw encoded query against any CMDB table.

For advanced users who know ServiceNow encoded query syntax. The query is passed directly to the Table API's sysparm_query parameter without modification.

Note: Server-side script expressions (javascript:, gs.*, eval) are blocked for security. Use field-based operators only.

Examples of encoded queries: "nameSTARTSWITHweb^operational_status=1" — operational CIs starting with "web" "sys_class_name=cmdb_ci_linux_server^ip_addressISNOTEMPTY" — Linux servers with IPs "sys_updated_onRELATIVEGT@dayofweek@ago@90" — CIs updated in the last 90 days "assigned_to.nameLIKESmith^ORmanaged_by.nameLIKESmith" — CIs assigned to or managed by someone named Smith "install_status=1^operational_status=1^sys_class_nameINcmdb_ci_linux_server,cmdb_ci_win_server" — installed and operational servers "sys_updated_on<2025-01-01" — CIs not updated since a specific date

Args: table: ServiceNow table name (e.g. cmdb_ci, cmdb_ci_server, cmdb_ci_win_server). encoded_query: Raw ServiceNow encoded query string. fields: Specific fields to return. Defaults to sys_id, name, sys_class_name, operational_status, ip_address, location, sys_updated_on. limit: Maximum number of results to return (1-1000, default 25). offset: Pagination offset for retrieving subsequent pages. display_value: Controls how reference fields (location, company, assigned_to, etc.) are returned. "" (default) returns raw sys_id values. "true" returns human-readable display values (e.g. "New York" instead of a sys_id). "all" returns both as {"value": sys_id, "display_value": "New York"}. Use "true" when presenting data to users; use "all" when you need both the sys_id (for API calls) and the display name.

Returns: JSON object with "count" (results on this page), "records" (list of CI dicts), "total_count", "has_more", "next_offset", and "suggested_next". When display_value="all", each reference field in a record is returned as {"value": sys_id, "display_value": label} instead of a plain sys_id string.

Get the full details of a single configuration item by its sys_id.

Returns all requested fields for the CI. If no fields are specified, returns a broad set of common CI attributes. Use this tool when you need complete information about a specific CI, such as after finding it via search_cis.

Prerequisites: Use search_cis or query_cis_raw to find the sys_id first. This tool only accepts sys_id (a 32-character hex identifier), not CI names. To look up a CI by name: search_cis(name_filter="my-server") → use the returned sys_id.

Examples: get_ci_details(sys_id="abc123...", table="cmdb_ci_server") get_ci_details(sys_id="abc123...", table="cmdb_ci_linux_server", display_value="true") get_ci_details(sys_id="abc123...", fields=["name", "ip_address", "os", "os_version"])

Args: sys_id: The 32-character sys_id of the CI record (from search_cis or query_cis_raw). table: The CMDB table the CI belongs to (e.g. cmdb_ci_server). Defaults to cmdb_ci. Using the specific class table is more efficient and returns class-specific fields. fields: Specific fields to return. If omitted, returns a broad default set including sys_id, name, sys_class_name, asset_tag, serial_number, ip_address, operational_status, install_status, location, department, company, os, os_version, cpu_count, ram, disk_space, discovery_source, first_discovered, last_discovered, sys_created_on, sys_updated_on. display_value: Controls how reference fields (location, company, assigned_to, etc.) are returned. "" (default) returns raw sys_id values. "true" returns human-readable display values (e.g. "New York" instead of a sys_id). "all" returns both as {"value": sys_id, "display_value": "New York"}. Use "true" when presenting data to users; use "all" when you need both the sys_id (for API calls) and the display name.

Returns: JSON object with the CI record fields, plus a "url" field linking to the ServiceNow record, or a NotFoundError if the sys_id does not exist. When display_value="all", each reference field is returned as {"value": sys_id, "display_value": label} instead of a plain sys_id string.

Count configuration items matching a query using the Aggregate API.

Uses the ServiceNow Stats API (/api/now/stats) for efficient counting without fetching actual records. Optionally group results by a field to get counts per value.

Examples: count_cis(table="cmdb_ci_server", group_by="operational_status") count_cis(table="cmdb_ci", group_by="sys_class_name") count_cis(table="cmdb_ci_linux_server", encoded_query="os=Linux Red Hat")

Args: table: CMDB table to count records in (e.g. cmdb_ci_server). Defaults to cmdb_ci. encoded_query: Optional encoded query to filter which CIs to count. Example: "operational_status=1" to count only operational CIs. group_by: Optional field name to group counts by (e.g. "sys_class_name" to get counts per CI type, or "operational_status" for counts per status).

Returns: JSON object with the aggregate count result. When group_by is used, returns counts broken down by each distinct value of that field.

List available CMDB classes from the Data Model Navigator.

Returns the class hierarchy under a given parent class. Results are cached for 1 hour to avoid repeated queries to the sys_db_object table.

Use this tool to discover which CI classes exist in the instance before running queries, or to explore the CMDB class hierarchy.

Args: parent_class: Parent class to list children of. Defaults to cmdb_ci (all CMDB classes). Use a more specific parent like cmdb_ci_server to see only server subclasses. limit: Maximum number of classes to return (default 100). offset: Pagination offset for retrieving subsequent pages of results.

Returns: JSON object with "count" and "classes" (list of class dicts with name, label, parent class, and whether the class has children).

Note: offset-based pagination may shift if classes are added or removed between calls. For stable enumeration, fetch all classes in a single call with a higher limit.

Get field definitions, descriptions, and suggested relationships for a CMDB class.

Queries the sys_dictionary table for field metadata and cmdb_rel_type_suggest for relationship suggestions. Includes inherited fields from parent classes by walking the class hierarchy. Results are cached for 1 hour.

Use this tool to understand the schema of a CI class before building queries, or to check what fields and relationships are available.

Prerequisites: Use list_ci_classes to find available class names, or suggest_table to find the right class.

Args: class_name: The CMDB class name to describe (e.g. cmdb_ci_server, cmdb_ci_linux_server). summary: If True (default), return only field_count, mandatory_fields (names only), and suggested_relationships — much lighter for initial exploration. Set False to include the full fields list with all metadata.

Returns: JSON object with "class_name", "field_count", and either a summary or the full "fields" list, plus "suggested_relationships".

Suggest the best CMDB table to query based on a natural language description.

Given a description like "linux servers", "network switches", "web applications", or "load balancers", this tool searches the CMDB class hierarchy to find the most appropriate table. It queries sys_db_object and sys_documentation for class labels and descriptions to find the best match.

Use this tool when you're unsure which CMDB table to query for a particular type of configuration item.

Each suggestion includes a confidence score (0-100) indicating how well it matches the description. When a single result clearly dominates, it is marked as best_match.

Examples: suggest_table(description="linux servers") → cmdb_ci_linux_server suggest_table(description="network switches") → cmdb_ci_netgear suggest_table(description="web applications") → cmdb_ci_appl Vague descriptions like "stuff" or "things" will return low-confidence matches.

Args: description: Natural language description of what you're looking for. Examples: "linux servers", "network switches", "web applications", "database instances", "storage devices", "virtual machines". limit: Maximum number of suggestions to return (1-1000, default 10). offset: Pagination offset for retrieving subsequent pages of suggestions.

Returns: JSON object with "suggestions" — a ranked list of matching CMDB tables with their name, label, confidence score, and pagination metadata.

Get all relationships for a configuration item.

Returns upstream (CIs this CI depends on), downstream (CIs that depend on this CI), or both. Each relationship includes the related CI's name, class, and operational status, plus the relationship type descriptor.

In ServiceNow CMDB relationships:

• Upstream: this CI is the CHILD in the relationship (e.g., "Runs on" a server)

• Downstream: this CI is the PARENT (e.g., a server that other CIs "Run on")

Prerequisites: Use search_cis to find the CI sys_id first. This tool only accepts sys_id (a 32-character hex identifier), not CI names. To look up a CI by name: search_cis(name_filter="my-server") → use the returned sys_id.

Examples: get_ci_relationships(ci_sys_id="abc123...", direction="downstream", limit=10) get_ci_relationships(ci_sys_id="abc123...", direction="upstream") get_ci_relationships(ci_sys_id="abc123...", direction="both", limit=50)

Args: ci_sys_id: The 32-character sys_id of the CI (from search_cis or query_cis_raw). direction: Which relationships to return: "upstream", "downstream", or "both". Defaults to "both". limit: Maximum relationships to return per direction (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "ci_sys_id", "direction", "count", and "relationships" list.

Walk the dependency tree from a CI with configurable depth and direction.

Recursively traverses relationships to build a tree of dependencies. Useful for understanding the full dependency chain of a CI — what it runs on, what runs on it.

Prerequisites: Use search_cis to find the root CI sys_id first.

Performance: API calls grow exponentially with max_depth — depth=3 with limit_per_level=10 can issue up to ~111 calls. Start with max_depth=2 and increase only if needed. Reduce limit_per_level for wide graphs. A hard 60-second timeout applies; on timeout only the root node is returned (in-progress subtrees are discarded) with timed_out=true.

Examples: get_dependency_tree(ci_sys_id="abc123...", direction="downstream", max_depth=2) get_dependency_tree(ci_sys_id="abc123...", class_filter=["cmdb_ci_linux_server", "cmdb_ci_win_server"]) get_dependency_tree(ci_sys_id="abc123...", format="ascii_tree", max_depth=3)

Args: ci_sys_id: The sys_id of the starting CI (32-character hex string from search_cis). direction: Direction to traverse: "upstream" (what this CI depends on) or "downstream" (what depends on this CI). Defaults to "upstream". max_depth: How many levels deep to traverse (1-5, default 3). Higher values make more API calls. Capped at 5 to prevent runaway traversals. limit_per_level: Maximum CIs to follow at each level (default 10). Controls breadth of the tree to avoid excessive API calls. class_filter: Optional list of sys_class_name values to include in the tree. Only CIs matching these classes appear in the output. CIs that don't match are still traversed (their children may match), but they are collapsed out of the result. When None or empty, all classes are included. Example: ["cmdb_ci_server", "cmdb_ci_linux_server"]. format: Output format. "json" (default) returns the nested tree structure. "ascii_tree" returns a pre-rendered text tree — much smaller, readable without post-processing, but loses sys_id and status detail.

Returns: When format="json" (default): JSON object with "ci" (root CI), "direction", "max_depth", "nodes_visited", "tree" (nested children), and "suggested_next". When format="ascii_tree": the "tree" field is replaced by "tree_text" (pre-rendered ASCII string). Both shapes also include "class_filter" when applied, "timed_out" on deadline hit, and "is_partial" + "traversal_errors" if any nodes failed to resolve.

List all relationship types available in the ServiceNow instance.

Returns relationship types from cmdb_rel_type with their parent and child descriptors. For example, the "Runs on::Runs" type has parent_descriptor "Runs on" and child_descriptor "Runs". Results are cached for 1 hour.

Args: limit: Maximum number of relationship types to return (default 50). offset: Pagination offset for retrieving subsequent pages of results.

Returns: JSON object with "count" and "relationship_types" list containing sys_id, name, parent_descriptor, and child_descriptor for each type.

Typical workflow: list_relationship_types → find_related_cis(ci_sys_id, rel_type=sys_id)

Find CIs related to a given CI by a specific relationship type.

Filters relationships to only those matching the specified type. The rel_type can be a sys_id or a relationship type name (e.g., "Runs on::Runs"). If a name is provided, it is resolved to a sys_id first.

Args: ci_sys_id: The sys_id of the CI to find related CIs for. rel_type: Relationship type — either a sys_id or a name like "Runs on::Runs". direction: "upstream", "downstream", or "both". Defaults to "both". limit: Maximum results to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "ci_sys_id", "rel_type", "direction", "count", and "relationships" list.

Produce a summary of services and applications impacted by a given CI.

Traverses downstream relationships (CIs that depend on this CI) up to the specified depth, then categorizes the impacted CIs by class. Focuses on business-relevant classes: business applications, services, and application clusters. Also useful for blast radius analysis, change risk assessment, and understanding service dependencies before scheduled maintenance.

Use this tool for change impact assessment — understanding what would be affected if this CI goes down.

Prerequisites: Use search_cis to find the CI sys_id first.

Performance: Traversal can issue many API calls for deeply connected CIs. Consider using max_depth=2 for initial assessment, then increasing if needed. A hard 60-second timeout applies; on timeout, impact counts reflect only what was traversed before the deadline (timed_out=true).

Examples: get_impact_summary(ci_sys_id="abc123...", max_depth=2) get_impact_summary(ci_sys_id="abc123...", class_filter=["cmdb_ci_server", "cmdb_ci_linux_server"]) get_impact_summary(ci_sys_id="abc123...", max_depth=3)

Args: ci_sys_id: The sys_id of the CI to assess impact for (32-character hex string from search_cis). max_depth: How deep to traverse downstream dependencies (1-5, default 3). class_filter: Optional list of sys_class_name values to include in impact counts and results. Traversal still visits all CIs (to find matching descendants), but only matching classes appear in totals and lists. When None or empty, all classes are included.

Returns: JSON object with "ci" (the source CI), "total_impacted" count, "impacted_by_class" (breakdown by CI class), and "impacted_services" (list of business apps/services found in the tree).

Find the shortest relationship path between two CIs.

Performs a bidirectional BFS (both upstream and downstream at each hop) to find the shortest chain of relationships connecting two CIs. Useful when you know both endpoints and want to understand how they are related without traversing the full tree.

Prerequisites: Use search_cis to find both CI sys_ids first.

Performance: BFS explores breadth-first with a limit of 10 relationships per node per direction. A hard 60-second timeout applies.

Examples: find_ci_path(source_sys_id="abc123...", target_sys_id="def456...") find_ci_path(source_sys_id="abc123...", target_sys_id="def456...", max_depth=3) find_ci_path(source_sys_id="abc123...", target_sys_id="def456...", max_depth=8)

Args: source_sys_id: The sys_id of the starting CI. target_sys_id: The sys_id of the target CI to find a path to. max_depth: Maximum hops to search (1-10, default 5). Higher values find longer paths but issue more API calls.

Returns: JSON object with "found" (bool), "hops" (number of relationships in the path), "path" (ordered list of nodes from source to target, each with "ci" details and "relationship_type"), "nodes_visited" (BFS cost indicator), and "suggested_next". When not found, also includes "max_depth_searched". When the BFS deadline is hit, also includes "timed_out": true and a "message".

Find CIs that have no relationships in cmdb_rel_ci.

Orphan CIs are configuration items with zero upstream or downstream relationships (also called unlinked, isolated, or disconnected CIs). These often indicate incomplete discovery, manual entries that were never linked, or leftover records from decommissioned infrastructure.

Scans a batch of CIs and checks each against cmdb_rel_ci using IN-batch queries. Results may be partial if the orphan ratio is low — use scan_offset to continue scanning from where the previous call left off.

Performance: This tool issues multiple API calls per batch (fetches CIs, then checks parent and child relationships for batches of up to 100 CIs). Use cmdb_health_summary for a quick count without record-level detail. Narrow scope with ci_class or operational_status to reduce scan cost.

Examples: find_orphan_cis(ci_class="cmdb_ci_server", operational_status="1") find_orphan_cis(ci_class="cmdb_ci_linux_server", limit=50) find_orphan_cis(ci_class="cmdb_ci", scan_offset=100) # continue scanning

Args: ci_class: CMDB table to search for orphans (e.g. cmdb_ci_server). Defaults to cmdb_ci (all types). operational_status: Optional filter by operational status (e.g. "1" for Operational). limit: Maximum orphan CIs to return (1-1000, default 25). scan_offset: Offset into the CI table to start scanning from. Use the "next_offset" value from a previous response to continue.

Returns: JSON object with "ci_class", "count", "orphan_cis" list, "total_scanned" (CIs checked), "has_more", and "next_offset" (for continuation).

Find CIs that share the same value for a given field within a class.

Identifies potential duplicates by grouping CIs on a field (typically name or serial_number) and returning groups with more than one record. Useful for finding CIs that may have been created by multiple discovery sources or manual entry.

Examples: find_duplicate_cis(ci_class="cmdb_ci_server", match_field="name") find_duplicate_cis(ci_class="cmdb_ci_server", match_field="serial_number") find_duplicate_cis(ci_class="cmdb_ci_server", match_field="ip_address", name_filter="prod")

Args: ci_class: CMDB table to search (e.g. cmdb_ci_server). Defaults to cmdb_ci. match_field: Field to match duplicates on. Defaults to "name". Common choices: "name", "serial_number", "asset_tag", "ip_address". name_filter: Optional STARTSWITH filter on the name field to narrow scope. limit: Maximum duplicate groups to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "ci_class", "match_field", "count", "total_count", "has_more", "next_offset", and "duplicate_groups" (list of groups, each with the shared value and matching CIs).

Find CIs that have not been updated within a specified number of days.

Stale CIs are records whose sys_updated_on timestamp is older than the threshold. Filtering to operational CIs (status=1) by default highlights records that claim to be active but haven't been refreshed — often a sign of broken discovery or decommissioned assets.

Examples: find_stale_cis(ci_class="cmdb_ci_server", days=90, operational_status="1") find_stale_cis(ci_class="cmdb_ci_linux_server", days=30) find_stale_cis(ci_class="cmdb_ci", days=180, operational_status="") # all statuses

Args: ci_class: CMDB table to search (e.g. cmdb_ci_server). Defaults to cmdb_ci. days: Number of days since last update to consider stale (default 90). Must be between 1 and 3650. operational_status: Filter by operational status. Defaults to "1" (Operational). Set to empty string to include all statuses. limit: Maximum stale CIs to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "ci_class", "stale_days", "count", "total_count", "has_more", "next_offset", and "stale_cis" list ordered by sys_updated_on ascending (most stale first).

Produce an overall CMDB health summary with key metrics.

Aggregates several health indicators into a single overview:

• Total CI count and breakdown by operational status

• Count of stale CIs (not updated in N days)

• Count of CIs missing key fields (name, sys_class_name)

• Breakdown by discovery source

This is an efficient summary using only Aggregate API calls — no record fetches. Use the specific tools (find_orphan_cis, find_duplicate_cis, find_stale_cis) for detailed record-level results.

Args: ci_class: CMDB table to summarize (e.g. cmdb_ci_server). Defaults to cmdb_ci. stale_days: Number of days threshold for staleness (default 90).

Returns: JSON object with "ci_class", "total_count", "by_operational_status", "stale_count", "missing_name_count", and "by_discovery_source".

Preview changes to an existing CI before applying them.

Fetches the current record, computes a diff against the proposed changes, and returns a confirmation token. No changes are made to ServiceNow.

The confirmation token is valid for 5 minutes. Pass it to confirm_ci_update to execute the change.

Prerequisites: Use search_cis or get_ci_details to find the CI sys_id first.

Typical workflow: preview_ci_update → review diff → confirm_ci_update

Examples: preview_ci_update(sys_id="abc123...", table="cmdb_ci_server", fields={ "operational_status": "6" }) # Retire a server preview_ci_update(sys_id="abc123...", table="cmdb_ci_server", fields={ "ip_address": "10.0.2.10", "short_description": "Moved to new subnet" }) preview_ci_update(sys_id="abc123...", table="cmdb_ci_linux_server", fields={ "install_status": "7", "operational_status": "2" }) # Mark as decommissioned

Args: sys_id: The sys_id of the CI to update. table: The CMDB table (e.g. cmdb_ci_server). Must be the specific class table. fields: Dictionary of field names to new values. Example: {"operational_status": "2", "install_status": "7"}. System fields (sys_id, sys_created_on, etc.) cannot be set.

Returns: JSON object with "token" (confirmation token), "sys_id", "table", "diff" (list of field changes with old/new values), and "fields" (proposed values).

Execute a previously previewed CI update.

Prerequisites: You MUST call preview_ci_update first and use the token from its response.

Requires the confirmation token returned by preview_ci_update. The token is single-use and expires after 5 minutes.

Args: token: The confirmation token from preview_ci_update.

Returns: JSON object with "success", "sys_id", "table", and the "updated_record".

Preview the creation of a new CI before inserting it.

Validates the fields and returns a confirmation token. No record is created in ServiceNow until confirm_ci_create is called.

The confirmation token is valid for 5 minutes.

Prerequisites: Call describe_ci_class(table) first to review mandatory fields and valid values before composing the fields dict. Call suggest_table if you are unsure of the correct table name.

Typical workflow: suggest_table → describe_ci_class → preview_ci_create → confirm_ci_create

Examples: preview_ci_create(table="cmdb_ci_server", fields={ "name": "web-server-01", "ip_address": "10.0.1.5", "operational_status": "1", "os": "Linux Red Hat" }) preview_ci_create(table="cmdb_ci_appl", fields={ "name": "MyApp", "operational_status": "1" }) preview_ci_create(table="cmdb_ci_linux_server", fields={ "name": "db-primary-01", "ip_address": "10.10.5.20", "os": "Linux Red Hat", "install_status": "1", "operational_status": "1" })

Args: table: The CMDB table to create the CI in (e.g. cmdb_ci_server). fields: Dictionary of field names to values. Must include at minimum a "name" field. Example: {"name": "web-server-01", "ip_address": "10.0.1.5", "operational_status": "1"}. System fields (sys_id, sys_created_on, etc.) cannot be set.

Returns: JSON object with "token" (confirmation token), "table", "fields" (the values to be created), and a human-readable message.

Execute a previously previewed CI creation.

Prerequisites: You MUST call preview_ci_create first and use the token from its response.

Requires the confirmation token returned by preview_ci_create. The token is single-use and expires after 5 minutes.

Args: token: The confirmation token from preview_ci_create.

Returns: JSON object with "success", "sys_id" (of the new CI), "table", and the "created_record".

Get business rules configured on a CMDB table.

Returns server-side business rules that fire on insert, update, delete, or query for the specified table. Script bodies are redacted for credentials.

Args: table: The CMDB table to inspect (e.g. cmdb_ci_server, cmdb_ci). active_only: If True, return only active rules. Defaults to True. include_scripts: If True, include full (redacted) script bodies. Defaults to False for token efficiency — set True when you need to review logic. limit: Maximum rules to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "table", "count", "total_count", "has_more", "next_offset", and "business_rules" list containing name, when, operations, order, condition, and optionally the redacted script body.

Get client scripts configured on a CMDB table.

Returns UI-side scripts (onChange, onLoad, onSubmit, onCellEdit) for the specified table. Script bodies are redacted for credentials.

Args: table: The CMDB table to inspect (e.g. cmdb_ci_server). active_only: If True, return only active scripts. Defaults to True. include_scripts: If True, include full (redacted) script bodies. Defaults to False for token efficiency — set True when you need to review logic. limit: Maximum scripts to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "table", "count", "total_count", "has_more", "next_offset", and "client_scripts" list containing name, type, field_name, and optionally the redacted script body.

Get Flow Designer flows related to a CMDB table or matching a name.

Searches sys_hub_flow by internal_name (CONTAINS table) and/or display name (CONTAINS name_filter). At least one of table or name_filter must be provided. Note: flow trigger/action details are stored in sub-tables, so this provides an overview — use the ServiceNow UI for full flow logic.

Examples: get_flows(table="cmdb_ci_server") get_flows(name_filter="decommission") get_flows(name_filter="Payroll", active_only=False)

Args: table: Filter flows whose internal_name contains this value (e.g. cmdb_ci_server). Optional if name_filter is provided. name_filter: Filter flows whose display name contains this value (e.g. "decommission", "Payroll"). Optional if table is provided. active_only: If True, return only active flows. Defaults to True. limit: Maximum flows to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "count", "total_count", "has_more", "next_offset", "suggested_next", and "flows" list containing sys_id, name, internal_name, description, active, and run_as. Also echoes "table" and/or "name_filter" when those parameters were provided.

Get detailed logic of a Flow Designer flow by sys_id.

Fetches the flow definition from sys_hub_flow_base and parses the label_cache to extract trigger, steps, referenced tables, and data flow. Use get_flows to find the flow sys_id first.

Prerequisites: Use get_flows(name_filter="...") to find the flow sys_id.

Examples: get_flow_details(sys_id="abc123...") get_flow_details(sys_id="abc123...", include_step_details=True)

Args: sys_id: The sys_id of the flow (from get_flows results). include_step_details: If True, fetches and decodes step-level configuration from sys_hub_flow_logic_instance_v2 and sys_hub_step_instance. Shows actual inputs, outputs, and conditions for each step. Requires fd_read role. Defaults to False for efficiency.

Returns: JSON object with flow metadata (sys_id, name, internal_name, description, active, status, run_as, type, sys_scope, sys_created_by, sys_updated_on), "steps" and "step_count" parsed from label_cache, and "suggested_next" guidance. When include_step_details=True, also includes "detailed_steps" (with decoded inputs, outputs, conditions, variables per step) and "detailed_step_count".

Get ACL rules governing access to a CMDB table.

Returns access control list entries from sys_security_acl for the specified table. Shows which roles can read, write, create, or delete records. Script conditions are redacted for credentials.

Args: table: The CMDB table to inspect (e.g. cmdb_ci_server). active_only: If True, return only active ACLs. Defaults to True. include_scripts: If True, include full (redacted) script bodies. Defaults to False for token efficiency — set True when you need to review logic. limit: Maximum ACLs to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "table", "count", "total_count", "has_more", "next_offset", and "acls" list containing name, operation, type, admin_overrides, condition, and optionally the redacted script body.

Get script includes matching a name filter.

Script includes are reusable server-side JavaScript classes and functions. Unlike business rules, they are not tied to a specific table — they are global utilities callable from any server-side script.

Use this to find utility classes referenced by business rules, flows, or other scripts (e.g., searching for "CMDB" to find CMDB-related utilities).

Examples: get_script_includes(name_filter="CMDB") get_script_includes(name_filter="DecommissionUtils", include_scripts=True) get_script_includes(name_filter="Util", active_only=False, limit=50)

Args: name_filter: Filter script includes whose name contains this value (case-insensitive LIKE match). When empty, returns all script includes up to the limit. active_only: If True, return only active script includes. Defaults to True. include_scripts: If True, include full (redacted) script bodies. Defaults to False for token efficiency — set True when you need to review logic. limit: Maximum script includes to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "count", "total_count", "has_more", "next_offset", and "script_includes" list containing name, api_name, description, active, client_callable, access, and optionally the redacted script body.

Produce a summary of all configurables for a CMDB table.

Counts business rules, client scripts, flows, ACLs, and script includes for the given table in a single overview. Uses the Aggregate API for efficient counting where possible, falling back to limited record fetches.

Use this for a quick audit of what automation and access controls exist on a table before making changes.

Args: table: The CMDB table to analyze (e.g. cmdb_ci_server).

Returns: JSON object with "table" and counts for each configurable type: "business_rules", "client_scripts", "flows", "acls", "script_includes", each with "active_count" and "total_count".

List Discovery schedules configured in the instance.

Returns discovery schedules from the discovery_schedule table, showing schedule name, status, frequency, and which IP ranges or CI groups are targeted. Use this to understand what automated discovery is running and when.

Args: active_only: If True, return only active schedules. Defaults to True. limit: Maximum schedules to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "count" and "schedules" list containing name, active status, discover, frequency, and run_as.

Get recent Discovery status records showing scan results.

Queries the discovery_status table for recent discovery runs. Each record represents a single discovery scan attempt against a target, showing whether it succeeded, failed, or is in progress.

Args: schedule_name: Filter by schedule name (STARTSWITH match). Optional. state: Filter by discovery state. Valid values: "Starting", "Active", "Completed", "Cancelled", "Error". Optional. limit: Maximum records to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "count" and "statuses" list containing sys_id, state, source, target IP, CI created/updated info, and timestamps.

Get recent Discovery error and warning log entries.

Queries the discovery_log table for error/warning entries from recent discovery runs. Use this to diagnose why CIs are not being discovered or updated correctly.

Args: severity: Filter by severity level. Defaults to "Error". Set to "" (empty string) to return all severity levels. days: How far back to search in days (1-365, default 7). limit: Maximum log entries to return (1-1000, default 25). offset: Pagination offset. max_message_length: Truncate message fields longer than this (default 500). Set to 0 to return full messages. Truncated messages include a message_length field with the original character count.

Returns: JSON object with "count", "days_back", and "errors" list containing sys_id, level, message, source, CI reference, and timestamp.

Get CMDB Identification and Reconciliation Engine (IRE) identification rules.

Identification rules define how incoming data is matched to existing CIs. Each rule specifies which fields (identifiers) are used to uniquely identify a CI of a given class. When discovery or import finds a CI, these rules determine whether to create a new record or update an existing one.

Args: table: Filter by CI class table name (e.g. cmdb_ci_server). Optional — omit to list rules for all classes. active_only: If True, return only active rules. Defaults to True. limit: Maximum rules to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "count" and "identification_rules" list containing name, applies_to table, identifier fields, priority, and active status.

Get CMDB IRE reconciliation (data refresh) rules.

Reconciliation rules control how field values are updated when multiple data sources provide conflicting values for the same CI. They define source priorities and which source "wins" for each field, preventing lower-priority sources from overwriting authoritative data.

Args: table: Filter by CI class table name (e.g. cmdb_ci_server). Optional — omit to list rules for all classes. active_only: If True, return only active rules. Defaults to True. limit: Maximum rules to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "count" and "reconciliation_rules" list containing name, applies_to table, source, priority, attributes, and active status.

Explain why two CIs might be duplicates by comparing their identification fields.

Fetches both CIs and the identification rules for their class, then compares the identifier fields side-by-side. This helps determine whether two CIs are true duplicates or false positives, and which identification rule matched (or failed to match).

Prerequisites: Use find_duplicate_cis to identify the duplicate pair first.

Example: explain_duplicate(sys_id_a="abc123...", sys_id_b="def456...", table="cmdb_ci_server")

Args: sys_id_a: sys_id of the first CI. sys_id_b: sys_id of the second CI. table: The CMDB table both CIs belong to (default cmdb_ci).

Returns: JSON object with both CIs' key fields, the applicable identification rules, and a field-by-field comparison showing matches and mismatches.

List configured import data sources.

Data sources define where external data comes from (JDBC, LDAP, file, REST, etc.) and which import set table it lands in. Use this to understand what feeds data into the CMDB.

Args: target_table: Filter by target table name (e.g. cmdb_ci_server). Optional. active_only: If True, return only active data sources. Defaults to True. limit: Maximum data sources to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "count" and "data_sources" list containing name, import_set_table, type, target_table, active status, and last run timestamp.

Get recent import set run records.

Each import set run represents a batch of data loaded into a staging table. Shows whether the import completed, how many rows were processed, and any errors encountered.

Args: table_name: Filter by import set table name (STARTSWITH match). Optional. state: Filter by run state. Common values include "Loaded", "Processed", "Error", "Complete", "Complete with errors", "Cancelled". Values may vary by instance configuration. Optional. days: How far back to search in days (1-365, default 7). limit: Maximum runs to return (1-1000, default 25). offset: Pagination offset.

Returns: JSON object with "count", "days_back", and "import_set_runs" list containing sys_id, table_name, state, row counts, and timestamps.

Get recent transform map errors from import set processing.

Transform maps control how staging table rows are mapped to target CMDB tables. This tool returns rows that failed during transformation, showing the error message and which source/target records were involved.

Args: target_table: Filter by target table name (e.g. cmdb_ci_server). Optional. days: How far back to search in days (1-365, default 7). limit: Maximum errors to return (1-1000, default 25). offset: Pagination offset. max_error_length: Truncate error_message fields longer than this (default 500). Set to 0 to return full messages. Truncated messages include an error_message_length field with the original character count.

Returns: JSON object with "count", "days_back", and "transform_errors" list containing sys_id, transform_map, target_table, error message, source and target records, and timestamp.

Clear the in-memory metadata cache, forcing fresh data on next access.

Clears all cached schema data including class hierarchies, field definitions, relationship types, and instance metadata. The next tool or resource access will re-fetch from ServiceNow automatically.

Use this after making schema changes in ServiceNow (e.g., adding fields, creating new CI classes, or modifying relationship types) to ensure the MCP server reflects the latest state.

Returns: JSON object confirming the cache was cleared.