Skip to main content
Glama

Preview security disposition

preview_security_disposition
Read-only

Preview what a disposition would cover before creating or changing it. For a cluster vulnerability: the canonical selector, how many occurrences across which clusters and workloads it would match, and the observations it would exclude (ambiguous or unattributed add-on ownership, a fix already available); give occurrence_id + disposition to preview a new policy, or policy_id to re-preview an existing one. With scope repository_code: the Semgrep or Checkov finding it would be recorded against (severity, title, line), whether it can be created and, if not, why. Computes only; records nothing. Always run it before create_security_disposition so the confirmation names the real blast radius.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "preview_security_disposition"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNoWith scope repository_code: the file the finding is in, as get_application_code_security reports it (file_path).
toolNoWith scope repository_code: semgrep or checkov, the scanner that reported the finding (get_application_code_security).
scopeNoWhat the disposition is pinned to. For a cluster vulnerability, with occurrence_id: organisation_addon (the default) pins the add-on the occurrence is attributed to across the organisation and needs a high-confidence add-on attribution; namespace pins every workload in the occurrence's namespace on its cluster and survives rollouts and image rebuilds (the usual choice for accepting a transitive dependency's CVE in one application); workload pins the one workload (cluster, kind, namespace, name), and a Deployment's ReplicaSet pins the Deployment so it survives rollouts; image pins the image digest wherever it runs and lapses when the image is rebuilt. Use namespace, workload or image when the occurrence has no add-on attribution (operator-managed pods, plain manifests, control-plane pods, charts outside the catalogue, your own application images). repository_code is a Semgrep or Checkov finding of a pipeline repository: pass application_id or repository_id, tool, rule_id and path instead of occurrence_id, and the Ankra Pipelines image gate stops blocking on that rule in that file while the disposition is active. Never for a CRITICAL finding.
rule_idNoWith scope repository_code: the finding's rule id, as get_application_code_security reports it.
policy_idNoExisting policy id (UUID) from list_security_dispositions. Exactly one of occurrence_id or policy_id.
expires_atNoReview deadline as an RFC 3339 timestamp.
dispositionNoacknowledged or accepted_risk. Required with occurrence_id. With scope repository_code: false_positive or accepted_risk.
occurrence_idNoOccurrence id (UUID) from get_security_finding or list_security_finding_occurrences. Exactly one of occurrence_id or policy_id, unless scope is repository_code.
repository_idNoWith scope repository_code: the pipeline repository (UUID). Exactly one of application_id or repository_id.
application_idNoWith scope repository_code: the application (UUID) whose pipeline repository the finding belongs to. Exactly one of application_id or repository_id.
expire_when_fix_availableNoWhether the policy should lapse as soon as a fixed version exists.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / scope / description
      Previous value: -"What the disposition is pinned to. For a cluster vulnerability, with occurrence_id: organisation_addon (the default) pins the add-on the occurrence is attributed to across the organisation and needs a high-confidence add-on attribution; workload pins the one workload (cluster, kind, namespace, name); image pins the image digest wherever it runs. Use workload or image when the occurrence has no add-on attribution (operator-managed pods, plain manifests, control-plane pods, charts outside the catalogue). repository_code is a Semgrep or Checkov finding of a pipeline repository: pass application_id or repository_id, tool, rule_id and path instead of occurrence_id, and the Ankra Pipelines image gate stops blocking on that rule in that file while the disposition is active. Never for a CRITICAL finding."New value: +"What the disposition is pinned to. For a cluster vulnerability, with occurrence_id: organisation_addon (the default) pins the add-on the occurrence is attributed to across the organisation and needs a high-confidence add-on attribution; namespace pins every workload in the occurrence's namespace on its cluster and survives rollouts and image rebuilds (the usual choice for accepting a transitive dependency's CVE in one application); workload pins the one workload (cluster, kind, namespace, name), and a Deployment's ReplicaSet pins the Deployment so it survives rollouts; image pins the image digest wherever it runs and lapses when the image is rebuilt. Use namespace, workload or image when the occurrence has no add-on attribution (operator-managed pods, plain manifests, control-plane pods, charts outside the catalogue, your own application images). repository_code is a Semgrep or Checkov finding of a pipeline repository: pass application_id or repository_id, tool, rule_id and path instead of occurrence_id, and the Ankra Pipelines image gate stops blocking on that rule in that file while the disposition is active. Never for a CRITICAL finding."
  2. Changed8 schema fields changed
    • addedInput schema / properties / application_id
      Added value: +{
      +  "description": "With scope repository_code: the application (UUID) whose pipeline repository the finding belongs to. Exactly one of application_id or repository_id.",
      +  "type": "string"
      +}
    • changedInput schema / properties / disposition / description
      Previous value: -"acknowledged or accepted_risk. Required with occurrence_id."New value: +"acknowledged or accepted_risk. Required with occurrence_id. With scope repository_code: false_positive or accepted_risk."
    • changedInput schema / properties / occurrence_id / description
      Previous value: -"Occurrence id (UUID) from get_security_finding or list_security_finding_occurrences. Exactly one of occurrence_id or policy_id."New value: +"Occurrence id (UUID) from get_security_finding or list_security_finding_occurrences. Exactly one of occurrence_id or policy_id, unless scope is repository_code."
    • addedInput schema / properties / path
      Added value: +{
      +  "description": "With scope repository_code: the file the finding is in, as get_application_code_security reports it (file_path).",
      +  "type": "string"
      +}
    • addedInput schema / properties / repository_id
      Added value: +{
      +  "description": "With scope repository_code: the pipeline repository (UUID). Exactly one of application_id or repository_id.",
      +  "type": "string"
      +}
    • addedInput schema / properties / rule_id
      Added value: +{
      +  "description": "With scope repository_code: the finding's rule id, as get_application_code_security reports it.",
      +  "type": "string"
      +}
    • changedInput schema / properties / scope / description
      Previous value: -"What the policy is pinned to, with occurrence_id: organisation_addon (the default) pins the add-on the occurrence is attributed to across the organisation and needs a high-confidence add-on attribution; workload pins the one workload (cluster, kind, namespace, name); image pins the image digest wherever it runs. Use workload or image when the occurrence has no add-on attribution (operator-managed pods, plain manifests, control-plane pods, charts outside the catalogue)."New value: +"What the disposition is pinned to. For a cluster vulnerability, with occurrence_id: organisation_addon (the default) pins the add-on the occurrence is attributed to across the organisation and needs a high-confidence add-on attribution; workload pins the one workload (cluster, kind, namespace, name); image pins the image digest wherever it runs. Use workload or image when the occurrence has no add-on attribution (operator-managed pods, plain manifests, control-plane pods, charts outside the catalogue). repository_code is a Semgrep or Checkov finding of a pipeline repository: pass application_id or repository_id, tool, rule_id and path instead of occurrence_id, and the Ankra Pipelines image gate stops blocking on that rule in that file while the disposition is active. Never for a CRITICAL finding."
    • addedInput schema / properties / tool
      Added value: +{
      +  "description": "With scope repository_code: semgrep or checkov, the scanner that reported the finding (get_application_code_security).",
      +  "type": "string"
      +}
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true; the description goes further by stating 'Computes only; records nothing' and detailing what the preview would exclude (ambiguous or unattributed add-on ownership, a fix already available). It also flags the org-wide scope precondition of a high-confidence add-on attribution, which is a real behavioral constraint an agent could otherwise miss.

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?

