Skip to main content
Glama
OT-AIops

OT-AIops

onboarding_config_draft

Read-only

[READ][risk=low] The config.yaml endpoints a stored scan can justify.

Instructions

[READ][risk=low] The config.yaml endpoints a stored scan can justify.

Closes the gap where a site scanned forty devices and then retyped all forty
by hand. Reads a stored scan; writes nothing. `config.yaml` is edited by a
person, exactly as with `iaiops tags apply`.

**Every drafted field says whether the scan established it.** A field with
`value: null` was NOT established, and its `caution` says what it is waiting
for — do not fill one in and do not drop it. Dropping it lets the protocol
default apply in silence, which is how a Modbus gateway gets read at unit 1
and shows a confident number for the wrong machine. Carry the cautions to
whoever merges this; they are the content, not decoration.

**Only CONFIRMED protocols become endpoints.** An open port means something
is listening, not that it speaks the protocol; those hosts appear under
`skipped` with the reason. `limits` states what this draft structurally
cannot contain — a protocol's absence here is not evidence of its absence at
the site.

`tags` is always empty and this tool will not fill it. A scan finds devices;
which point means run state or good count is process knowledge, and a wrong
production counter yields a plausible OEE, which is worse than an error
(D16). That confirmation is a person's, via `iaiops tags export` / `apply`.

`scan_id` empty means the newest stored scan. `db` overrides the store
(.db/.sqlite, under $IAIOPS_HOME, the config dir or an IAIOPS_AGENT_READ_DIRS dir).

Input Schema

NameRequiredDescriptionDefault
dbNo
scan_idNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.28.0

TDQS

A4.2/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description adds substantial beyond-annotation detail: only CONFIRMED protocols become endpoints, unconfirmed hosts land under `skipped` with reasons, `limits` enumerates what the draft structurally cannot contain, and null `value` fields carry `caution` messages that must be preserved. It also explains the downstream failure mode of silently applying protocol defaults, which is exactly the context an agent needs to not 'helpfully' fill gaps.

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

Conciseness3/5

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

The critical behavior (null values, confirmed-only protocols, tags always empty) is front-loaded and bolded, which is good structure. But it is padded with editorial asides — the Modbus unit-1 anecdote, the D16 OEE digression — that, while illustrative, cost length without changing the call decision.

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?

With no output schema, the description fully compensates by naming the response sections (`skipped`, `limits`, `tags`) and what each means, plus the semantics of null fields. For a read-only drafting tool with two optional params, an agent has everything needed to call it and interpret the result correctly.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must carry both parameters, and it does: empty `scan_id` selects the newest stored scan, and `db` overrides the store with accepted extensions and the search path ($IAIOPS_HOME, config dir, IAIOPS_AGENT_READ_DIRS). The only gap is that it never shows what a scan_id value looks like, leaving the agent to infer format from another tool's output.

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

Purpose4/5

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

The opening line states a specific resource (config.yaml endpoints) and its source (a stored scan), so an agent knows this generates a draft config rather than reading or writing live values. The phrasing 'the endpoints a stored scan can justify' is slightly abstract and needs the second paragraph's example to land fully, and it never names the closest sibling (onboarding_status) to differentiate itself explicitly.

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?

It clearly delineates the handoff boundary: drafting is automatic, but tag assignment must be done by a person via `iaiops tags export` / `apply`, and warns not to fill or drop null-valued fields. What it lacks is a statement of when in the onboarding workflow to call this versus onboarding_status or protocols_supported — the sequencing is implied rather than stated.

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