Skip to main content
Glama
luiacuaniello

PerspectiveGraph

by luiacuaniello
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Hybrid

search_assets

Read-onlyIdempotent

Resolve a mentioned asset or finding name into matching node IDs by searching indexed names, CVE IDs, and keywords for other PerspectiveGraph tools.

Instructions

Full-text search across indexed assets and findings by name, CVE id, or keyword. Use it to resolve a name a human mentioned into the node ids the other tools take. It needs OpenSearch on the deployment: where that is off it answers with an error saying so, never with an empty list, and get_posture and list_attack_paths are then where names come from. It returns the best size matches and has no further page: narrow the query instead.

Input Schema

NameRequiredDescriptionDefault
sizeNoMaximum number of matches to return, best match first.
queryYesText matched against asset and finding names, labels, ids, severities and CWEs, e.g. 'log4j', 'PII', 'CVE-2021-44228'.

Output Schema

NameRequiredDescriptionDefault
searchYesThe matches, best first. Empty when nothing matches.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.38.1
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "search": {
+      "description": "The matches, best first. Empty when nothing matches.",
+      "items": {
+        "properties": {
+          "id": {
+            "description": "Node id: usable as `target` or `from` in routes_to_target and in simulate_fix cuts.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "label": {
+            "description": "Its type, e.g. Container, IAM_Role, CVE.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "name": {
+            "description": "Asset or finding name.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "score": {
+            "description": "Relevance of the match. Comparable only within one result.",
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        },
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "search"
+  ],
+  "type": "object"
+}
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds substantial non-obvious behavior: a hard dependency on OpenSearch, that the disabled case returns an error rather than an empty list, and that results are non-paginated so the query must be narrowed instead.

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?

Four sentences ordered purpose → routing use case → deployment failure mode → result limits, with zero filler. The failure-mode caveat is placed exactly where a caller would look for it, and nothing is restated from the schema.

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?

An output schema exists so return shape need not be described; the description still covers the error-vs-empty distinction, the deployment prerequisite, and non-pagination behavior. For a two-parameter read tool this leaves no meaningful gap for correct invocation.

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 100%, so the schema already documents both parameters, making 3 the baseline. The description earns above baseline by clarifying `size` semantics: results are best-match-first and there is no further page, so callers must narrow the query rather than raise size to page through.

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+resource (full-text search across indexed assets and findings) and the match fields (name, CVE id, keyword). It explicitly separates itself from siblings by naming get_posture and list_attack_paths as the alternative source of names when OpenSearch is off.

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 an explicit primary use case — resolve a human-mentioned name into the node ids other tools take — and an explicit when-not path: if OpenSearch is disabled, get_posture and list_attack_paths are where names come from. No routing is left to inference.

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

Deploy Server

Other Tools