Skip to main content
Glama
nh4ttruong

secobserve-mcp

by nh4ttruong
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Assess SecObserve Observation

secobserve_assess_observation

Assess one vulnerability observation: change its severity, status, priority, or VEX justification with a mandatory comment, writing an attributable audit log for VEX generation.

Instructions

Record a human assessment on one observation: change its severity, status, priority or VEX justification.

This is how triage is done. It writes an observation log, so the change is attributable and reversible, and it is what later VEX documents are generated from. Never edit an observation's severity or status with secobserve_update -- that bypasses the log and the approval workflow.

Two rules the API enforces: a comment is mandatory, and a new assessment is refused while the previous one is still in 'Needs approval'.

Args: observation_id (int): Observation to assess. severity (Optional[Severity]): Unknown/None/Low/Medium/High/Critical. status (Optional[Status]): Open/Affected/Resolved/Duplicate/False positive/ In review/Not affected/Not security/Risk accepted. priority (Optional[int]): 1-99. clear_priority (bool): Remove the priority instead of setting one. vex_justification (Optional[VexJustification]): Machine-readable reason, expected with 'Not affected' and 'False positive'. risk_acceptance_expiry_date (Optional[str]): YYYY-MM-DD, for 'Risk accepted'. comment (str): Mandatory rationale, 1-4096 characters.

Returns: str: A confirmation line naming the observation and the fields changed, plus a note when the instance's four-eyes setting leaves the assessment in 'Needs approval' (the API returns an empty body on success).

Examples: - Use when: "mark 8123 as not affected, the vulnerable function is never called" -> observation_id=8123, status="Not affected", vex_justification="vulnerable_code_not_in_execute_path", comment="..." - Use when: "accept the risk on 8123 until the end of the quarter" -> status="Risk accepted", risk_acceptance_expiry_date="2026-12-31", comment="..." - Don't use when: assessing many findings the same way (use secobserve_bulk_assess_observations). - Don't use when: approving someone else's assessment (use secobserve_approve_observation_log).

Error Handling: 400 "Cannot create new assessment while last assessment still needs approval" means the previous assessment must be approved or rejected first. 403 means the token lacks Observation_Assessment on that product. The schema refuses a call that would change nothing.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
statusNoNew status. Omit to leave it as it is.
commentYesWhy this assessment was made. Mandatory -- it is the audit record, and approvers see only this. State the evidence, not just the verdict.
priorityNoNew priority, 1 (most urgent) to 99. Use clear_priority to remove one.
severityNoNew severity. Omit to leave it as it is.
clear_priorityNoRemove the existing priority. Cannot be combined with priority.
observation_idYesId of the observation to assess.
vex_justificationNoWhy the finding does not apply. Expected with status 'Not affected' or 'False positive' so that generated VEX documents carry a machine-readable reason.
risk_acceptance_expiry_dateNoISO date (YYYY-MM-DD) when a 'Risk accepted' status lapses back to open.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changedv0.3.0
    • removedInput schema / $defs / AssessObservationInput
      Removed value: -{
-  "additionalProperties": false,
-  "description": "Input model for assessing one observation.",
-  "properties": {
-    "comment": {
-      "description": "Why this assessment was made. Mandatory -- it is the audit record, and approvers see only this. State the evidence, not just the verdict.",
-      "maxLength": 4096,
-      "minLength": 1,
-      "title": "Comment",
-      "type": "string"
-    },
-    "observation_id": {
-      "description": "Id of the observation to assess.",
-      "minimum": 1,
-      "title": "Observation Id",
-      "type": "integer"
-    },
-    "priority": {
-      "anyOf": [
-        {
-          "maximum": 99,
-          "minimum": 1,
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "New priority, 1 (most urgent) to 99. Send null to clear a priority.",
-      "title": "Priority"
-    },
-    "risk_acceptance_expiry_date": {
-      "anyOf": [
-        {
-          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "ISO date (YYYY-MM-DD) when a 'Risk accepted' status lapses back to open.",
-      "title": "Risk Acceptance Expiry Date"
-    },
-    "severity": {
-      "anyOf": [
-        {
-          "$ref": "#/$defs/Severity"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "New severity. Omit to leave it as it is."
-    },
-    "status": {
-      "anyOf": [
-        {
-          "$ref": "#/$defs/Status"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "New status. Omit to leave it as it is."
-    },
-    "vex_justification": {
-      "anyOf": [
-        {
-          "$ref": "#/$defs/VexJustification"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Why the finding does not apply. Expected with status 'Not affected' or 'False positive' so that generated VEX documents carry a machine-readable reason."
-    }
-  },
-  "required": [
-    "comment",
-    "observation_id"
-  ],
-  "title": "AssessObservationInput",
-  "type": "object"
-}
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / clear_priority
      Added value: +{
+  "default": false,
+  "description": "Remove the existing priority. Cannot be combined with priority.",
+  "title": "Clear Priority",
+  "type": "boolean"
+}
    • addedInput schema / properties / comment
      Added value: +{
+  "description": "Why this assessment was made. Mandatory -- it is the audit record, and approvers see only this. State the evidence, not just the verdict.",
+  "maxLength": 4096,
+  "minLength": 1,
+  "title": "Comment",
+  "type": "string"
+}
    • addedInput schema / properties / observation_id
      Added value: +{
+  "description": "Id of the observation to assess.",
+  "minimum": 1,
+  "title": "Observation Id",
+  "type": "integer"
+}
    • removedInput schema / properties / params
      Removed value: -{
-  "$ref": "#/$defs/AssessObservationInput"
-}
    • addedInput schema / properties / priority
      Added value: +{
+  "anyOf": [
+    {
+      "maximum": 99,
+      "minimum": 1,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "New priority, 1 (most urgent) to 99. Use clear_priority to remove one.",
+  "title": "Priority"
+}
    • addedInput schema / properties / risk_acceptance_expiry_date
      Added value: +{
+  "anyOf": [
+    {
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "ISO date (YYYY-MM-DD) when a 'Risk accepted' status lapses back to open.",
+  "title": "Risk Acceptance Expiry Date"
+}
    • addedInput schema / properties / severity
      Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/Severity"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "New severity. Omit to leave it as it is."
+}
    • addedInput schema / properties / status
      Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/Status"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "New status. Omit to leave it as it is."
+}
    • addedInput schema / properties / vex_justification
      Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/VexJustification"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Why the finding does not apply. Expected with status 'Not affected' or 'False positive' so that generated VEX documents carry a machine-readable reason."
+}
    • changedInput schema / required
      Previous value: -[
-  "params"
-]New value: +[
+  "observation_id",
+  "comment"
+]
  2. First observedv0.1.2

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations, the description discloses that the tool writes an attributable and reversible observation log, that VEX documents are generated from these assessments, that a comment is mandatory, and that a new assessment is refused while the previous one is in 'Needs approval.' It even covers error semantics for 400/403 and the empty-body success response.

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 well-structured and front-loaded with the core purpose, followed by rules, args, returns, examples, and errors. It is long but warranted for an 8-parameter triage tool; the main inefficiency is that the Args section largely duplicates the schema's parameter descriptions.

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?

For a mutation-heavy triage tool with 8 parameters, the description covers prerequisites, side effects, success behavior, error handling, and routing to sibling tools. The output schema exists and the description still explains the confirmation line and the 'Needs approval' nuance, so nothing an agent needs to call it correctly 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?

The input schema already documents all 8 parameters at 100% coverage, so the baseline is 3. The description adds value through natural-language examples linking intents to parameter combinations, such as 'Not affected' requiring a vex_justification and 'Risk accepted' using risk_acceptance_expiry_date. It also calls out that clear_priority removes rather than sets priority, reinforcing the schema.

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 first sentence names a specific verb and resource: 'Record a human assessment on one observation: change its severity, status, priority or VEX justification.' This clearly scopes the tool and distinguishes it from siblings like secobserve_update, secobserve_bulk_assess_observations, and secobserve_approve_observation_log.

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?

The description explicitly says 'This is how triage is done' and warns against using secobserve_update because it bypasses the log and approval workflow. It also gives concrete 'Use when' and 'Don't use when' examples, directing bulk assessments to a sibling and approval to another.

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