Entity Profile

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds genuinely useful behavior beyond those annotations: NPMI edges carry raw pmi/co-occurrence/marginal values, rarity is defined in terms of corpus_df vs corpus_n, and top_neighbors_truncated can hide low-fidelity neighbors unless limit is raised. This is transparent about an easy-to-misread response behavior.

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

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

The description is front-loaded and information-dense: the first sentence defines the core purpose, and the following sentences add high-value details like the NPMI payload, rarity semantics, and truncation caveat. It is somewhat long and technical, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, annotations, a moderate parameter list, and strong parameter descriptions, the description supplies the missing context about return content, edge fields, rarity interpretation, and pagination/limit caveats. For a complex intelligence-graph endpoint, nothing essential for correct invocation appears to be missing.

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

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

Schema coverage is 67%, with node_id and limit already described, and node_type sufficiently conveyed by its enum. The description adds real parameter value: it explains how limit interacts with fidelity ordering, which matters because low-fidelity edges are the first dropped. It also contextualizes the node_id values across node types. This exceeds the baseline without fully replacing the schema's per-parameter detail.

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

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

The description clearly identifies the tool as a one-call dossier for any intelligence-graph node, naming the supported node types (threat, technique, actor, IOC, CVE). It distinguishes itself from the many sibling getters such as get_threat/get_actor/get_cve by claiming to replace five or six separate lookups, so an agent can select it with confidence.

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

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

The description states when to use it: when a consolidated overview with neighbors, rankings, and type-specific rollups is needed, and that it is the best token-per-call option in the graph family. It also gives practical guidance about checking top_neighbors_truncated and raising limit before concluding a neighbor is absent. It does not explicitly name alternatives or give when-not-to-use conditions, so it falls just 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.