One call follows: endpoint → attachment (pod / leaf / interface or vPC) →
EPG → bridge domain → VRF → contracts the EPG provides/consumes → filter
entries, plus faults whose DN names the EPG or the attachment interface.
Every link is the relation APIC resolved (its tDn), so cross-tenant links
into 'common' are followed correctly.

How to read the result (do not over-state it):
  * It is NOT a reachability test. 'staticPathResolved: true' means the
    fabric is configured to carry the endpoint, not that traffic flows.
  * 'relatedFaultCandidates' are matched by DN only — proximity, not cause.
    Never report one as the reason for a problem. 'faults: null' means no
    fault scan succeeded (related faults unknown, not none); 'complete:
    false' means some scan failed, hit its page limit, or could not run.
  * 'tagRelations' in state 'missing-target' are policy-tag lookups and say
    nothing about the attachment path; do not report them as a path failure.
  * A section that is null with an entry in 'errors' was NOT read — never
    describe it as empty or absent. 'segmentResolved'/'staticPathResolved'
    are null in that case, not false.
  * A cleared fault keeps the description it had when raised; judge it by
    severity/lifecycle, not by its text.
  * 'contracts.complete: false' means a contract or filter was not read or
    not returned (its entry says 'read: false', 'exists: false' or has
    'entries: null') — its rules are unknown, not absent. The EPG → BD →
    VRF verdict is unaffected.
  * An 'epg' with 'supported: false' is a parent object this read does not
    trace (e.g. an L2Out external EPG) — the chain is undetermined, not broken.
  * 'notFound' means the fabric has not learned the address now, or it is in
    a tenant this account cannot see — not that the host is down.
  * 'notChecked' lists what this read does not evaluate (vzAny, taboo
    contracts, imported contracts, preferred-group peers, service graphs).

Args:
    mac: Endpoint MAC (any case; e.g. 00:50:56:AB:CD:EF). Pass mac OR ip.
    ip: Endpoint IPv4/IPv6 address. Pass mac OR ip.
    limit: Max matching endpoints to trace (default 5, max 20); the result
        carries returned/limit/truncated.
    fault_limit: Max related-fault candidates per endpoint (default 20).
    target: Target name from config (must be 'platform: aci').

Returns dict: {query, endpoints:[{endpoint, ips, attachment, attachmentFormed,
    tagRelations, epg, bd, vrf, contracts, segmentResolved, notChecked,
    relatedFaultCandidates, staticPathResolved, findings:[{rank, severity,
    signal, cause, action}], errors}], returned, limit, truncated,
    serverReportedMatches, lookupErrors, note, notFound?}.

Follows EPG → BD → VRF through the relations APIC resolved (cross-tenant
links into 'common' included) and expands the contracts the EPG provides
and consumes down to filter entries. Use it when you know the EPG but not
an endpoint in it.

A relation that is not 'formed' is reported as a finding with its state; a
read that failed is null with an entry in 'errors' (not empty — say it was
not read). An unenforced VRF means contracts do not restrict traffic in it.
'notChecked' lists what is not evaluated (vzAny, taboo, imported
contracts, preferred-group peers, service graphs).

Args:
    tenant: Tenant name (e.g. 'tenant-A').
    app: Application profile name.
    epg: EPG name.
    target: Target name from config (must be 'platform: aci').

Returns dict: {epg, bd, vrf, contracts:{contracts, returned, limit,
    truncated, filters, filtersTruncated, complete}, segmentResolved,
    notChecked,
    findings:[{rank, severity, signal, cause, action}], errors}.

Rows are fault RECORDS, not incidents: a record with 'delegated: true'
mirrors a fault raised on another object, so one condition can appear
twice — do not count them as separate problems. 'active' comes from
severity only; a cleared fault ('active: false') keeps its original
description, which is not current state. 'bySeverity.serverReported' is
APIC's own totalCount per level. Within one severity, rows are sorted
newest first among the rows APIC returned; when a level is truncated, rows
beyond the page may be newer — raise the limit before claiming "latest".

Args:
    severity: One of critical/major/minor/warning/info/cleared; omit for
        every active level.
    include_cleared: Also read cleared faults when no severity is given.
    limit: Max rows (default 50, max 500). The result carries
        returned/limit/truncated; re-run with a higher limit when
        'truncated' is true rather than treating the list as complete.
    target: Target name from config (must be 'platform: aci').

Returns dict: {severities, faults:[{rank, code, severity, active, lifecycle,
    delegated, dn, scope, pod, node, aboutDn, cause, descr, changeSet,
    lastTransition, ...}], returned, limit, truncated,
    bySeverity:{serverReported}, delegatedRecords, note}.

Args:
    network_id: Meraki network id (from network_list).
    timespan: Look-back window in seconds (7200..2592000, default 86400).
    target: Target name from config; omit for the default.

Args:
    network_id: Meraki network id.
    client_id: Client id/MAC (from client_list).
    target: Target name from config; omit for the default.

Args:
    network_id: Meraki network id.
    client_id: Client id/MAC (from client_list).
    target: Target name from config; omit for the default.

Args:
    network_id: Meraki network id.
    client_id: Client id/MAC (from client_list).
    target: Target name from config; omit for the default.

Buckets devices by Meraki model prefix (MX security appliance, MS switch, MR
wireless AP, MV camera, MG cellular gateway) and returns per-family counts.

Args:
    org_id: Meraki organization id; omit to use the target's default org.
    model: Model family/prefix to filter (e.g. 'MS', 'MR46'); omit for all.
    limit: Max rows in the returned list (default 500). The result carries
        'returned'/'limit'/'truncated'; re-run with a higher limit when
        'truncated' is true rather than treating the list as complete.
    target: Target name from config; omit for the default.

Args:
    serial: Device serial (e.g. Q2XX-XXXX-XXXX).
    org_id: Meraki organization id; omit to use the target's default org.
    target: Target name from config; omit for the default.

Args:
    org_id: Meraki organization id; omit to use the target's default org.
    target: Target name from config; omit for the default.

Args:
    serial: MS switch serial.
    target: Target name from config; omit for the default.

Args:
    network_id: Meraki network id (from network_list).
    target: Target name from config; omit for the default.

The flagship uplink RCA: pulls per-uplink loss/latency across the org (MX
security appliances), ranks the worst uplinks by a composite of average loss
and latency, flags each degraded uplink against the thresholds, and attaches
a likely cause and a recommended action. Every ranking carries its numbers,
not a black-box verdict. Pass 'records' for pure analysis, or an org/target
to pull live.

Args:
    loss_pct: Avg loss %% at/above which an uplink is degraded (default 5.0).
    latency_ms: Avg latency ms at/above which an uplink is degraded (default 150).
    records: Injected uplink series — {serial, networkId, uplink, ip,
        timeSeries:[{lossPercent, latencyMs}]}; skips live collection.
    org_id: Meraki organization id for live pull; omit to use target default.
    limit: Max rows in the ranked list (default 100). The result carries
        'returned'/'limit'/'truncated'; re-run with a higher limit when
        'truncated' is true rather than treating the list as complete.
    target: Target name from config; omit for the default.

Returns dict: {uplinksEvaluated, degradedCount, thresholds, worst:[{serial,
    networkId, uplink, ip, avgLossPct, maxLossPct, avgLatencyMs, maxLatencyMs,
    degraded, cause, action}], returned, limit, truncated, note}.

Folds device online %%, uplink health %%, and an alert-severity penalty into
one weighted score per network (0.5 / 0.3 / 0.2), every component returned so
the number is explainable. Pure analysis over injected rows — no live pull.

