Skip to main content
Glama
nh4ttruong

secobserve-mcp

by nh4ttruong
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Bulk Assess SecObserve Observations

secobserve_bulk_assess_observations

Apply one assessment to up to 250 vulnerability observations at once. Set status, severity, priority, VEX justification, and a shared comment to resolve bulk findings consistently.

Instructions

Apply one identical assessment to up to 250 observations by id.

The comment is stored on every one of them, so write it to be true of the whole set. Get the ids from secobserve_list with response_format="json" and fields=["id"]; a filter that matches more than 250 rows needs several calls.

Args: observation_ids (List[int]): 1-250 observation ids. product_id (Optional[int]): Use the product-scoped endpoint instead of the instance-wide one; required for product API tokens. severity, status, priority, clear_priority, vex_justification, risk_acceptance_expiry_date: as in secobserve_assess_observation. comment (str): Mandatory rationale applied to every observation.

Returns: str: A confirmation naming the number of observations submitted and the fields changed. The API returns 204 with no body, so per-observation outcomes are not reported; any id whose previous assessment awaits approval is skipped server-side.

Examples: - Use when: "all 40 findings in this retired branch are resolved" -> observation_ids=[...], status="Resolved", comment="Branch decommissioned ..." - Use when: "these are all the same false positive from the secret scanner" -> status="False positive", vex_justification="component_not_present", comment="..." - Don't use when: the findings need different verdicts (assess them one by one).

Error Handling: Over 250 ids is refused by the schema. 403 means the token lacks Observation_Assessment on one of the products involved -- narrow with product_id. Read-only mode blocks the call.

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.
product_idNoScope the call to one product's endpoint. Omit for the instance-wide endpoint. Pass it when the token is a product API token, which cannot use the instance-wide one.
clear_priorityNoRemove the existing priority. Cannot be combined with priority.
observation_idsYesIds to assess, 1 to 250 per call. Every id gets the same assessment.
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. Changed13 schema fields changedv0.3.0
    • removedInput schema / $defs / BulkAssessInput
      Removed value: -{
-  "additionalProperties": false,
-  "description": "Input model for assessing many observations at once.",
-  "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_ids": {
-      "description": "Ids to assess, 1 to 250 per call. Every id gets the same assessment.",
-      "items": {
-        "type": "integer"
-      },
-      "maxItems": 250,
-      "minItems": 1,
-      "title": "Observation Ids",
-      "type": "array"
-    },
-    "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"
-    },
-    "product_id": {
-      "anyOf": [
-        {
-          "minimum": 1,
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Scope the call to one product's endpoint. Omit for the instance-wide endpoint. Pass it when the token is a product API token, which cannot use the instance-wide one.",
-      "title": "Product Id"
-    },
-    "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_ids"
-  ],
-  "title": "BulkAssessInput",
-  "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_ids
      Added value: +{
+  "description": "Ids to assess, 1 to 250 per call. Every id gets the same assessment.",
+  "items": {
+    "type": "integer"
+  },
+  "maxItems": 250,
+  "minItems": 1,
+  "title": "Observation Ids",
+  "type": "array"
+}
    • removedInput schema / properties / params
      Removed value: -{
-  "$ref": "#/$defs/BulkAssessInput"
-}
    • 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 / product_id
      Added value: +{
+  "anyOf": [
+    {
+      "minimum": 1,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Scope the call to one product's endpoint. Omit for the instance-wide endpoint. Pass it when the token is a product API token, which cannot use the instance-wide one.",
+  "title": "Product Id"
+}
    • 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_ids",
+  "comment"
+]
  2. First observedv0.1.2

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. Beyond this, the description reveals several non-obvious behaviors: the comment is stored on every observation, the API returns 204 with no body (so per-observation outcomes are not reported), ids awaiting approval are skipped server-side, and read-only mode blocks the call. It also discloses a 403 error meaning, which is crucial for troubleshooting. This goes well beyond the annotations and enriches the agent's understanding of side effects and edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with clear sections: an intro sentence, a 'Args' list, a 'Returns' note, 'Examples,' and 'Error Handling.' It front-loads the critical constraint (250 max, identical assessment) and leads with the most important operational advice (getting ids from secobserve_list). Every section earns its place, and the use of bullet points and examples makes it scannable. There is zero fluff or repetition of schema details.

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?

Despite the tool's complexity (9 parameters, bulk action, conditional endpoint choice), the description covers all essential aspects: the one-to-many behavior, how to obtain ids, batching strategy, product-scoped vs instance-wide endpoint, the response's lack of detail, error handling, and example use cases. The output schema is present but the 'Returns' section still clarifies that the API returns 204 with no body, which is critical for setting agent expectations. Nothing an agent needs to invoke this correctly and handle edge cases 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 description coverage is 100%, so the schema already documents every parameter. The description adds valuable context beyond the schema: it states that the comment is written to all observations (reinforcing its mandatory nature) and that severity, status, etc. behave 'as in secobserve_assess_observation,' avoiding repetition. It also explicitly calls out the product_id requirement for product API tokens, which is a practical nuance. The parameter semantics are adequately enhanced without redundancy, earning a 4.

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 opens with a precise, specific statement: 'Apply one identical assessment to up to 250 observations by id.' This clearly distinguishes it from the single-observation sibling (secobserve_assess_observation) by the bulk behavior and the 250-id cap. The tool name and title align perfectly, leaving no ambiguity about its function.

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 tells the agent when to use this tool vs. alternatives: 'Get the ids from secobserve_list...', 'Use when...' for bulk uniform assessments, and 'Don't use when the findings need different verdicts (assess them one by one).' This directly points to the sibling tool for non-uniform cases, providing clear decision criteria. It also gives practical advice on batching more than 250 rows across multiple calls.

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