Inconsistent tool naming conventions. Mix of verb_noun (do_alterx, do_arjun) and noun-first (crtsh, httpx, amass). 'do_' prefix is redundant, FastMCP already registers as a tool. Names like 'crtsh', 'httpx' lack action verbs entirely, forcing LLMs to infer intent from context rather than the name alone.
Output schemas are not documented. Tools return raw subprocess stdout/stderr as strings (e.g. 'alterx completed successfully' concatenated with command output). LLMs cannot infer structured output fields or know what to extract for downstream tool chaining. Missing response shape documentation violates the 'document the output schema' rule.
Rename tools to consistent verb_noun pattern: 'enumerate_subdomains_assetfinder', 'scan_http_headers', 'list_nuclei_tags', 'upload_mobile_app', 'scan_mobile_app', 'get_mobile_scan_logs'. Remove 'do_' prefix; FastMCP registration handles tool declaration. Names should convey action + target at a glance.
Document output schemas for all tools. Example for 'do_alterx': 'Returns object {domains: string[], pattern_used: string, count: integer, error: string|null}'. For passthrough tools (nmap, amass), parse CLI output into structured JSON: {open_ports: [{port: int, service: string}], hosts_scanned: int}. Include this in code as a @dataclass or TypedDict.
Enhance parameter descriptions with actionable constraints. Format: '[WHAT] [WHEN] [FORMAT] [EXAMPLE] [CONSTRAINT]'. Example: 'Target domain name. Use to specify which domain to enumerate. Format: apex domain without protocol (e.g., example.com, not https://example.com or 1.1.1.1). Required.'
Add error handling with recovery guidance. Catch subprocess exceptions, validate inputs early, return structured errors: '{"error": "invalid_domain", "message": "Domain must match pattern ^[a-z0-9.-]+$", "recovery": "Check domain spelling and try again or use do_assetfinder to discover valid domains"}'.
Document pagination and result limits. Add optional 'limit' and 'offset'/'cursor' parameters where applicable. Amend tool descriptions: 'Returns up to 50 results per call. Use pagination to retrieve additional domains.'
Add workflow hints to descriptions. For domain discovery tools, append: 'Output can be passed to httpx (target), do_nmap (target), or do_ffuf (url). Call this first in reconnaissance workflow.' For scanning tools, note prerequisites.
Parameter descriptions lack actionable constraints. Example: 'target' in do_assetfinder is 'The root domain (e.g., example.com)'. Missing: format (must be domain, not IP or URL?), required behavior if invalid, interaction with other params. Descriptions should specify 'domain name without protocol (e.g., example.com, not https://example.com)'.
Minimal/generic parameter descriptions. 'get_nuclei_tags' has an empty input schema and description 'Get Nuclei Tags'. 'do_nmap' description is 'Run nmap with specified target' (13 chars). 'crtsh' description 'Discovers subdomains from SSL certificate logs' (46 chars) lacks WHEN to use it vs. other subdomain tools, prerequisites, rate limits, or output expectations.
No error handling guidance. Tools catch exceptions and return raw error messages: 'Failed to start alterx: {str(e)}'. No categorization (retryable vs. fatal), no recovery hints, no invalid-input self-correction guidance. An LLM hitting 'Amass exited with code 1' has no next-step direction.
No pagination or result limiting documented. Tools like 'amass', 'do_katana', 'httpx' can return hundreds of results, but no mention of limits, pagination params, or how to bound output. Returning unbounded result sets risks context window exhaustion.
Parameter dependency not documented. 'amass' has conditional logic: intel_whois is 'required' for domain intel but the schema doesn't mark it as required or explain the condition. LLMs will pass the domain without whois, hitting a validation error.
Missing dependency hints between tools. Users need to enumerate domains before scanning them, but no tool description hints at the workflow (e.g., 'Call do_assetfinder or amass first to discover domains, then pass results to httpx or do_nmap'). Multi-step agent plans require explicit guidance.
Tool naming mixes patterns: some start with 'do_', some with verbs (analyze_http_header, get_nuclei_tags, scanFile, uploadFile, getScanLogs), others are nouns (amass, crtsh, httpx). This inconsistency forces LLMs to pause and reason about naming convention before understanding tool purpose.
Raw command output returned as-is. Tools like 'do_alterx', 'amass', 'do_nmap' return unstructured subprocess output concatenated with status text. No parsing, structuring, or field extraction. LLMs must parse raw CLI output, error-prone and wasteful.
Consolidate enum constraints in parameter definitions. For methods (GET, POST, JSON, HEADERS), already done in do_arjun, replicate this pattern for strategy (depth-first/breadth-first in do_katana) and enum_type (active/passive in amass).
Add parameter interdependency documentation. For 'amass', state in description: 'For intel+domain: intel_whois required (true). For intel+organization: intel_whois optional. For enum: intel_whois ignored.' Make conditional logic explicit.
Strip internal metadata from responses. Parse JSON/CSV from tool output, filter to user-facing fields, discard CLI version strings and debug output. Example: if 'amass' returns raw JSON, extract only {subdomain: string, source: string, ip: string}, drop internal timing, cache metadata, and API IDs.
Add explicit tool selection guidance. For competing tools (do_assetfinder vs. amass vs. crtsh), document: 'assetfinder: broad domain correlation (fast, passive). amass: deep OSINT with WHOIS/active enum (slower, thorough). crtsh: SSL certificate logs only (real-time cert transparency).' Help LLMs pick the right tool for the intent.