ti_graph_lookup

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds that this is a live API path call for a single object, but says nothing about behavior for unknown or malformed values, rate limits, or whether results are cached. With annotations carrying the safety burden, a 3 is right.

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, purpose front-loaded, zero redundant phrasing. The raw endpoint paths consume space that could have gone to return-value context, which keeps it from a 5.

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?

There is no output schema, so the description is the only place an agent could learn what a 'graph' lookup returns — WHOIS registrant fields, ASN, related domains? That is left unstated. For a simple two-parameter read tool it is nearly adequate, but the missing return-shape hint is a real gap.

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 100% and the kind enum is documented, so the schema already does the heavy lifting. The description maps kind values to concrete endpoint shapes (ip= vs domain=), which is a small amount of extra meaning but nothing about value formats or validation beyond what the schema states.

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?

States a specific verb and resource: WHOIS/graph enrichment for a single IP or domain, and even names the two concrete endpoints. The second sentence explicitly separates it from the collection tools, so an agent can distinguish it from siblings such as ti_global_search or ti_get_item without reading schemas.

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 line 'describes the object itself rather than the threat records mentioning it' gives a clear selection criterion against the collections family. It stops short of naming an explicit alternative tool or stating a when-not condition (e.g., use ti_global_search for multi-object pivots), so it is strong but not exhaustive.

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