Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server provides 5 tools with basic structure, but falls short on several critical quality dimensions. Tool descriptions are present but generic (18-58 chars, well below the 50-200 char ideal for LLM optimization). Parameter descriptions are missing or minimal across most tools. Input schemas are present and mostly well-typed, but lack depth in descriptions. Error handling is basic, no recovery guidance, no categorization of errors as retryable vs. fatal. Output schemas are not explicitly documented. The naming convention follows verb_noun style appropriately (whois_lookup, dns_lookup, etc.), but parameter naming has issues, 'query' vs 'domain' inconsistency between tools, and no human-friendly resolution (e.g., accepting domain names vs. IPs without explicit type hints). Cache-clearing tool (clear_dns_cache) lacks documentation about side effects. No tool annotations (readOnlyHint/destructiveHint/idempotentHint) present. Overall, the server provides functional tools but lacks the LLM-optimized descriptions, parameter depth, and error guidance needed for reliable agent composition.
Tools (5)
clear_dns_cachewrite50/100
Clear the DNS lookup cache
dns_lookupread only50/100
Look up DNS records for a domain (A, AAAA, MX, TXT, NS, CNAME, SOA, SRV)
dns_lookup_batchread only50/100
Look up multiple DNS records for a domain in a single query
dns_reverse_lookupread only50/100
Perform reverse DNS lookup on an IP address
whois_lookupread only50/100
Look up WHOIS information for a domain, IP address, or ASN
Tool descriptions are too generic and lack LLM-optimization context (18-64 chars vs. 50-200 char ideal). Descriptions do not answer WHEN to use each tool instead of similar ones (whois_lookup vs. dns_lookup distinction not explained), WHAT is returned, or any prerequisites.
Parameter descriptions are missing or minimal across all tools. Most param descriptions are single clauses ('Domain to look up', 'IP address to perform reverse lookup on') with no format constraints, valid ranges, or examples. Parameters like 'domain' vs 'query' are used inconsistently across tools, forcing LLM to reason about subtle naming differences.
Output schemas are not documented. Code shows raw_output and parsed_fields in whois responses, but no LLM-facing schema definition for return values. Agents cannot plan downstream tool calls or extract expected fields without documented return structure.
Recommendations
Expand tool descriptions to 80-150 chars, explicitly answering: WHAT does it do? WHEN to use it vs. similar tools? WHAT does it return? Example: 'whois_lookup: Retrieve registration and administrative info for a domain, IP address, or autonomous system number. Use when you need owner/registrar details; use dns_lookup for zone/nameserver info. Returns raw output plus parsed fields (registrar, expiry, nameservers, etc.). Returns error if query times out or is invalid.'
Add comprehensive parameter descriptions with format/range constraints: 'domain' should specify 'Valid fully-qualified domain name (e.g., example.com)'; 'record_type' already has enum but could add 'Defaults to A if omitted'; 'ip_address' should add 'IPv4 or IPv6 address; will auto-detect format'.
Document return schemas for each tool. For dns_lookup, specify: '{"records": [{"type": string, "values": [string], "ttl": int}], "authority": [string]}'. For whois_lookup: '{"query": string, "raw_output": string, "parsed_fields": {[key: string]: string | [string]}, "timestamp": string, "error": string (if failed)}'.
Add error recovery guidance in descriptions and handle errors in code: (1) Timeout errors: 'Whois lookup timed out (>10s). The domain or ASN may be unresponsive. Try dns_lookup() instead, or retry in a few seconds.' (2) Invalid input: 'Invalid query format. Provide a valid domain (example.com), IPv4 (192.0.2.1), IPv6 (2001:db8::1), or ASN (AS12345).' (3) Not found: 'No WHOIS record found. The domain may be brand-new, private, or invalid. Verify the spelling and try again.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Error handling is absent or minimal. No error recovery guidance (e.g., 'Domain not found. Try a different domain or use whois_lookup() for IP-based info.'). No error categorization (retryable vs. user-fixable vs. fatal). Code shows timeout handling and generic 'Internal error' messages that give LLMs nothing actionable to do next.
clear_dns_cache is a destructive WRITE tool but has no destructiveHint annotation, no confirmation step, and minimal description of scope/side-effects. Description lacks indication that this is a side-effecting operation. No guidance on when agents should call it.
Parameter naming inconsistency: 'whois_lookup' uses 'query' (ambiguous, could be domain, IP, or ASN), while 'dns_lookup' and others use 'domain'. LLM must reason about semantic differences when naming should make them obvious. No type-suffixed naming (query_type, domain_name, ip_address_type) to disambiguate.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) present. Code indicates all DNS tools are READ_ONLY and whois is READ_ONLY, but this is not exposed in the schema. clear_dns_cache is WRITE but unmarked. Agents cannot plan safely without knowing tool side-effects.
Add destructiveHint annotation to clear_dns_cache. Expand description to: 'Clear all cached DNS records from local disk cache (~/.cache/domain-lookup-mcp). This is a destructive operation, all cached data will be lost, forcing fresh queries on next lookup. Use only if cache is stale or corrupted. Returns count of records cleared.'
Rename 'whois_lookup' parameter from 'query' to 'whois_query' or split into 'domain' and 'asn' params with clear mutual-exclusivity documentation. Or keep 'query' but add detailed description: 'WHOIS query string: a domain name (example.com), IP address (192.0.2.1, 2001:db8::1), or ASN (AS12345, 12345). Format is auto-detected.'
Add readOnlyHint annotation to whois_lookup, dns_lookup, dns_lookup_batch, dns_reverse_lookup. This signals that agents can safely retry these tools.
Consider adding idempotentHint to dns_lookup and dns_lookup_batch, repeated calls with same inputs return same results (or cached results), supporting safe retries.
Add examples in descriptions sparingly and correctly: Instead of 'e.g., A, AAAA, MX', use the enum field (already done well for record_type). Avoid concrete example values like 'example.com' unless absolutely necessary, LLMs tend to reuse them literally.
Add batch_lookup guidance: 'dns_lookup_batch is more efficient than calling dns_lookup multiple times for the same domain with different record types. Use dns_lookup_batch for 2+ record types on one domain; use dns_lookup for single record type or different domains.'
Document caching behavior and TTL in tool descriptions: 'Results are cached locally for 24 hours with automatic expiry. Use clear_dns_cache() if you need to force a fresh lookup sooner.'
Add per-item error reporting for batch operations (dns_lookup_batch): If record_type 'UNSUPPORTED' is requested, return '[{"type": "UNSUPPORTED", "error": "Unsupported record type. Valid types: A, AAAA, MX, TXT, NS, CNAME, SOA, SRV"}]' rather than blanket failure.