HIGH: Multiple tools with minimal descriptions (list_active_scans, medusa_init, medusa_update_config, list_recent_searches, boofuzz_list_scripts, get_scan_results). Descriptions under 50 chars do not provide LLMs with sufficient context to decide when to call the tool or what to expect.
Recommendations
Add explicit permission checks to all write operations (medusa_init, medusa_update_config, boofuzz_create_script, boofuzz_run_fuzzer). Implement a permission-gate pattern: before executing, verify caller has scope (e.g. 'write:blockchain_tests' or 'execute:fuzzer'). Return a clear 403 with required scope if denied.
Implement target validation and scope boundaries for reconnaissance tools (masscan_scan, masscan_top_ports). Define an allow-list of target ranges (e.g. internal lab subnets only). Reject scans outside the scope with a 403 error and explanation of approved targets.
Add rate limiting to network-facing tools (masscan_scan, boofuzz_run_fuzzer). Enforce per-agent quotas (e.g. max 3 concurrent scans, max 10/minute) to prevent runaway fuzzing campaigns.
Expand all short descriptions to 50-150 chars. For list_active_scans, change 'List running analyses' to 'List all currently active binary capability analyses with their scan IDs, start times, and completion status.' For get_scan_results, clarify what type of results are retrieved.
Document all output schemas explicitly. For capa_analyze, publish: {scan_id: string, filepath: string, status: 'completed'|'failed'|'timeout', capabilities: [{name, namespace, attack_ids, mbc_ids}], stats: {total_capabilities, by_namespace, attack_techniques}}. For medusa_fuzz, document the structure of coverage_report and crash_results.
Add min/max constraints and units to all numeric parameters. medusa_fuzz workers: 1-16 (integer, count of parallel workers). masscan_scan rate: 100-100000 (int, packets per second). Timeout params: 10-3600 (integer, seconds).
HIGH: No output schemas documented. Tools return structured data (scan results, analysis findings) but the code does not specify what fields agents should expect. This forces LLMs to guess field names for downstream composition.
HIGH: Parameter descriptions are sparse or missing. Many tools accept critical parameters (timeout, rate, workers, target-contracts) with no description of valid ranges, units, or constraints. E.g., medusa_fuzz 'rate' has no min/max; timeout lacks time-unit clarity.
MEDIUM: Error handling is generic and non-actionable. Code uses try-except blocks but returns minimal guidance. E.g., 'File not found' for capa_analyze gives no suggestion to check path; no recovery steps offered.
MEDIUM: Duplicate tool names across modules (list_active_scans appears in binary-analysis and reconnaissance; get_scan_results has ambiguous naming). LLMs will conflate these and may call the wrong tool module.
MEDIUM: Complex parameter structures (medusa_fuzz with 15+ optional parameters) lack clear dependencies and interaction rules. Documentation does not specify which parameter combinations are valid or mutually exclusive.
MEDIUM: File path parameters (boofuzz_create_script script_name, dharma_generate grammar_path) do not validate or sanitize input. No path traversal checks visible. An agent could write files outside intended directories.
MEDIUM: Timeout parameters lack explicit units and ranges. capa_analyze and boofuzz_run_fuzzer both accept timeout as integer but do not specify if it is seconds, milliseconds, or specify min/max bounds.
capa_analyzeboofuzz_run_fuzzermasscan_scan
Rename or qualify duplicate tools. Change reconnaissance list_active_scans to list_active_scans_network or get_network_scan_results to get_scan_results_network to avoid LLM confusion.
Implement structured error responses following the error-classification pattern. On file not found, return: {error_code: 'FILE_NOT_FOUND', message: 'File /path/to/binary not found', hint: 'Check the file path exists and is readable. Use absolute paths or provide a relative path from the working directory.', retryable: false}.
Add parameter dependency documentation. For medusa_fuzz, document: 'If config is provided, it overrides individual parameters (workers, seq-len, test-limit). If config is omitted, all parameters apply. Either provide config OR explicit parameters, not both.'
Implement input validation and path traversal guards. For boofuzz_create_script, validate script_name contains only alphanumeric and underscores. Reject any script_name containing '/' or '..' to prevent directory traversal.
Add dry-run support to destructive operations. Modify boofuzz_run_fuzzer to accept a 'dry_run' boolean param. When true, validate the script and target connectivity without executing the actual fuzzing payload. Return a summary of what would be fuzzed.
Include query IDs and references in all list/search responses. searchsploit_search results should include edb_id alongside each exploit entry so agents can immediately call searchsploit_examine without an extra lookup.
Add pagination support to tools returning variable-length results. medusa_fuzz and masscan_scan should accept limit (1-1000, default 50) and offset (default 0) parameters. Return total_count and next_offset in the response.
Clarify output structure for tools with multiple result types. boofuzz_get_results should document: if session found and completed, return {status: 'completed', crashes: [list], coverage: number}. If still running, return {status: 'running', progress: '45%'}. If not found, return clear 404 with available session IDs.
Document tool composition chains. After searchsploit_search returns exploits, clarify that agents should call searchsploit_examine with the edb_id. Capa_analyze results should be extractable with get_analysis_results, ensure scan_id is returned from capa_analyze and used by get_analysis_results.