Skip to main content
Glama

Ankra

by ai.ankra
OverviewDiscussionsAdmin

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.

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; 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.
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. 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"
+}
  2. First observed

TDQS

A4.6/5.0
Behavior4/5

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

readOnlyHint=true already declares safety, and 'Computes only; records nothing' reinforces rather than adds. It does, however, add behavioral context the annotation cannot: which observations are excluded (ambiguous/unattributed add-on ownership, a fix already available) and that the repository_code path may report whether the disposition can be created and, if not, why. That is genuine dry-run semantics beyond the hint.

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 'run it first' directive are front-loaded, and the dense sentences each carry weight given two distinct modes. It is long, but for an 11-parameter tool with conditional branches the length is largely earned; minor redundancy between the intro and the trailing imperative.

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?

No output schema exists, so the description must characterize the return values, and it does thoroughly: canonical selector, match counts across clusters and workloads, excluded observations, and the finding details (severity, title, line) for repository_code. For a preview tool with one readOnly annotation, an agent has everything needed to invoke and interpret it.

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 baseline is 3, but the description adds real meaning: it explains how parameters combine differently per scope (occurrence_id vs policy_id, application_id vs repository_id, and the scope-dependent allowed disposition values). This conditional logic is not fully derivable from the schema alone.

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 (preview) and resource (a security disposition), and distinguishes itself from create_security_disposition and update_security_disposition by making clear it is the non-committing dry run. The two scoped modes (cluster vulnerability vs repository_code) are named, so an agent can tell it apart from any sibling without opening a 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?

Explicitly instructs 'Always run it before create_security_disposition', and gives the precise selection rule between the two modes (occurrence_id + disposition for a new policy, policy_id to re-preview an existing one). It also states a guardrail ('Never for a CRITICAL finding' in the schema) and the repository_code input set, leaving little to inference.

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

All Ankra toolsInspect
Try in Browser
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources