secobserve-mcp

Bulk Assess SecObserve Observations

secobserve_bulk_assess_observations

Apply a single assessment, including mandatory comment, status, severity, priority, and VEX justification, to up to 250 observations at once to triage identical findings in bulk.

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: params (BulkAssessInput): Validated input containing: - 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, 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

Name	Required	Description	Default
`params`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.2Sep 17, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations say readOnlyHint=false and destructiveHint=false, so the agent already knows it mutates but is not destructive. The description adds exactly the behavioral context the annotations do not: the comment is stored on every observation, per-observation outcomes are not reported because the API returns 204 with no body, ids are skipped server-side when the previous assessment awaits approval, the 403 permission nuance, and read-only mode blocking the call. No contradiction with the annotations.

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 one-line definition is front-loaded, followed by well-labeled Args/Returns/Examples/Error Handling sections. Every sentence carries a distinct fact (id source, 250 max, 204 no-body, 403 meaning, read-only block, same-verdict warning). No filler.

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 batch mutation tool with three annotations, this description is exhaustive on limits, return behavior, auth/scope, and failure modes. The output schema declares 'Returns: str', and the description complements it by explaining there is no per-observation detail. Nothing needed to call this 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?

Schema coverage is 0%, so the description carries the full parameter burden, and it largely does: it clarifies observation_ids scope (1-250), the product_id endpoint-scoping semantics, and that comment must be true of the whole set. It names severity/status/priority/vex_justification/risk_acceptance_expiry_date by referring to secobserve_assess_observation rather than duplicating their full meaning. This delegation works only if the agent has that sibling's docs, so it is slightly less than 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 ('apply'), a precise resource ('one identical assessment to up to 250 observations by id'), and the limit. It differentiates from sibling secobserve_assess_observation by calling out the batch action and the 250-id cap. No need to open the schema to know what this does.

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 when-to-use examples, a don't-use-when condition, and an explicit alternative (assess findings needing different verdicts one by one). It also tells the agent where to get ids (secobserve_list with fields=['id']) and how to paginate. This is fully actionable selection guidance.

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

Deploy Server