Tools

All tools except idrac_list take idrac (a registry name from the configuration) as their first argument. Tools marked destructive carry the MCP destructiveHint annotation — well-behaved clients prompt before running them.

This page is generated from the running server by scripts/gen-tools-reference.py; it cannot drift from the code.

Discovery & identity

idrac_list

read-only · idempotent

Full guidance (the docstring the LLM sees)

List all iDRACs in this server's registry.

ALWAYS call this first to discover which `idrac` name to pass to other
tools. Returns one entry per configured iDRAC with:
  - name (string handle, used in all other tool calls)
  - host (FQDN or IP)
  - user
  - cert_path (or null if cert verification isn't pinned)
  - description (free-text label)

Passwords are NEVER returned. Safe to share output broadly.
No network I/O — reads from the local registry config only.

idrac_ping

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes

Full guidance (the docstring the LLM sees)

Cheap reachability + auth check for one iDRAC.

Reads the unauthenticated Redfish service root, then opens and closes a
token session. Returns:
  - {ok: true, host, redfish_version, product, firmware, auth: "passed"}
    if the iDRAC is reachable AND accepts the configured credentials
  - {ok: false, host, error: "<msg>"} otherwise

Use BEFORE issuing destructive operations to confirm the box is actually
responsive. Note: repeated FAILED auth attempts count toward iDRAC's
IP-blocking lockout (default: 3 failures = 60s block) — if this returns
an auth error, fix credentials before retrying in a loop.

idrac_info

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes

Full guidance (the docstring the LLM sees)

One-shot summary of an iDRAC and its host server.

Returns: model, service_tag, serial, hostname, power_state, health,
bios_version, idrac_firmware, cpu summary (model/count/cores), memory_gib.

Good starting point for "what is this box?" or "is it on?" questions.
The service_tag is Dell's support identifier (Redfish `SKU` field) —
that's what Dell warranty/driver lookups want. For deeper inventory
(DIMM-level, per-drive), use idrac_inventory. For live telemetry, use
idrac_sensors.

idrac_health

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes

Full guidance (the docstring the LLM sees)

Health status per subsystem: system, processors, memory, storage
controllers, thermal, power, and the iDRAC itself.

Each value is the Redfish Status Health string ("OK", "Warning",
"Critical") or null when the subsystem doesn't report. `storage` is a
dict per controller.

If anything is non-OK, follow up with idrac_sel (recent hardware
events usually explain a Warning/Critical) and idrac_inventory (which
component exactly).

Degrades gracefully: if one subsystem's Redfish resource fails (e.g. a
box with no storage controller 404s on /Storage), that subsystem
reports its error string and the rest of the report survives.

idrac_get

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes
path	string	yes	Redfish resource path starting with /redfish/v1/. Supports OData query params like ?$top=10 or ?$expand=*($levels=1). See idrac://docs/redfish-map for a tree of useful paths.

Full guidance (the docstring the LLM sees)

Read any Redfish resource by path. Generic escape hatch for reads.

Prefer specific tools (idrac_info, idrac_sensors, idrac_inventory...)
when they exist — they return cleaner shapes. Use this when you need
something we haven't wrapped: NVMe details, license info, network
adapter firmware, Dell OEM extensions under /Oem/Dell/, etc.

