Skip to content

Tool reference — all 21 tools, with usage and examples

Every capability of iiq-rules-mcp is exposed as an MCP tool. In normal use you don't call tools yourself — you describe what you need in Claude Desktop (see the HOW-TO guide and its prompt library) and the model drives them. But every tool can also be invoked directly by asking for it by name, which is exactly what the examples below show.

The envelope — every answer has the same shape

All 21 tools respond with one JSON envelope:

{
  "server":   { "name": "iiq-rules-mcp", "version": "1.6.4" },
  "tool":     "iiq_class_lookup",
  "verdict":  "confirmed",
  "grounding": { "iiq_version": "8.1 ...", "jar": { "count": 209, "...": "..." },
                 "dtd": { "...": "..." }, "export": { "...": "..." },
                 "markers_ok": true, "pins_ok": true },
  "license":  { "mode": "trial", "expires": "2026-07-23", "...": "..." },
  "result":   { "...": "tool-specific payload" },
  "warnings": [],
  "limits":   [],
  "error":    null
}
  • verdict is one of exactly four values: confirmed (positively verified against a named substrate) · refuted (positively contradicted — fix the artifact) · unverifiable (could not be checked — never treat as clean) · advisory (calibrated judgment aid, may be wrong).
  • grounding stamps what the answer was verified against (your jar/DTD/export fingerprints) — an answer from a mis-grounded session is visibly from that session.
  • limits names every bound on the answer (truncation, scan scope, the runtime-semantics ceiling). Nothing is silently skipped.
  • error is only for bad input or internal faults — a missing substrate is answered as unverifiable with a named reason, never disguised as an error or as success.

Below, "Verdicts" states what each verdict means for that tool.

Status

iiq_grounding_status()

The first tool to call in any session: what is this server grounded in, right now?

  • Args: none.
  • Verdicts: always confirmed — it reports state (and it is the only tool that still answers when the license blocks work, so the license state is always inspectable).
  • Ask: "Run iiq_grounding_status and summarize it."
  • Returns: per-substrate identities (jar fingerprint, DTD/export hashes, registry source), the boot attestation (JVM identity + the three marker classes), the structural pins report, the license state, and degradations — a named list of exactly which capabilities answer unverifiable because an optional substrate is absent. Empty list = fully grounded.

The composite gate

iiq_verify_rule_artifact(rule_xml)

The blocking gate. Seven stages over one drafted Rule, one verdict. Never present a generated rule as verified unless this returns confirmed.

  • Args: rule_xml — the complete Rule document (naked <Rule> or a <sailpoint> wrapper containing exactly one Rule).
  • Stages: 1 xml_dtd (DTD validation + import packaging + storage limits read from your own jar) → 2 signature (type + <Signature> vs the registry contract) → 3 references (imports vs classpath, object references vs export) → 4 bsh_parse (no-eval syntax) → 5 scope (variable reads vs the injected contract) → 6 members (static members + method existence/arity on grounded receivers) → 7 reviews (advisory annex — never gates).
  • Verdicts: worst gating stage wins — any refuted stage refutes the artifact; any unverifiable or skipped stage means it cannot be called verified; confirmed only when stages 1–6 all confirm.
  • Ask: "Run iiq_verify_rule_artifact on this rule and walk me through every stage: [paste rule XML]"
  • Returns: result.stages (per-stage verdict, skip reason, and detail — line-anchored findings with ready-to-paste fixes), result.advisories (non-gating findings — read them), and result.reviews (best-practices/security/performance annex). Every response carries the claim_ceiling limit: runtime semantics are out of scope by design.

Example of a refuted stage's detail (a missing DOCTYPE):

{ "stage": "xml_dtd", "verdict": "refuted",
  "detail": { "packaging": { "import_ready": false,
    "finding": "no DOCTYPE: `iiq console import` rejects this file at line 2 ...",
    "fix": "add this line directly after the XML prolog: <!DOCTYPE Rule PUBLIC \"sailpoint.dtd\" \"sailpoint.dtd\">" } } }

Selection & registry

iiq_rule_catalog(keyword="")

WHICH rule type fits the scenario — browse all 102 types by functional family, or filter by keyword.

  • Args: keyword — optional literal, case-insensitive filter over type names and behavior facts. Empty = the full grouped catalog.
  • Verdicts: always advisory — selection guidance is doc-derived (own words), never a verified claim. Zero matches means only that the catalog text doesn't mention the term.
  • Ask: "Which rule type fires when accounts are aggregated from a delimited file? Search the catalog for 'file'."
  • Returns: result.families → per-type {purpose, fires_when, executor, returns, doc_covered}. Always confirm the chosen type with iiq_rule_signature next.

