Pivotal Entities

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable caveats beyond annotations: it explicitly warns that betweenness is an 'ego-bridge heuristic, not exact Brandes' and instructs not to present results as exact betweenness, noting the response carries this in `note`. This is genuine behavioral disclosure well beyond what annotations provide.

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?

Two sentences, efficient and front-loaded. The first sentence establishes what the tool returns and the ranking; the second delivers the critical caveat about betweenness. No wasted words. It loses one point because the caveat is placed at the end, slightly reducing the immediate clarity of the safety-critical warning, though the structure is overall tight.

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?

The tool has an output schema (so return values need no description), two simple parameters, and rich annotations covering read-only/idempotent/destructive profile. Given this context, the description adequately explains the ranking semantics and the heuristic caveat. It's complete for a read-only ranked-list tool; a minor gap is not explaining the node_type filtering behavior in the description.

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 description coverage is 50%, meaning the limit parameter is described (default 25, max 100) in the schema while node_type is described only via its enum values. The description doesn't add parameter-level detail beyond the schema — it doesn't explain how node_type filters results or how limit interacts with ranking. With 50% coverage, the description carries some compensation burden but mostly remains silent on parameter semantics.

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 states the tool retrieves 'the hubs and bridges of the intelligence graph' ranked by 'weighted degree and approximate betweenness.' It uses a specific verb (get) plus a well-defined resource (pivotal entities = hubs/bridges) with explicit ranking criteria. This meaningfully distinguishes it from siblings like get_infrastructure_pivots or get_correlation_path.

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 implies usage: to identify high-coverage nodes in the intelligence graph where a detection buys maximum coverage. It frames the 'when to use' clearly ('where a single detection buys the most coverage'), but it does not explicitly say when NOT to use it or name alternative tools for specific scenarios. The node_type parameter suggests filtering by entity type, but the description doesn't guide which type to pick.

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