Examples of useful paths (see idrac://docs/redfish-map for the map):
  /redfish/v1/Systems/System.Embedded.1            host identity + power
  /redfish/v1/Managers/iDRAC.Embedded.1            the iDRAC itself
  /redfish/v1/Chassis/System.Embedded.1/Thermal    temps + fans
  /redfish/v1/UpdateService/FirmwareInventory      firmware collection
  /redfish/v1/TaskService/Tasks                    running tasks
  /redfish/v1/Managers/iDRAC.Embedded.1/Oem/Dell/DellAttributes/iDRAC.Embedded.1

Responses can be large — prefer narrow paths over hierarchical $expand
on big collections.

Power & LED

idrac_power_status

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes

Full guidance (the docstring the LLM sees)

Read current power state.

Returns: {power_state, allowable_resets, operations}
  - power_state: "On" / "Off"
  - allowable_resets: raw Redfish ResetType values this firmware accepts
  - operations: the friendly verbs idrac_power takes, filtered to what
    this box supports

For changing state, use idrac_power.

idrac_power

destructive

Argument	Type	Required	Description
idrac	string	yes
operation	string	yes	Power operation. One of: ‘on’, ‘off’ (ACPI graceful), ‘off-hard’ (immediate), ‘cycle’ (full power cycle), ‘reset’ (hard reboot), ‘reset-graceful’ (OS-mediated reboot), ‘nmi’, ‘button’ (virtual power button press). ALL of these affect the HOST, not the iDRAC.

Full guidance (the docstring the LLM sees)

Issue a power command. DESTRUCTIVE — affects the host OS.

Operations:
  - `on`             turn host on (error if already on — check first)
  - `off`            ACPI graceful shutdown — the OS does the work
  - `off-hard`       IMMEDIATE power off — data loss possible
  - `cycle`          full power cycle (off + on); needs newer firmware,
                     falls back is NOT automatic — check
                     idrac_power_status operations list first
  - `reset`          hard reboot without OS involvement
  - `reset-graceful` OS-mediated reboot
  - `nmi`            non-maskable interrupt (kernel debugging/crash dump)
  - `button`         emulate pressing the physical power button

Use `reset` after idrac_vmedia_mount + boot override to boot new media
(or just use idrac_boot_to_iso which chains it all). DO NOT call this
without explicit user confirmation if the host runs production
workloads. `off` (graceful) is the safest destructive op.

Returns: {idrac, operation, reset_type, before, status: "issued"}.
State change is asynchronous — poll idrac_power_status after a few
seconds to confirm. To reboot the iDRAC ITSELF (not the host), use
idrac_get on the Manager.Reset action via the operations cookbook.

idrac_led

idempotent

Argument	Type	Required	Description
idrac	string	yes
state	string	yes	‘blink’ (identify), ‘on’, or ‘off’.

Full guidance (the docstring the LLM sees)

Control the front-panel identification LED (blue ID light).

The blue LED on the chassis lights/blinks so you can physically find
the box in a rack. Common workflow: state='blink', walk the rack, then
state='off'.

Tries the standard `IndicatorLED` PATCH first; iDRAC firmware 7.x
deprecated that field, so on rejection it falls back to the Chassis
`LocationIndicatorActive` property (which only knows on/off — 'blink'
and 'on' both map to active).

Idempotent and non-destructive.

Inventory & sensors

idrac_inventory

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes

Full guidance (the docstring the LLM sees)

Component-level hardware inventory.

Returns a dict with keys: cpus, dimms, storage (controllers with their
physical drives AND virtual disks / RAID volumes), nics, idrac_nic.
Each component carries the useful identifying fields (model, serial,
capacity, slot, health) rather than the full Redfish bodies.

Response can be large (24 DIMM slots on an R740). For just identity and
headline numbers, prefer idrac_info. For firmware versions, use
idrac_firmware.

Degrades gracefully: a subsystem whose collection fails (e.g. no
storage controller) reports its error under `errors` and the rest of
the inventory survives.

idrac_sensors

read-only

Argument	Type	Required	Description
idrac	string	yes

Full guidance (the docstring the LLM sees)

Read live thermal and power sensors.

Returns:
  - temperatures: [{name, celsius, health}] — inlet/exhaust/CPU temps
  - fans: [{name, rpm, health}]
  - power: {consumed_watts, capacity_watts, psus: [{name, model,
    capacity_watts, input_voltage, health}], voltages: count}

Use this for:
  - "Is this server actually doing work?" (consumed_watts vs idle)
  - Thermal monitoring (inlet temp is the one facility people care about)
  - Confirming both PSUs are healthy and fed

NOT idempotent — each call returns the current instant reading.
Reads the Chassis Thermal + Power resources (stable on every iDRAC9
firmware, unlike the newer per-sensor collection).

idrac_firmware

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes

Full guidance (the docstring the LLM sees)

List installed firmware versions for every updatable component.

Returns {installed: [{name, version, updateable}]} covering BIOS,
iDRAC, RAID controller, NICs, PSUs, drives, CPLD, etc.

The FirmwareInventory also contains "Previous-" (rollback) and
"Available-" entries; this tool filters to "Installed-" — what's
actually running. Use idrac_get on
/redfish/v1/UpdateService/FirmwareInventory if you need the rest.

Logs

idrac_sel

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes
limit	integer	default 50	How many of the newest entries to return.

Full guidance (the docstring the LLM sees)

Read the newest System Event Log entries (newest first).

The SEL is the HARDWARE event log: power events, ECC errors, PSU
failures, intrusion, thermal trips. This is the first place to look
when idrac_health shows Warning/Critical or a box misbehaves.

Severity values: "OK", "Warning", "Critical". A healthy quiet box shows
mostly power-on/off audit entries.

For firmware update history, config jobs, and iDRAC-internal events use
idrac_lclog instead (much noisier).

idrac_lclog

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes
limit	integer	default 50	How many of the newest entries to return.

Full guidance (the docstring the LLM sees)

Read the newest Lifecycle Controller log entries (newest first).

The LC log records iDRAC-side activity: config jobs, firmware updates,
user logins, SCP imports, license changes. It's the audit trail for
"who changed what, when" — and it's LARGE (thousands of entries on a
box that's been in service). Keep `limit` modest.

For hardware faults, idrac_sel is the better signal.

idrac_sel_clear

destructive · idempotent

Argument	Type	Required	Description
idrac	string	yes

Full guidance (the docstring the LLM sees)

Clear the System Event Log. DESTRUCTIVE — the history is gone.

Only do this deliberately (e.g., after resolving a hardware issue so
future alerts stand out, or before handing off refurbished hardware).
Consider capturing idrac_sel output first so the history is preserved
somewhere.

The Lifecycle Controller log is NOT touched (and records that the SEL
was cleared, so the action itself is auditable).

Virtual media & boot

idrac_vmedia_status

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes

Full guidance (the docstring the LLM sees)

List virtual media devices and what's mounted in them.

Returns one entry per device (virtual CD/DVD, virtual removable disk)
with: id, media_types, inserted, image (the mounted URL or null),
connected_via.

Use BEFORE idrac_vmedia_mount to see whether something is already
inserted (mounting over an existing image requires ejecting first).

idrac_vmedia_mount

Argument	Type	Required	Description
idrac	string	yes
image_url	string	yes	URL of the ISO/IMG. Schemes: http://, https://, nfs:// (nfs://host/path/file.iso), or CIFS as //host/share/file.iso. GOTCHA: an HTTPS URL served with a self-signed cert fails unless the iDRAC attribute RFS.1.IgnoreCertWarning is enabled — plain HTTP on the management LAN avoids the whole issue.
device	string	default cd	‘cd’ (virtual CD/DVD, for ISOs) or ‘removable’ (virtual USB/floppy, for IMGs).

Full guidance (the docstring the LLM sees)

Mount a remote ISO/IMG as virtual media on the host.

The host sees a USB-attached optical drive (or removable disk). Use
cases: OS install, live rescue image, firmware bootable ISO.

The iDRAC streams the image from your URL for as long as it's mounted —
the HTTP/NFS server must stay reachable for the whole install.

If the device already has an image inserted, this fails; call
idrac_vmedia_unmount first. To boot from the mounted ISO, follow with
idrac_boot_override target=Cd — or skip both and use idrac_boot_to_iso,
which chains mount + boot-once + reboot correctly.

Returns: {idrac, device, image_url, status}. Confirm with
idrac_vmedia_status (inserted=true, image=your URL).

idrac_vmedia_unmount

idempotent

Argument	Type	Required	Description
idrac	string	yes
device	string	default cd	‘cd’ or ‘removable’ — which virtual device to eject.

Full guidance (the docstring the LLM sees)

Eject the image from a virtual media device.

Safe operation: the host just sees the virtual disc ejected. If the
host OS is actively reading from it (mid-install!), it gets I/O errors,
so check where the install stands before ejecting.

Idempotent, honestly: an already-empty device (or firmware that errors
on an empty eject) reports success, and a claimed eject is verified by
reading the device back — "ejected" here means the device CONFIRMS no
media, not merely that the command was accepted.

idrac_boot_override

idempotent

Argument	Type	Required	Description
idrac	string	yes
target	string	yes	Boot device. One of [‘None’, ‘Pxe’, ‘Cd’, ‘Hdd’, ‘BiosSetup’, ‘Usb’, ‘SDCard’, ‘UefiTarget’, ‘Utilities’, ‘Diags’, ‘UefiHttp’]. ‘None’ + enabled=‘Disabled’ clears an override.
enabled	string	default Once	‘Once’ (next boot only), ‘Continuous’, or ‘Disabled’.

Full guidance (the docstring the LLM sees)

Set the standard Redfish boot-source override.

Takes effect at the next host boot — pair with idrac_power reset.

CAVEAT for ISO installs: target='Cd' points at the FIRST optical device
the BIOS enumerates, which on a box with a physical DVD drive may not
be the virtual one. For booting a mounted virtual ISO specifically,
prefer idrac_boot_to_iso — it uses Dell's OEM attribute that targets
the virtual CD unambiguously.

Common targets: Pxe (network install), BiosSetup (drop into F2 setup —
handy with the virtual console), Hdd, Cd, UefiHttp.

idrac_boot_to_iso

destructive

Argument	Type	Required	Description
idrac	string	yes
image_url	string	yes	URL of the bootable ISO (same rules as idrac_vmedia_mount).
reboot	boolean	default True	If true (default), immediately restarts the host to boot the ISO (ForceRestart if on, On if off). If false, everything is staged and the NEXT boot uses the ISO.

Full guidance (the docstring the LLM sees)

One-shot workflow: mount an ISO and boot the host from it.

DESTRUCTIVE when reboot=true — the host restarts immediately.

Steps performed, each VERIFIED by reading state back before the next
(a 2xx means "accepted", not "applied" — only read-back counts):
  1. Eject any image already in the virtual CD (verified empty)
  2. InsertMedia with your ISO URL (verified inserted)
  3. Set Dell OEM attributes ServerBoot.1.BootOnce=Enabled +
     ServerBoot.1.FirstBootDevice=VCD-DVD (verified by re-reading;
     targets the VIRTUAL CD specifically — the standard 'Cd' override
     can hit a physical drive instead)
  4. If reboot: ComputerSystem.Reset (ForceRestart, or On if the
     host was off)

After this, watch progress via idrac_console (virtual console URL) —
the ISO's installer takes over from there. The boot-once flag clears
itself after one boot; the ISO stays mounted until idrac_vmedia_unmount.

Returns per-step outcomes so a partial failure is obvious. If a step
fails, the error message carries the completed-steps ledger — the BMC
is then in a PARTIAL state (e.g. old media already ejected, new ISO
mounted, no boot override). Inspect with idrac_vmedia_status before
retrying; do NOT fall back to idrac_boot_override target=Cd.

BIOS, attributes, jobs & SCP

idrac_bios_get

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes
attribute	string	default ``	Optional case-insensitive substring filter, e.g. ‘boot’, ‘virtualization’, ‘ProcTurbo’. Empty returns everything (hundreds of attributes).

Full guidance (the docstring the LLM sees)

Read current BIOS attributes, plus any pending (staged) changes.

Returns {current: {...}, pending: {...}}. `pending` holds values PATCHed
to /Bios/Settings that haven't been applied by a reboot yet — non-empty
pending means a config job is probably queued (check idrac_jobs).

Attribute names are the Dell BIOS token names (e.g. LogicalProc,
BootMode, SysProfile). They're case-sensitive when WRITING — copy the
exact key from this output into idrac_bios_set.

idrac_bios_set

destructive

Argument	Type	Required	Description
idrac	string	yes
attributes	object	yes	Attribute name -> new value. Names AND enum values are case-sensitive — read the exact current spelling with idrac_bios_get first. Example: {“LogicalProc”: “Disabled”, “BootMode”: “Uefi”}.
reboot	boolean	default False	If true, immediately ForceRestart the host so the change applies now. If false (default), the change stages and applies at the NEXT reboot.

Full guidance (the docstring the LLM sees)

Stage BIOS attribute changes. They apply at reboot (Dell creates a
config job that runs during POST).

DESTRUCTIVE: wrong BIOS settings can make a host unbootable, and with
reboot=true the host restarts immediately.

Flow: PATCH lands in /Bios/Settings with ApplyTime=OnReset and the
iDRAC queues a job (JID returned here). On the next boot, POST runs the
job (adds a few minutes to boot time), then the new values show as
`current` in idrac_bios_get.

Poll the job with idrac_jobs job_id=<jid>. If the job fails (invalid
value, dependency conflict), the message in the job explains why —
Dell validates at APPLY time, not at PATCH time, so a 200 here does
not guarantee the value is valid.

idrac_attributes_get

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes
group	string	default idrac	‘idrac’ (network, users, IPMI, virtual console, RFS…), ‘system’ (chassis/server settings), or ‘lc’ (Lifecycle Controller settings).
filter	string	default ``	Optional case-insensitive substring filter on attribute name, e.g. ‘NIC.1’, ‘Users.2’, ‘RFS’, ‘SNMP’. Empty returns ALL (2000+ attributes for the idrac group — always filter).

Full guidance (the docstring the LLM sees)

Read Dell attributes (the racadm `get` namespace, over Redfish).

These are the grouped dotted attributes like NIC.1.DNSRacName,
Users.2.UserName, ServerBoot.1.FirstBootDevice, RFS.1.IgnoreCertWarning.
Unlike BIOS attributes, changes to these apply IMMEDIATELY (no reboot,
no job) via idrac_attributes_set.

Group 'idrac' is by far the biggest and most useful: network config,
user accounts, virtual-media/RFS behavior, SNMP/email alerting,
time/NTP, web-server and session settings.

idrac_attributes_set

destructive · idempotent

Argument	Type	Required	Description
idrac	string	yes
attributes	object	yes	Attribute name -> new value, exact dotted names from idrac_attributes_get. Example: {“RFS.1.IgnoreCertWarning”: “Enabled”} or {“Time.1.Timezone”: “US/Mountain”}.
group	string	default idrac	‘idrac’, ‘system’, or ‘lc’ — must match where the attributes live.

Full guidance (the docstring the LLM sees)

Set Dell attributes. Applies IMMEDIATELY — no reboot, no job.

DESTRUCTIVE: this can reconfigure the iDRAC's own network, disable its
web server, or change user credentials — i.e., lock you out of the
management plane itself. Read the current value first and change the
minimum necessary.

Honesty guarantee: after the PATCH, this tool reads the attributes BACK
and diffs against what you asked for. `status` is "applied" only when
every attribute reads back with the requested value; otherwise it's
"partial" with a `rejected` dict showing wanted-vs-actual. Dell returns
200 with complaints in @Message.ExtendedInfo for read-only/invalid keys
— those messages are surfaced too. (Write-only attributes like user
passwords never read back; they appear in `rejected` with actual=null —
check `messages` to judge those.)

idrac_jobs

read-only · idempotent

Argument	Type	Required	Description
idrac	string	yes
job_id	string	default ``	Optional JID (e.g. ‘JID_123456789012’) to fetch one job instead of the list.
wait	boolean	default False	With job_id: poll until the job reaches a terminal state (Completed/Failed), up to 5 minutes. Use after idrac_bios_set reboot=true or idrac_scp_import.

Full guidance (the docstring the LLM sees)

List the iDRAC job queue, or fetch/await a single job.

Jobs are how Dell applies staged changes: BIOS config jobs, firmware
updates, SCP imports. Each has JobState (Scheduled → Running →
Completed/Failed), PercentComplete, and human-readable Message.

A job stuck in "Scheduled" usually means it's waiting for the reboot
that triggers it. A Failed job's Message says why (invalid attribute
value, dependency, etc.).

