Skip to main content
Glama
industrial-aiops

OT-AIops

by industrial-aiops
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

uns_live_audit

Read-only

Capture a live MQTT topic sample and audit it for naming conformance and topic sprawl. Identifies governance issues from observed topics in a bounded capture window.

Instructions

[READ][risk=low] Capture the LIVE UNS topic tree (bounded) then audit it.

Closes the governance loop: subscribes to a live broker, collects up to
``max_msgs`` messages or until ``duration_s`` (whichever first), then runs the
naming-conformance + topic-sprawl audit over the observed topics. Never an
open-ended loop.

Args:
    endpoint: Endpoint name from config (protocol must be 'mqtt').
    topic: Topic filter to capture under (default '#').
    duration_s: Capture window in seconds (1..60, capped server-side).
    max_msgs: Max messages to capture (1..500, capped server-side).
    allowed_roots: Permitted top-level segments; others are flagged (optional).
    min_segments: Minimum namespace depth a well-formed topic must have.
    max_leaf_parents: A leaf under more than this many parents is scattered.

Returns dict: the uns_topic_audit result (topic_count, depth, verdict, findings)
    plus capture:{endpoint, topic, observed_messages, unique_topics, topics[]}
    and stored_for_onboard (False when the capture saw no topics).

Example: uns_live_audit(topic="factory/#", duration_s=8, allowed_roots=["factory"]).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
topicNo#
endpointNo
max_msgsNo
duration_sNo
min_segmentsNo
allowed_rootsNo
max_leaf_parentsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true and destructiveHint=false, and the description complements this with process-level details: it subscribes to a live broker, is bounded ('Never an open-ended loop'), caps duration_s and max_msgs server-side, and explains the stored_for_onboard false case. It also gives the full return structure, adding significant context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a one-line summary, a process paragraph, an Args list, Returns, and an Example. It is somewhat verbose but not excessive for a tool with 7 parameters and a rich return contract. Front-loading the purpose and safety note ('[READ][risk=low]') is effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (live subscription, audit logic, 7 params) and no output schema, the description provides everything an agent needs: return format, example invocation, parameter ranges, and an edge case (stored_for_onboard false). Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 0%, the description fully compensates. Every parameter is explained with type constraints and intent: endpoint requires the 'mqtt' protocol, duration_s is capped at 60, max_msgs at 500, allowed_roots flags unauthorized top-level segments, min_segments defines namespace depth, and max_leaf_parents describes scatterness. This is far more than the bare schema title.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it 'Capture[s] the LIVE UNS topic tree (bounded) then audit[s] it.' This specific verb-resource pair distinguishes it from static audit tools like uns_topic_audit, which likely only audit an existing tree without live capture. The scope and action are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description frames the tool as closing the governance loop and explains the capture+audit flow, so an agent can infer when to use it for live checks. However, it never explicitly names alternative tools like uns_topic_audit or states when not to use it, leaving some inference to the reader.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools