IOC DNS Enrichment

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds meaningful context beyond these annotations: it clarifies that the data is 'previously resolved and cached' and explicitly flags that this is NOT a live lookup — a key behavioral caveat not captured by any annotation. Minor deduction for not describing the output format beyond 'reverse-IP and subdomain records.'

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 three sentences and tightly written with zero filler. It front-loads purpose in the first sentence, adds the critical non-live caveat in the second, and points to the alternative in the third. Every sentence earns its place. Minor deduction only because the parenthetical 'reverse-IP and subdomain records' could arguably be integrated more cleanly, but this is essentially optimal.

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 is a simple single-parameter read operation with comprehensive annotations (readOnly, idempotent, non-destructive) and an output schema present, the description is largely complete. It covers the stored-vs-live distinction, the input scope, and points to the richer sibling. Context signals show only 1 parameter, 100% schema coverage, and presence of an output schema, all of which reduce the descriptive burden. Could add pagination/limits info for many-record DNS results, but that's speculative.

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 100%, and the single required parameter 'value' has a clear description ('IP address or domain'). The main description reinforces the acceptable input types. Since the schema already documents the parameter fully, the baseline of 3 applies — the description adds slight value by phrasing it as 'stored DNS enrichment lookup' but not much beyond schema. There's only 1 parameter, so there's little semantic ambiguity to resolve.

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 what the tool does: 'Return stored DNS enrichment for an IP or domain indicator.' It specifies the resource (stored DNS enrichment), the scope (IP or domain), and explicitly differentiates from siblings ('Use get_ioc_intelligence for the full stored dossier'). The verb 'Return' plus resource is specific and unambiguous.

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 explicitly notes this is a read of stored/cached data, NOT a live lookup at call time, which prevents misuse. It also names the alternative get_ioc_intelligence for a fuller dossier, giving clear when-to-use vs when-not guidance. This is exceptional usage guidance for a retrieval tool.

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