idrac_scp_export

idempotent

Argument	Type	Required	Description
idrac	string	yes
target	string	default ALL	What to export: ‘ALL’, or a component like ‘BIOS’, ‘iDRAC’, ‘NIC’, ‘RAID’, ‘System’, ‘LifecycleController’.

Full guidance (the docstring the LLM sees)

Export the Server Configuration Profile (SCP) — the full declarative
config of the box as JSON.

The SCP is Dell's config-as-code format: every BIOS token, iDRAC
attribute, RAID layout, and NIC setting in one document. Use it for:
  - Config BACKUP before risky changes (save the output to a file!)
  - Cloning a golden config to identical hardware via idrac_scp_import
  - Diffing two boxes' configs

This blocks while the iDRAC generates the export (typically 30-90s)
and returns the profile in `scp` — the `scp` value is the
SystemConfiguration document itself, which is exactly what
idrac_scp_import expects (pass `scp`, not this whole result).
Passwords are exported as hashes or omitted, so an import of this
document won't restore credentials.

idrac_scp_import

destructive

Argument	Type	Required	Description
idrac	string	yes
scp	object	yes	The SCP document to import — the scp object from a previous idrac_scp_export (or a hand-edited subset: an SCP with only the components you want changed is valid and applies only those).
shutdown_type	string	default Graceful	‘Graceful’ (default — OS shuts down cleanly before applying host-side changes), ‘Forced’ (immediate), or ‘NoReboot’ (stage only; job waits until the next manual reboot).
preview	boolean	default False	If true, VALIDATE the SCP against this box without applying anything. Always preview an SCP from another box first.
allow_cross_import	boolean	default False	The SCP carries the service tag of the box it was exported from. By default an import is REFUSED when that tag doesn’t match the target (wrong-box imports can rebuild RAID arrays = data loss). Set true only for a deliberate golden-config clone to different hardware.

