secobserve-mcp

Read SecObserve Metrics

secobserve_product_metrics

Read-onlyIdempotent

Read pre-aggregated vulnerability and license counts for a product, group, or instance. Use current, timeline, or status to review counts, trends, or metric freshness.

Instructions

Read pre-aggregated observation and license counts for a product, a group, or the whole instance.

Far cheaper than counting rows with secobserve_list: these come from the metrics tables a background job maintains. That also means they are as old as the last calculation -- kind="status" tells you how old, and is worth reading before quoting a number as current.

Args: params (MetricsInput): Validated input containing: - kind (str): "current", "timeline" or "status". - product_id (Optional[int]): One product, or every product in a group when the id is a product group. Omit for the instance. - age (Optional[MetricsAge]): Window for "timeline": "Past 7 days", "Past 30 days", "Past 90 days", "Past 365 days". - response_format (ResponseFormat): "json" (default) or "markdown".

Returns: str: For kind="current", a JSON object of counts keyed by severity (open_critical, open_high, ...) and by license evaluation result. For kind="timeline", a JSON object keyed by ISO date, each value the counts for that day. For kind="status", {"last_calculated": ISO timestamp, "calculation_interval": minutes}.

Examples: - Use when: "how many critical findings are open in product 12?" -> kind="current", product_id=12 - Use when: "is our backlog growing?" -> kind="timeline", age="Past 90 days" - Use when: a metric looks wrong -> kind="status", to check the job has run. - Don't use when: you need the findings themselves (use secobserve_list).

Error Handling: 403 means no view permission on the product. An empty timeline usually means the metrics job has not run yet for that window -- check kind="status".

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes further by explaining that data is pre-aggregated and stale (as old as last calculation), how to detect staleness via kind='status', and error semantics (403 for no permission, empty timeline meaning job not run). This adds substantial behavioral context beyond 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 description is well-structured with clear sections (main purpose, Args, Returns, Examples, Error Handling). Every sentence earns its place: the cost advantage is front-loaded, and the examples and error handling are concise but instructive. No filler or redundancy.

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 read-only metrics tool, the description covers the return format for each kind, explains when staleness matters, provides usage guidance, and addresses error cases. It leaves nothing an agent needs to call the tool correctly, even without relying on the output schema (which is also present).

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 provides rich descriptions for all parameters (kind, product_id, age, response_format) with 100% coverage, so the baseline is 3. The description's 'Args' section restates these but adds practical guidance (e.g., omitting product_id for instance, age only for timeline) and concrete usage examples that map intents to parameter choices, elevating it to 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 states a specific verb and resource ('Read pre-aggregated observation and license counts') and immediately differentiates from secobserve_list by noting cost efficiency. It clearly covers the three scopes (product, group, instance) and three kinds, making the tool's purpose unambiguous.

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?

Explicit 'Use when' and 'Don't use when' examples map natural-language queries to parameter values, and it names the sibling tool (secobserve_list) as the alternative when raw findings are needed. It also advises checking kind='status' before quoting a number as current, covering a real edge case.

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

Deploy Server