@shieldlabs-ai/mcp

Official

by ShieldLabs-ai

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Explain Risk Score

shieldlabs_explain_risk_score

Read-onlyIdempotent

Explain why an identification received its Risk Score by breaking down the risk band, weighted signals, detection flags, and connection type. Use a request ID or pasted identification.

Instructions

Explain why an identification got its Risk Score: the band (trusted 0-29, suspicious 30-59, dangerous 60-100, or the 999 rate-limit marker), each weighted risk signal with a plain-language meaning from the catalog bundled with this server, the detection flags that are set, the connection type and caveats.

Args:

request_id (string, optional): read the identification from the History API, waiting up to about 10 s for a new one
identification (object or JSON string, optional): explain a pasted identification instead (normalized identification, webhook event or data object, or raw History API row)
response_format ('markdown' | 'json'): default 'markdown' Give exactly one of request_id and identification.

Returns (json): { "request_id": string | null, "risk_score": number, "risk_band": "trusted" | "suspicious" | "dangerous" | "rate_limited", "band_range": string, "band_meaning": string, "signals": [{ name, weight, label, meaning, reading, typical_weight, related_flag, in_catalog }], "detection_flags": [{ flag, label, scored, meaning }], "connection_type": { value, label, meaning } | null, "notes": [string], "source": "history" | "webhook" | "input", "truncated"?: true, "truncation_message"?: string }

A pasted risk_score must be an integer from 0 to 100, or the 999 rate-limit marker, and weights must be integers. Weights come from the identification itself; the catalog's typical weights can change, and signal names outside the catalog are possible. The catalog is also available as the resource shieldlabs://reference/risk-signals.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`request_id`	No	Request ID of the identification to explain, read from the History API (needs SHIELDLABS_API_KEY; waits up to about 10 seconds for a new identification, like shieldlabs_get_identification). Give either request_id or identification.
`identification`	No	An identification to explain without an API call: a normalized identification (for example the json output of shieldlabs_get_identification), a webhook event or its data object, or a raw History API row. A JSON object or its JSON text.
`response_format`	No	Output format: 'markdown' (default) for readable text, 'json' for structured data	markdown

Output Schema

TableJSON Schema

Name	Required	Description
`notes`	Yes
`source`	Yes
`signals`	Yes
`risk_band`	Yes
`truncated`	No	Only present (true) when this server shortened the explanation
`band_range`	Yes
`request_id`	Yes
`risk_score`	Yes
`band_meaning`	Yes
`connection_type`	Yes
`detection_flags`	Yes
`truncation_message`	No	What was shortened: risk signals left out, or long pasted values cut

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Oct 5, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=true. The description adds genuinely useful behavior beyond that: the ~10 s wait for a new identification, possible truncation via truncated/truncation_message, and the caveat that catalog typical weights can drift and out-of-catalog signal names are possible.

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

Conciseness3/5

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

Well front-loaded with the purpose first, then Args and Returns. However, the large Returns block restates the full response shape even though an output schema already exists, so a meaningful portion of the text duplicates structured data rather than earning its place.

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?

Output schema exists, so return values need no further explanation, and all three parameters are documented. The description still covers the pieces an agent needs: latency, truncation, the 999 rate-limit marker, band ranges, catalog drift caveats, and a pointer to the shieldlabs://reference/risk-signals resource.

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 baseline is 3. The description goes beyond the schema by adding the mutual-exclusion constraint ('exactly one of request_id and identification') and the validity rule that a pasted risk_score must be an integer 0-100 or the 999 marker with integer weights — constraints not encoded in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Explain why an identification got its Risk Score') and enumerates exactly what is explained: band, weighted signals, detection flags, connection type, caveats. The purpose is unmistakable and functionally distinct from shieldlabs_get_identification, but no sibling is named in the description itself, so the differentiation is only implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete operating rule — 'Give exactly one of request_id and identification' — and explains the two modes: reading from the History API versus explaining a pasted identification. It does not state when to prefer this tool over shieldlabs_get_identification or shieldlabs_search_history, so exclusions are absent.

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

Deploy Server