Full guidance (the docstring the LLM sees)

Import a Server Configuration Profile. DESTRUCTIVE — can reconfigure
BIOS, RAID (data loss if the SCP defines virtual disks!), NIC, and the
iDRAC itself, and usually reboots the host.

Guardrails built in:
  - `scp` must be the SystemConfiguration document itself (the `scp`
    VALUE from idrac_scp_export, not the whole tool result) — anything
    else is rejected before touching the BMC
  - the SCP's source service tag must match the target box unless
    allow_cross_import=true
  - the host's current power state is preserved (a powered-off box is
    NOT powered on as a side effect)

Safety ladder:
  1. idrac_scp_export first — capture current state for rollback
  2. preview=true — validate without applying
  3. Import with shutdown_type='Graceful'

Returns a job_id immediately (imports take minutes and may reboot the
box mid-way — blocking here would be pointless). Poll with
idrac_jobs job_id=<jid> wait=true. With shutdown_type='NoReboot' the
job sits Scheduled until you reboot manually.

Console

idrac_console

Argument	Type	Required	Description
idrac	string	yes

Full guidance (the docstring the LLM sees)

Get access to the host's console: an HTML5 virtual-console URL and
serial-console instructions.

Tries Dell's GetKVMSession OEM action, which mints one-shot temporary
credentials and yields a DIRECT browser URL to the HTML5 KVM — no
iDRAC login page. The temp credentials are short-lived (use the URL
within ~a minute) and single-session; call this tool again for a
fresh one. Requires newer iDRAC9 firmware (roughly 5.x+); on older
firmware this falls back to the normal login URL.

Also returns serial console (SOL) guidance: iDRAC9 exposes the host
serial console via `ssh <user>@<host>` then `console com2`, and via
`ipmitool -I lanplus ... sol activate` if IPMI-over-LAN is enabled.
BIOS/OS output only appears there if serial redirection is configured.

Marked non-read-only because GetKVMSession creates a session object on
the iDRAC (harmless, self-expiring).