GetToolsResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/stormmcp/json-schema/stormmcp-get-tools-response-schema.json",
  "title": "GetToolsResponse",
  "description": "Response model for the GetTools endpoint.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/stormmcp-dynamictoolsdiscovery-api-openapi.yml#/components/schemas/GetToolsResponse",
  "type": "object",
  "properties": {
    "results": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/LibraryToolResult"
      },
      "description": "Gets or sets the results keyed by library ID."
    },
    "sourceRefreshRateLimited": {
      "type": "boolean",
      "description": "Gets or sets a value indicating whether the hoisted Refresh Tools limiter refused this request."
    }
  },
  "$defs": {
    "DerivedAnnotationResult": {
      "type": "object",
      "properties": {
        "toolName": {
          "type": "string",
          "description": "Gets or sets the tool name this derivation corresponds to."
        },
        "status": {
          "type": "string",
          "description": "Gets or sets the row status — a value from\nDerivedAnnotationStatuses. Defaults to\nstring DerivedAnnotationStatuses.Derived so verdicts cached\nbefore the field existed deserialize as completed rows.\nstring DerivedAnnotationStatuses.Deriving rows are synthesized\nper response while the background worker runs; they are never cached\nand never stamped into stored definitions."
        },
        "hints": {
          "type": "object",
          "additionalProperties": {
            "type": "boolean"
          },
          "description": "Gets or sets the asserted hints after safety masking — only hints the\nbackend asserted at or above the confidence floor, with\n`readOnlyHint: true` never present (the asymmetry rule: a benign\nread-only label from a non-deterministic source could satisfy an\nauto-approve rule). May be empty: the backend answered but asserted\nnothing derivable."
        },
        "rationales": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Gets or sets the per-hint one-line rationales for the asserted hints.\nSurfaced on the REST row for admin evaluation; not part of the\n`_meta` stamp."
        },
        "source": {
          "type": "string",
          "description": "Gets or sets the verdict source — a value from the derivation source\nvocabulary (v1: always `model`)."
        },
        "adapterId": {
          "type": "string",
          "description": "Gets or sets the producing adapter's identity (model id + rubric\nversion), so verdicts from different brains stay distinguishable."
        },
        "confidence": {
          "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
          "type": [
            "number",
            "string"
          ],
          "description": "Gets or sets the minimum confidence across the asserted hints; zero\nwhen nothing was asserted.",
          "format": "double"
        },
        "inputHash": {
          "type": "string",
          "description": "Gets or sets the content hash of the derivation input (name,\ndescription, input-schema property names) the verdict was computed\nfrom."
        },
        "generatedAt": {
          "type": "string",
          "description": "Gets or sets when the verdict was produced.",
          "format": "date-time"
        }
      },
      "description": "Derived annotation hints for a single upstream MCP tool that declares no\n`annotations` block of its own (MCPG-1417). One entry is produced per\nderived tool; tools that were skipped (already annotated, non-upstream, or\nwhose derivation failed) produce no entry. Also the value cached in the\nglobal content-addressed verdict cache — the tool name participates in the\ncontent hash, so a cached entry's identity is stable by construction."
    },
    "JsonArray": {
      "type": "array"
    },
    "JsonObject": {
      "type": "object"
    },
    "LibraryAdvertisedSurface": {
      "type": "integer"
    },
    "LibraryDiscoveryResolutionOrigin": {
      "type": "integer"
    },
    "LibraryToolResult": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "Gets or sets a value indicating whether the tools were retrieved successfully."
        },
        "errorMessage": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the error message if the retrieval failed."
        },
        "failureOrigin": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the typed origin of an unsuccessful tools fetch (MCPG-2031).\nNull on a successful result. The in-process\nToolFetchFailureOrigin is the single source; this property\ncopies it onto the REST wire so a caller can classify credential, timeout,\ntransport, and upstream failures without parsing string? LibraryToolResult.ErrorMessage.",
              "$ref": "#/$defs/ToolFetchFailureOrigin"
            }
          ]
        },
        "resolutionOrigin": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the resolution-stage origin (MCPG-2087). Null on fetch-stage\nfailures and on success. Distinct from ToolFetchFailureOrigin? LibraryToolResult.FailureOrigin.",
              "$ref": "#/$defs/LibraryDiscoveryResolutionOrigin"
            }
          ]
        },
        "connectionReason": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the canonical `McpConnectionReasons` value on a\nresolution-stage unsuccessful result (MCPG-2075). Null otherwise."
        },
        "advertisedSurface": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the tools-versus-skills-only discriminator (MCPG-2073).\nNull when initialize did not capture capabilities, and also null when\ninitialize captured a capability list that named neither tools nor skills.",
              "$ref": "#/$defs/LibraryAdvertisedSurface"
            }
          ]
        },
        "tools": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the tools available from this library as a JSON object\n(raw pass-through of the MCP `tools/list` response shape).",
              "$ref": "#/$defs/JsonObject"
            }
          ]
        },
        "toolScans": {
          "type": [
            "null",
            "array"
          ],
          "items": {
            "$ref": "#/$defs/ToolScanResult"
          },
          "description": "Gets or sets the per-tool scan results. Correlates with entries in\nJsonObject? LibraryToolResult.Tools by string ToolScanResult.ToolName. Null when\nthe library was not scanned (feature flag off). An empty list indicates\nscanning was attempted but produced no results (scanner failure or no\ntools returned by the server)."
        },
        "advertisedCapabilities": {
          "type": [
            "null",
            "array"
          ],
          "items": {
            "type": "string"
          },
          "description": "Gets or sets the typed capability inventory the server declared at\n`initialize` (values from\nMcpServerCapabilityNames),\nor null when initialization did not complete far enough to capture capabilities\n(MCPG-1275). Lets consumers distinguish a healthy server with zero tools (e.g. a\nskills-only server) from a failed one without string matching."
        },
        "skills": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the skill inventory read from a skill-capable server's\n`skill://index.json` as the flat array of SEP-2640 index entries\n(each entry's `url`/`digest`/`frontmatter` is verbatim upstream\ncontent, MCPG-1275). Null when the server is not skill-capable, the index is unparseable, or the probe\nfailed.",
              "$ref": "#/$defs/JsonArray"
            }
          ]
        },
        "skillScans": {
          "type": [
            "null",
            "array"
          ],
          "items": {
            "$ref": "#/$defs/SkillScanResult"
          },
          "description": "Gets or sets the per-skill governance scan results (MCPG-1262). Correlates with\nentries in JsonArray? LibraryToolResult.Skills by string SkillScanResult.Url. Null when\nthe library carries no skill inventory (see JsonArray? LibraryToolResult.Skills) or the scan\nstep itself faulted. An entry whose SKILL.md body could not be\nfetched carries string ToolScanStatuses.NotScanned."
        },
        "derivedAnnotations": {
          "type": [
            "null",
            "array"
          ],
          "items": {
            "$ref": "#/$defs/DerivedAnnotationResult"
          },
          "description": "Gets or sets the per-tool derived annotation results (MCPG-1417).\nCorrelates with entries in JsonObject? LibraryToolResult.Tools by\nstring DerivedAnnotationResult.ToolName; only unannotated\nupstream tools that produced a verdict have entries. Null when the\ncaller did not opt in, the derivation backend is unconfigured, or\nderivation failed for the library. Report-only metadata — the tools' own\n`annotations` blocks are never modified."
        },
        "sourceRefreshError": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the reason an explicit refresh (`forceRefresh`) could not re-pin this\nlibrary's SpecLink or SkillLink source to its current revision (MCPG-1891). Null when the\nsource was refreshed, when the library has no pinned source, or when no refresh was asked\nfor. Discovery still ran, against the previously pinned revision, so bool LibraryToolResult.Success\nand JsonObject? LibraryToolResult.Tools describe that revision."
        },
        "sourceRefreshReasons": {
          "type": [
            "null",
            "array"
          ],
          "items": {
            "$ref": "#/$defs/SourceRefreshReason"
          },
          "description": "Gets or sets the typed per-library force-refresh reasons (MCPG-2060). Distinct from\nstring? LibraryToolResult.SourceRefreshError, which keeps the human sentence. Null or empty when no\nforce-refresh reason applies. Multiple values on one library are all present.\nSourceRefreshReason.Unspecified is never produced. SourceRefreshReason.Denied,\nSourceRefreshReason.SourceReadFailed, and\nSourceRefreshReason.RateLimited are terminal for create;\nSourceRefreshReason.CoveringRepairBumpFailed is advisory.\nSourceRefreshReason.DeadlineMissed, SourceRefreshReason.TimedOut,\nSourceRefreshReason.PersistFailed, and\nSourceRefreshReason.ConfigurationGone are not terminal for create.\nRetry the refresh after the limiter window; the create is refused (429) until\na refresh completes."
        },
        "sourceRef": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the administrator source ref after an explicit refresh (MCPG-1891).\nNull when no refresh ran, when the library is not a pinned SpecLink or SkillLink\nserver, or when the pin is a content hash. A failed re-pin keeps the previous value."
        },
        "sourceRevision": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the pinned source revision after an explicit refresh (MCPG-1891).\nNull when no refresh ran or the library has no pin. A failed re-pin keeps the previous value.\nThis is the pin triple's revision, not the observation envelope's source revision."
        },
        "sourceResolvedAt": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets when string? LibraryToolResult.SourceRevision was last resolved after an explicit refresh\n(MCPG-1891). Null when no refresh ran or the library has no pin. A failed re-pin keeps the\nprevious value.",
          "format": "date-time"
        },
        "observationSourceRevision": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the observation envelope's source revision (MCPG-1832). Distinct from\nthe force-refresh pin string? LibraryToolResult.SourceRevision."
        },
        "sourceIdentity": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the credential-free source identity from the observation envelope (MCPG-1832)."
        },
        "catalogVersion": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the content-derived catalog version of the observed tool set (MCPG-1832)."
        },
        "observationToken": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the observation token echoed when this result actually built or revalidated.\nA gateway cache hit carries the cached build's token unchanged; the\nresponse is non-advancing because this request issued no token."
        },
        "sourceCoordinate": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the source coordinate the observation was built from (MCPG-1832)."
        },
        "observationGeneration": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "null",
            "integer",
            "string"
          ],
          "description": "Gets or sets the generation the observed version holds in that coordinate's slot,\nor null when it holds none (MCPG-1832).",
          "format": "int64"
        },
        "slotCurrentVersion": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the slot's current catalog version at response time (MCPG-1832)."
        },
        "slotCurrentGeneration": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "null",
            "integer",
            "string"
          ],
          "description": "Gets or sets the slot's current generation at response time, or null when the slot has never advanced (MCPG-1832).",
          "format": "int64"
        },
        "revisionIsDerived": {
          "type": "boolean",
          "description": "Gets or sets a value indicating whether string? LibraryToolResult.ObservationSourceRevision was derived from\nthe tool-set content rather than read from an immutable coordinate pin (MCPG-1832)."
        },
        "catalogRecordReason": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets a library-addressed reason the tenantless catalog record could not be updated\nwhile producer envelope and tools were kept (MCPG-1832)."
        }
      },
      "description": "Result for tools from a specific library."
    },
    "SkillScanResult": {
      "type": "object",
      "properties": {
        "skillName": {
          "type": "string",
          "description": "Gets or sets the skill name this scan result corresponds to (the entry's\n`frontmatter.name`, or derived from the URL path when absent)."
        },
        "url": {
          "type": "string",
          "description": "Gets or sets the entry's raw `skill://` URL, verbatim from the index.\nCorrelates this result with the matching JsonArray? LibraryToolResult.Skills\nentry by its `url` property."
        },
        "status": {
          "type": "string",
          "description": "Gets or sets the scan status. Values are defined in\nToolScanStatuses — the same vocabulary as per-tool scan results.\nstring ToolScanStatuses.NotScanned covers entries whose SKILL.md body\ncould not be fetched (upstream read failed, file exceeded the size cap, or the\nentry was beyond the per-server scan cap)."
        }
      },
      "description": "Governance scan outcome for a single skill (MCPG-1262). One entry is produced per\nscannable entry of a skill-capable server's `skill://index.json` inventory;\nthe SKILL.md body is scanned by the same Policy Engine scanner used for tool\ndefinitions."
    },
    "SourceRefreshReason": {
      "type": "integer",
      "description": "Typed per-library force-refresh outcome (MCPG-2060). Mirrors the gRPC\n`SourceRefreshReason` enum. SourceRefreshReason.Unspecified is never produced.\nSourceRefreshReason.Denied, SourceRefreshReason.SourceReadFailed, and\nSourceRefreshReason.RateLimited are terminal for create.\nSourceRefreshReason.CoveringRepairBumpFailed is advisory. SourceRefreshReason.DeadlineMissed,\nSourceRefreshReason.TimedOut, SourceRefreshReason.PersistFailed, and\nSourceRefreshReason.ConfigurationGone are not terminal for create.\nSourceRefreshReason.RateLimited may appear per library in addition to the request-level\n`sourceRefreshRateLimited` flag. Retry the refresh after the limiter window;\nthe create is refused (429) until a refresh completes."
    },
    "ToolFetchFailureOrigin": {
      "type": "integer"
    },
    "ToolScanResult": {
      "type": "object",
      "properties": {
        "toolName": {
          "type": "string",
          "description": "Gets or sets the tool name this scan result corresponds to."
        },
        "status": {
          "type": "string",
          "description": "Gets or sets the scan status. Values are defined in\nToolScanStatuses."
        }
      },
      "description": "Scan outcome for a single MCP tool definition. One entry is produced per\ntool returned from the remote MCP server's `tools/list` response."
    }
  }
}