Skip to main content
Glama

Scan a host's exposed stack

observe
Read-only

Scan a host's exposed stack and join it to the CVE corpus — the recon workhorse. Fingerprints the homepage + JS bundles (recovering the backend identity and API endpoints homepage detection misses on SPAs), then ranks against live KEV / SSVC-active / high-EPSS into a dig-order. Fetches only public pages.

NON-BLOCKING: a scan takes ~1-4 min, so observe() never waits on it. A recent scan (<24h) returns status="ready" instantly. A cache miss KICKS a background scan and returns status="scanning" immediately — POLL by calling observe() again with the same host until it returns status="ready". Returns:

  • status="ready": host stack + endpoints + dig_order + top_across_stack (the scan result), plus bounty_programs: public programs whose current scope lists this host.

  • status="scanning": retry_after_seconds + last_scanned_at (call again after that delay).

  • status="error": a guard/validation error.

Args: host: hostname or URL, e.g. "auth.example.com". fresh: force a re-scan (kicks a new background scan even if a recent one exists). per_tech: top CVEs to surface per component (default 4).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "host": "<host>"
    },
    "name": "observe"
  }
}

Input Schema

NameRequiredDescriptionDefault
hostYes
freshNo
per_techNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only say readOnly/openWorld; the description adds the material behavior the agent cannot otherwise know: non-blocking execution, 1-4 min scan duration, 24h cache TTL, the three possible status values with their payloads, retry_after_seconds, and that only public pages are fetched. This is exactly the async/polling contract an agent needs before calling.

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

Conciseness4/5

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

Front-loaded with purpose, then a clearly signposted NON-BLOCKING block and a status-by-status return listing — easy to scan, every segment useful. Minor slack in the 'recon workhorse' framing and some parenthetical restatement, but nothing meaningfully wasteful.

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?

No output schema exists, and the description compensates fully by enumerating the returned fields per status (stack, endpoints, dig_order, top_across_stack, bounty_programs, retry_after_seconds, last_scanned_at). For a 3-parameter async tool this is complete enough to invoke and interpret correctly.

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?

Schema coverage is 0%, so the description must carry the load and does: host accepted as hostname or URL with an example, fresh documented as forcing a new background scan even when a recent one exists, and per_tech defined as top CVEs surfaced per component (default 4). No parameter is left ambiguous.

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 concrete verb+resource: fingerprints a host's homepage and JS bundles, joins the result to the CVE corpus, and ranks against KEV/SSVC/EPSS. The scope ('recovering backend identity and API endpoints homepage detection misses on SPAs') tells an agent exactly what this does that a plain technology check would not.

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 clear operational protocol: call once, poll with the same host until status='ready', use fresh to force a re-scan when a stale cached result is not acceptable. It does not explicitly name alternatives (e.g. check_technology or search_vulns) or state when not to use it, so it stops short of a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.