Entity Profile

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe read. The description adds modest extra context: token efficiency ('best token-per-call ratio') and the concept of 'edge fidelity' and 'consensus/rarity' rollups, which hint at reconciliation quality of the returned data. However, it doesn't disclose pagination, return size limits, or behavior for nodes not found in the graph, gaps that would add value beyond annotations.

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 a tight three-sentence block with front-loaded purpose, a detailed but dense payload list, and a value-proposition closing line. Every sentence earns its place. It could arguably trim the marketing phrasing ('Best token-per-call ratio') slightly, but overall it is appropriately sized with efficient structure.

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?

With an output schema present and read-only annotations covering the safety profile, the description provides sufficient context: purpose, payload breakdown, token efficiency, and supported node types. Given the tool's moderate complexity (2 params, single node profile aggregation), the description is reasonably complete. Minor gaps like behavior on unknown node_ids and pagination limits are the only missing pieces.

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 50%: node_type has an enum listing five types (well covered), while node_id's description covers the formats ('TL- id, T-number, actor name, IOC value, or CVE id'). The description adds the scope of aggregation per type but doesn't add meaning materially beyond what the schema already states for the two parameters. The high-level dossier framing is about output, not parameter semantics, so baseline 3 is appropriate for the 50% coverage case.

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?

Description uses a specific, vivid framing ('One-call dossier for any node in the intelligence graph') and enumerates exactly what the tool returns: centrality/pivot rank, top graph neighbours with edge fidelity, and type-specific rollups. It distinguishes itself from siblings by framing as a consolidated 'dossier' replacing five or six separate lookups, and lists the five supported node types (threat, technique, actor, IOC, CVE).

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 makes its use case clear: a consolidated cross-type lookup for any graph node that replaces multiple separate lookups, and explicitly names the return coverages (threats, techniques, IOCs, campaigns, CVEs). However, it does not explicitly state when NOT to use it or name alternatives for single-type deep dives (e.g., get_threat, get_cve, get_actor_intelligence), which would differentiate it more sharply from siblings.

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