Purpose and the pre-requisite to call it before create_security_disposition are front-loaded, and each sentence carries real information. It is dense and the scope sentence is long, but trimming it would lose the conditional routing that makes the tool callable.

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

Completeness5/5

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

There is no output schema, and the description compensates by describing exactly what the preview returns in both modes: the canonical selector, occurrence counts by cluster and workload, excluded observations, and for repository_code the finding's severity, title and line plus whether creation is possible and why not. Nothing an agent needs to call this correctly or interpret the result is missing.

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 coverage is 100%, so the schema already carries per-parameter definitions and the description need not repeat them. It still adds value by explaining the conditional mode logic (occurrence_id + disposition for a new policy, policy_id for re-preview) and by tying scope choices to concrete situations like operator-managed pods or transitive dependencies. It stops short of explaining expire_when_fix_available's interaction with the exclusions, hence not a 5.

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?

States a specific verb and resource — 'Preview what a disposition would cover before creating or changing it' — and immediately distinguishes itself from the mutating sibling create_security_disposition. The two operating modes (cluster vulnerability vs. repository_code finding) are named explicitly, so an agent knows the scope of the tool without opening the schema.

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?

Gives explicit routing: 'give occurrence_id + disposition to preview a new policy, or policy_id to re-preview an existing one', and mandates running it before create_security_disposition. It also states an exclusion ('Never for a CRITICAL finding') and when to prefer namespace/workload/image scope over organisation_addon, which is exactly the kind of when/when-not guidance that prevents misuse.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.