Args:
    device_statuses: rows {serial, networkId, status, productType} (e.g. from
        org_device_statuses' 'devices').
    uplinks: optional rows {networkId, status} (active/ready = healthy).
    alerts: optional rows {networkId, severity} (critical/warning/info).
    limit: Max rows in the ranked list (default 100). The result carries
        'returned'/'limit'/'truncated'; re-run with a higher limit when
        'truncated' is true rather than treating the list as complete.

Returns dict: {networksEvaluated, fleetScore, summary:{healthy, degraded,
    critical}, weights, worst:[{networkId, score, band, devicesOnline,
    devicesTotal, onlinePct, uplinkHealthPct, alertPenalty}], returned,
    limit, truncated, note}.

Example: network_health_score(device_statuses=[
    {"networkId":"N1","status":"online"},
    {"networkId":"N1","status":"offline"}]).

Compares each network bound to the template against the template's settings
by exact value and reports expected-vs-actual for every drifted key. Pure
analysis over injected data — no live pull.

Args:
    template: {id, name, settings:{key: value}} — the config template.
    networks: rows {networkId, name, boundTemplateId, settings:{key: value}};
        only those whose boundTemplateId matches template['id'] are checked.
    limit: Max rows in the drifted list (default 100). The result carries
        'returned'/'limit'/'truncated'; re-run with a higher limit when
        'truncated' is true rather than treating the list as complete.

Returns dict: {templateId, templateName, boundNetworks, driftedCount,
    compliantCount, settingsChecked, driftedNetworks:[{networkId, name,
    deviations:[{setting, expected, actual}]}], returned, limit, truncated,
    note}.

Example: config_template_drift(
    template={"id":"T1","name":"branch","settings":{"timezone":"UTC"}},
    networks=[{"networkId":"N1","boundTemplateId":"T1",
               "settings":{"timezone":"PST"}}]).

Args:
    org_id: Meraki organization id; omit to use the target's default org.
    target: Target name from config; omit for the default.

Args:
    network_id: Meraki network id (from network_list).
    target: Target name from config; omit for the default.

Args:
    network_id: Meraki network id (from network_list).
    target: Target name from config; omit for the default.

Args:
    network_id: Meraki network id (from network_list).
    limit: Max rows in the returned list (default 200). The result carries
        'returned'/'limit'/'truncated'; re-run with a higher limit when
        'truncated' is true rather than treating the list as complete.
    target: Target name from config; omit for the default.

Args:
    network_id: Meraki network id (from network_list).
    timespan: Look-back window in seconds (7200..2592000, default 86400).
    limit: Max rows in the returned list (default 25). The result carries
        'returned'/'limit'/'truncated'; re-run with a higher limit when
        'truncated' is true rather than treating the list as complete.
    target: Target name from config; omit for the default.

Call this first to triage a Meraki organization before drilling into a
specific network or device.

Args:
    org_id: Meraki organization id; omit to use the target's default org.
    target: Target name from config; omit for the default.

Args:
    target: Target name from config; omit for the default.

Args:
    org_id: Meraki organization id; omit to use the target's default org.
    target: Target name from config; omit for the default.

Args:
    org_id: Meraki organization id; omit to use the target's default org.
    target: Target name from config; omit for the default.

Args:
    org_id: Meraki organization id; omit to use the target's default org.
    target: Target name from config; omit for the default.

Args:
    org_id: Meraki organization id; omit to use the target's default org.
    limit: Max rows in the returned list (default 500). The result carries
        'returned'/'limit'/'truncated'; re-run with a higher limit when
        'truncated' is true rather than treating the list as complete.
    target: Target name from config; omit for the default.

Args:
    org_id: Meraki organization id; omit to use the target's default org.
    target: Target name from config; omit for the default.

Records the device's prior status for the audit trail; a reboot cannot be
undone, so no undo descriptor is offered. Pass dry_run=True to preview.

Args:
    serial: Device serial to reboot.
    dry_run: If True, preview without rebooting.
    target: Target name from config; omit for the default.

No configuration change (a locate aid), so no undo is recorded. It is still
a POST to the controller, so it is tiered as a write: ``risk_level="low"``
is what marks a tool as a *read*. Tiering this "low" would misreport a POST
as a read in the audit trail, contradicting its own [WRITE] tag.

Args:
    serial: Device serial.
    duration: Blink duration in seconds (5..120, default 20).
    target: Target name from config; omit for the default.

Captures the changed keys' prior values before the change, so the harness
records an undo (restore the prior values) and a faithful audit trail. Pass
dry_run=True to preview.

Args:
    serial: Device serial.
    attrs: Attributes to set — allowed keys: name, tags, address, notes,
        lat, lng, floorPlanId.
    dry_run: If True, preview without changing.
    target: Target name from config; omit for the default.

Captures the changed keys' prior values before the change (undo restores
them). Pass dry_run=True to preview.