iiq_rule_signature(rule_type)

The authoritative Signature contract for one rule type: what IIQ injects, what the rule must return.

  • Args: rule_type — case-sensitive Rule$Type value, e.g. "Correlation", "BuildMap", "BeforeProvisioning".
  • Verdicts: confirmed from the registry (per-field source labels: bundled snapshot vs your export's <RuleRegistry> override); refuted for a type that doesn't exist.
  • Ask: "Show me the signature contract for BuildMap — what does IIQ inject at runtime and what must the rule return?"
  • Returns: signature_inputs (the args IIQ actually passes — note: connector-invoked types like BuildMap/JDBC/WebService bypass runRule() and receive ONLY these), inputs, runrule_default_args (context/log/taskResult — only for runRule-invoked types), doc-derived behavior facts (purpose / fires-when / return contract), and per-field provenance.

Reflection (your classpath is the truth)

iiq_class_lookup(class_fqn)

Full reflection metadata for one class.

  • Args: class_fqn, e.g. "sailpoint.object.ProvisioningPlan"; nested classes in source form (Outer.Inner) work.
  • Verdicts: confirmed (loads, with full metadata) · refuted (definitively not on the classpath — a grounded negative) · unverifiable (exists but could not be inspected; reason named).
  • Ask: "Look up sailpoint.object.ProvisioningPlan — methods, fields, superclass."
  • Returns: modifiers, superclass, interfaces, methods[], fields[].

iiq_method_signature(class_fqn, method_name)

Every overload of a method, across the whole inheritance hierarchy.

  • Args: class_fqn, method_name (simple name).
  • Verdicts: confirmed with overloads; refuted when the member exists on neither the class nor any ancestor — a grounded negative under declared+inherited scope.
  • Ask: "What overloads does sailpoint.api.SailPointContext.getObject have, and which class declares each?"
  • Returns: result.overloads — each with parameters, return type, declared_on, and an inherited flag. Compiler bridge/synthetic methods are segregated into result.compiler_artifacts — real bytecode, but never API to write against.

iiq_implementations_of(interface_fqn, package_prefix=None, limit=100)

Concrete classes implementing/extending a type.

  • Args: the interface/abstract FQN; a dotted package_prefix is strongly recommended (real classpaths run ~240 JARs); limit caps hits (reported as a truncated limit, never silent).
  • Verdicts: confirmed with hits · unverifiable when zero found (absence unproven under scan bounds) · refuted when the interface itself is not on the classpath.
  • Ask: "List implementations of sailpoint.connector.Connector under the sailpoint package."

iiq_search_api(keyword, limit=25, package_prefix=None)

Find classes by name — substring plus typo-tolerant fuzzy match.

  • Verdicts: always confirmed (it reports ranked matches; match_kind: "fuzzy" entries are suggestions, not exact hits).
  • Ask: "Search the classpath for classes matching 'WebService'."

iiq_verify_class_references(class_refs)

Batch existence check for Java FQNs — three-state, per input.

  • Args: class_refs — a non-empty list of FQNs.
  • Verdicts: refuted if anything is definitively missing · unverifiable if anything could not be inspected · confirmed when all resolve.
  • Ask: "Check these classes exist on my classpath: sailpoint.object.Identity, sailpoint.tools.Util, sailpoint.object.Imaginary."
  • Returns: one {fqn, status, reason} per input, in order (resolved | missing | uninspectable), plus a summary count.

XML / DTD (your sailpoint.dtd is the truth)

iiq_xml_schema_for(artifact_type)

The DTD-grounded envelope schema for an artifact type.

  • Args: element name, optionally qualified: "Rule", "Rule:Customization", "Workflow".
  • Verdicts: confirmed · refuted (element not in this DTD) · unverifiable (no DTD configured).
  • Ask: "What's the XML structure of a Rule element? Include the valid type values."
  • Returns: the raw content_model (the ordering truth) and — for Rule — result.rule_types, the enumerated valid type values.

iiq_xml_element_attrs(element_name)

Attributes + content model for one DTD element.

  • Ask: "What attributes does the Signature element accept, and what children can it contain?"
  • Returns: content_model, allowed_children (unordered), attributes with types, enum values, and defaults. Verdicts as above.

iiq_verify_xml(xml)

Validate any IIQ artifact XML against your DTD (Xerces).

  • Args: any artifact XML; a missing DOCTYPE is auto-injected for validation and reported in limits.
  • Verdicts: confirmed (zero violations) · refuted with line/column errors — plus a targeted warning when the error pattern fingerprints an un-CDATA'd <Source> · unverifiable (no DTD).
  • Ask: "Validate this XML against my DTD: [paste XML]"

BeanShell (parsed with bsh.Parser — never executed)

iiq_verify_beanshell(source)

Syntax check for a <Source> body.

  • Verdicts: confirmed (parses) · refuted with {kind, message, line, column} errors mapping directly to your input · unverifiable (bsh not on the classpath).
  • Ask: "Parse-check this BeanShell: [paste code]"

iiq_analyze_beanshell(source)

Structured, line-anchored facts — what the script actually touches.

  • Verdicts: confirmed with facts · unverifiable when it doesn't parse (errors echoed).
  • Ask: "What does this script do — imports, API calls, loops, exception handling? [paste code]"
  • Returns: result.facts = imports, calls, loops, exception_handling, and robustness flags (e.g. search_in_loop, no_exception_handling).

iiq_verify_beanshell_scope(source, rule_type=None, declared_inputs=None)

Reads of variables that are neither defined nor injected.

  • Args: pass rule_type so the per-type injected contract applies, and declared_inputs for args your drafted <Signature> declares.
  • Verdicts: refuted on confident findings (result.undefined, line-anchored) · advisory when the injected set is uncertain (caller-scope types, or no type given) · confirmed when clean · unverifiable when it doesn't parse. result.considered_injected shows exactly what was treated as in scope.
  • Ask: "Check this Correlation source for undefined variables: [paste code]"

iiq_verify_beanshell_members(source)

Do the static members and method calls the script names exist on your classpath?

  • Verdicts: confirmed when every judged ClassName.member and every grounded method call resolves · refuted with unresolved entries (including valid_alternatives suggestions) · unverifiable when the source doesn't parse or calls can't be typed.
  • Ask: "Verify the members in this snippet — is Filter.MatchMode.START real? [paste code]"

iiq_verify_rule(rule_xml)

Quick rule-level check: BeanShell syntax + import resolution in one call (a subset of the composite gate).

  • Verdicts: confirmed (parses AND every concrete import resolves) · refuted (syntax errors, missing imports, structurally broken artifact) · unverifiable (imports uninspectable / bsh unavailable).
  • Ask: "Quick-check this rule XML — syntax and imports only: [paste XML]"

Object references (your export is the truth)

iiq_verify_references(artifact_xml)

Do the <Reference>s and by-name object references resolve in YOUR deployment?

  • Args: a single artifact or a <sailpoint>-wrapped bundle (bundles are co-generation-aware: siblings imported together resolve against each other).
  • Verdicts: refuted on any dangling reference — the class of failure that crashes at import time or at first use · confirmed when everything checkable resolves · unverifiable without an export (never silently clean).
  • Ask: "Do the object references in this artifact resolve in my export? [paste XML]"
  • Returns: result.unresolved with up to 3 did-you-mean suggestions per miss (suppress with IIQ_DISABLE_CATALOG_SUGGESTIONS=true).

Reviews (always advisory — never a gate)

iiq_best_practices(source=None, artifact_type=None, name=None)

iiq_security_review(source=None, artifact_type=None, name=None)

iiq_performance_review(source=None, artifact_type=None, name=None)

Calibrated heuristic reviews — three rulesets, one shape.

  • Args (two modes): inline — pass source (drafted BeanShell; works without an export); export mode — pass artifact_type ("Rule") and name to deep-review one artifact from your export.
  • Verdicts: always advisory — findings are judgment aids for a human, never verified claims. unverifiable when there is neither a source nor an export.
  • Ask: "Run a security review on this source: [paste code]" · "Performance-review the rule named 'AD Correlation' from my export."
  • Returns: a score, findings[] with severity / message / suggestion / line, and ruleset provenance (bundled vs your override files).

Putting it together

The intended flow (taught to the model by the bundled iiq_rule_authoring_contract prompt):

  1. iiq_grounding_status — know what this session can prove.
  2. iiq_rule_catalog → iiq_rule_signature — pick and confirm the type's contract.
  3. iiq_class_lookup / iiq_method_signature / iiq_search_api — ground every API before writing it.
  4. Draft, then iiq_verify_rule_artifact — repair per stage findings, repeat until confirmed.
  5. Present with every advisory and unverifiable item surfaced.

The individual tools exist so you (or the model) can zoom into any single layer — but the composite gate is the only verdict that means "verified".

iiq-rules-mcp is an independent product of SIMPLIFYAUTH CONSULTANCY SERVICES (OPC) PRIVATE LIMITED, not affiliated with, endorsed by, or sponsored by SailPoint Technologies. SailPoint, IdentityIQ, and related marks are trademarks of SailPoint Technologies, Inc., used only to describe compatibility.