Skip to main content
Glama

Substitutability Check

substitutability_check
Read-only

Swap a variant in a gated assembly and re-run all gates to determine whether the replacement is interchangeable, so you can revise the existing part number or assign a new one.

Instructions

Liskov-substitutability gate — Form/Fit/Function as code (§7.1, #147). Take an assembly that gates green with variant A in a slot, swap in variant B (a different family row, or any part claiming the same interface), and re-run merge_assembly + all the gates. Still green ⇒ B is interchangeable with A — by construction a compatible (MINOR/PATCH) change ⇒ revise the existing part number; a gate now fails ⇒ the swap broke Form/Fit/Function ⇒ a new part number. Purely deterministic (no API, no judgment); the substitutability test #138 (B1 families) and #146 (the interface registry) call.

manifest: path to a manifest that gates green with variant A in slot. slot: the component id to swap (variant A → variant B). variant: the replacement component spec — a dict with exactly one of file/manifest/library (the same one-source rule merge_assembly enforces). verify_baseline: re-merge the base assembly first and require it green so the premise is honest (default True).

Function, not just Form and Fit (#261): if the swapped-in variant declares a PERFORMANCE contract (#226), it is part of the comparison. A contract measured as NOT met breaks the performance gate like any other. A contract with NO recorded verdict yields a THIRD answer — substitutable: null, verdict 'performance_unproven' — because an unverified spec is not a passed spec, and handing an unproven part an existing part number is the silent pass #226 prevents.

Returns {schema, slot, variant, baseline_ok, swap_ok, substitutable (True | False | null), verdict ('substitutable' | 'not_substitutable' | 'baseline_not_green' | 'performance_unproven'), broken_gates (the NAMED gate(s) the swap broke), broken (gate→violations), classification (compatibility/semver/decision), performance? (only when a component declares a contract), reports}.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "manifest": "<manifest>",
      "slot": "<slot>",
      "variant": "<variant>"
    },
    "name": "substitutability_check"
  }
}

Input Schema

NameRequiredDescriptionDefault
slotYes
variantYes
manifestYes
workspaceNoRun this call in this named workspace
verify_baselineNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds substantial behavior beyond them: the check is deterministic with no API or judgment, verify_baseline controls whether the base assembly is re-verified, performance contracts can break the gate, and an unproven performance contract yields a distinct null verdict. There is no contradiction with 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 front-loaded with the core purpose and then proceeds through inputs and outputs in a logical order. It is long and dense with internal references, but most of that detail earns its place for a complex gate tool; the jargon-heavy cross-references are the only mild drag.

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

Completeness4/5

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

For a complex, read-only gate with low schema coverage and no output schema, the description is largely complete: it covers purpose, workflow, key inputs, possible verdicts, broken gates, and the three-valued substitutable result. The main omission is the workspace parameter, and some return fields like schema are only named rather than explained.

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 only 20%, so the description must carry parameter meaning. It defines manifest, slot, variant, and verify_baseline well, including the critical one-source rule for variant. It does not explain the optional workspace parameter, which is the main remaining gap.

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 states a specific operation — a Liskov-substitutability gate that swaps variant B into a slot and re-runs merge_assembly plus gates — and clearly distinguishes the result from ordinary assembly merging. An agent can identify this as the interchangeability check among siblings like merge_assembly and interface_align_check.

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

Usage Guidelines5/5

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

It explicitly describes the scenario: start from an assembly that gates green with variant A, swap in variant B, and re-run the gates. It also states the decision rule: green means revise the existing part number, while a failure means a new part number, and it names merge_assembly and the relevant tests that call this tool.

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