secobserve-mcp

Run SecObserve Background Task

secobserve_run_periodic_task

Trigger a scheduled background job now to refresh stale metrics, or list registered task names to run later.

Instructions

Trigger one of SecObserve's scheduled background jobs now, or list which jobs exist.

Useful when a metric looks stale or housekeeping has not run. The task is queued, not executed inline: the call returns immediately and the outcome shows up in secobserve_list(resource="periodic_tasks"). Only one instance of a task runs at a time.

Args: task (Optional[str]): Registered task name. Omit to list the accepted names without running anything.

Returns: str: With no task, a JSON array of registered task names. With a task, a confirmation that it was queued and a pointer to the periodic_tasks resource for its outcome.

Examples: - Use when: "what background jobs can I run?" -> task omitted - Use when: "recalculate the metrics now" -> task="calculate_product_metrics" (confirm the exact name from the listing first). - Don't use when: you want to know whether metrics are stale (use secobserve_product_metrics with kind="status").

Error Handling: 400 means the name is not registered -- call without 'task' for the list. 409 means that task is already running; wait for it rather than retrying. Requires superuser; a product token gets 403.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`task`	No	Registered task name. Omit to list the names this instance accepts instead of running anything.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.3.0Sep 20, 2026

removedInput schema / $defs

Removed value: -{
-  "RunPeriodicTaskInput": {
-    "additionalProperties": false,
-    "description": "Input model for triggering a background task.",
-    "properties": {
-      "task": {
-        "anyOf": [
-          {
-            "maxLength": 100,
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Registered task name. Omit to list the names this instance accepts instead of running anything.",
-        "title": "Task"
-      }
-    },
-    "title": "RunPeriodicTaskInput",
-    "type": "object"
-  }
-}

addedInput schema / additionalProperties
```
Added value: +false
```

removedInput schema / properties / params

Removed value: -{
-  "$ref": "#/$defs/RunPeriodicTaskInput"
-}

addedInput schema / properties / task

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 100,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Registered task name. Omit to list the names this instance accepts instead of running anything.",
+  "title": "Task"
+}

removedInput schema / required
```
Removed value: -[
-  "params"
-]
```

First observedv0.1.2Sep 17, 2026

TDQS

A5/5.0

Behavior5/5

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

The description goes beyond the annotations by disclosing that 'the task is queued, not executed inline', that the call 'returns immediately', that only one instance runs at a time, and that errors map to 400/409/403 with auth requirements. No contradiction exists 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 definition is front-loaded with a one-sentence purpose and then organized into Args, Returns, Examples, and Error Handling. Each section contributes distinct, useful information without redundancy or 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 single-optional-parameter tool with an output schema and annotations, the description covers purpose, invocation variants, return behavior, error handling, auth, and alternatives. Nothing needed to select or call the tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though the schema already documents task at 100% coverage, the description adds practical meaning: omitting task lists accepted names, running requires 'confirm the exact name from the listing first', and it gives the concrete example 'calculate_product_metrics'. It also ties task validity to specific error codes.

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 'Trigger one of SecObserve's scheduled background jobs now, or list which jobs exist,' a specific verb-resource pairing that clearly defines the tool. It also distinguishes itself from siblings by naming secobserve_list(resource='periodic_tasks') and secobserve_product_metrics, so an agent can tell it apart.

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?

It states exactly when to use: 'Useful when a metric looks stale or housekeeping has not run' and gives explicit don't-use guidance with an alternative: 'Don't use when you want to know whether metrics are stale (use secobserve_product_metrics with kind="status")'. The examples for listing vs running also clarify invocation context.

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

Deploy Server