Args:
    network_id: Meraki network id.
    vlan_id: VLAN id to update.
    attrs: Attributes to set — allowed keys: name, subnet, applianceIp,
        groupPolicyId, dhcpHandling.
    dry_run: If True, preview without changing.
    target: Target name from config; omit for the default.

Records the claimed serials so the harness can offer an undo (remove them).
Pass dry_run=True to preview.

Args:
    network_id: Meraki network id to claim into.
    serials: Device serials to claim.
    dry_run: If True, preview without claiming.
    target: Target name from config; omit for the default.

The devices' current network is captured for undo, so the undo token is
genuinely applicable — but claiming a device back restores MEMBERSHIP, not
CONFIGURATION. A removed device is reset to an unconfigured state; it
returns with the network's defaults, without the name, tags, address, notes
or switch-port settings it carried before. Read those with device_status /
switch_ports first if you will need them back.

Pass dry_run=True to preview. Accepts a single ``serial`` or a ``serials``
list — the list form is how claim_devices_into_network's undo replays.

Args:
    network_id: Meraki network id the devices are bound to.
    serial: One device serial to remove (or use ``serials``).
    serials: Device serials to remove (mutually exclusive with ``serial``).
    dry_run: If True, preview without removing.
    target: Target name from config; omit for the default.

REFUSES when the network is unbound and carries local VLANs: the bind
overwrites them with the template's, unbinding does not put them back, and
this tool has no VLAN-create operation — so the undo would report success
having restored nothing.

Undo, precisely: rebind to the prior template when there was one (a faithful
restore — the configuration was template-derived either way); unbind when
the network was unbound with a VERIFIED empty VLAN set (restores the binding
state only, NOT firewall rules / group policies / static routes); and NO
undo at all when the prior VLAN set could not be read.

Pass dry_run=True to preview. The preview runs the same refusal check
(reads only), so it never previews green a bind the real call would refuse.

Args:
    network_id: Meraki network id to bind.
    template_id: Config template id to bind to.
    auto_bind: Auto-bind switch/AP profiles (Meraki autoBind flag).
    dry_run: If True, preview without binding.
    target: Target name from config; omit for the default.

Captures the template the network was bound to, so undo rebinds to it. Pass
dry_run=True to preview.

Args:
    network_id: Meraki network id to unbind.
    dry_run: If True, preview without unbinding.
    target: Target name from config; omit for the default.

Each entry names the original tool, the inverse tool that ``undo_apply``
would run, and a human note. Use the ``undoId`` with ``undo_apply``.

One extra row is fetched so ``truncated`` is **measured**, not guessed from
the returned count happening to equal the limit — a capped list that cannot
say "there is more" invites a weak model to report it as the whole story.

Each entry carries ``effectVerified``. False means the original write
lost its response, so the change it reverses is PROBABLE, not confirmed —
check the live state before applying, and do not report the result as a
restore of a state that may never have been reached.

Args:
    limit: Max rows to return (default 50).
    target: Unused (undo state is host-local); accepted for CLI uniformity.

The inverse runs through its own governed tool, so its real risk tier is
recorded there. Pass dry_run=True to preview the inverse call without
executing it. A token can only be applied once.

Args:
    undo_id: The undoId from undo_list (or an ``_undo_id`` in a write result).
    dry_run: If True, preview the inverse tool + params without running it.
    target: Passed through to the inverse tool when it accepts a target.