Hercules MCP

by 0xMihirK

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools are clearly distinguishable by their domain prefixes (system_, nmap_, metasploit_, browser_) and specific action verbs. The only potential confusion is between web_scan and web_vuln_scan, but the descriptions clarify that one is for fingerprinting and the other for vulnerability scanning, so an agent can reliably separate them.
Naming Consistency5/5
All tool names follow a consistent lowercase snake_case convention with a <domain>_<action> pattern, such as nmap_scan, metasploit_search, shell_kill_job, and browser_open. There are no mixed naming styles or deviations, making the naming highly predictable.
Tool Count2/5
With 45 tools, this server is well above the typical 3-15 tool range and qualifies as 'too many' per the calibration. While each tool has a distinct purpose, the large number (especially 10 browser_* tools and 4 shell_* job tools) creates a heavy surface that could overwhelm agents and increases selection complexity.
Completeness4/5
The server covers the core penetration testing lifecycle comprehensively: recon, scanning, exploitation, post-exploitation, web app testing, and browser automation. Minor gaps exist, such as no workspace_list_files or workspace_delete_file, and no dedicated packet capture tool, but shell_exec provides a viable workaround for these missing operations.
Average 4/5 across 45 of 45 tools scored. Lowest: 3.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 9 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the save location, path resolution rules, and full-page behavior, which is useful. However, it leaves unclear whether the tool returns the image inline, writes only to disk, how return_base64 affects behavior, or any side effects like overwriting existing files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with Purpose, Constraints, and Example sections, making it scannable and front-loaded. It is not overly verbose, though the truncation in the purpose text prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no output schema, no annotations, and a non-trivial save behavior, the description is incomplete. It omits key parameters (annotate, return_base64), the nature of the inline image content, and the full return behavior, making it hard for an agent to invoke correctly in all scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description must compensate. It explains full and partially explains path and session, but annotate and return_base64 are completely unexplained. The example with session='recon' helps, but not enough for a 5-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool captures a validated PNG screenshot of the current page as MCP image content and saves it, which is specific and actionable. It does not explicitly differentiate from sibling browser_snapshot, but the verb and output format make the core purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical constraints (default save path, path traversal restrictions, full-page capture via full=True) that imply when these options matter, but it does not explicitly state when to choose this over sibling tools like browser_snapshot or browser_read. No exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors: sessions are isolated, each has its own cookies, and the stream action relays a loopback WebSocket to a configured host port. However, it does not mention side effects of close/close_all (e.g., whether cookies are discarded) or any other consequences, leaving behavioral transparency partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Purpose, Constraints, and Example sections, and it front-loads the core purpose. It is concise, though the use of ellipses suggests truncation, slightly reducing clarity. Overall, it is appropriately sized and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main functions and constraints, and an output schema exists so return values are not necessary. However, it leaves gaps in parameter semantics (session) and side-effect disclosure, making it adequate but not fully complete for a tool with multiple actions and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It explains the 'action' enum values and hints at 'stream_port' via 'configured host port', but the 'session' parameter is not described at all. The phrase 'selected session' implies how to select, but the parameter itself remains ambiguous, leaving one of three params unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource ('isolated stealth browser identities' and 'loopback-only live-view stream') and enumerates the primary actions (current, list, close, close_all, stream). The verb 'Manage' is slightly generic, but the resource is well-defined and clearly distinguishes this session management tool from sibling browser interaction tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for managing browser sessions, but does not explicitly state when to use this tool vs alternatives, nor provide exclusions. The constraints section lists allowed actions, giving some guidance, but no direct comparison to sibling tools like browser_open or system_start_new_session is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It reveals key behaviors (foreground vs background, job_id creation) but remains vague on other important aspects like timeout, output format, error handling, and the exact behavior of 'interact'. The truncated ending suggests additional undisclosed details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with labeled sections (Purpose, Constraints, Example). It avoids fluff and quickly conveys core information, though the ellipsis at the end suggests it may be truncated, slightly harming completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, no annotations, lacks a visible output schema), the description is far from complete. It covers only the surface-level constraints and leaves many behavioral aspects and parameters undocumented, making it insufficient for an agent to reliably invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains only action, target, port, background, and job_id. Parameters like udp, command, execute, extra_args, tail_lines, and listen_port are completely unexplained, leaving significant gaps for a parameter-heavy tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: using ncat with three explicit actions (connect, listen, interact) for TCP/UDP connections. It distinguishes between connection modes but does not explicitly contrast with sibling tools like nmap_scan or network_curl, so it loses a point for sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage constraints: connect requires target/port and runs foreground, while listen can run foreground or background with background=True creating a job_id and pipe. This gives clear context for choosing between actions, though it lacks explicit 'when-not-to-use' alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It reveals path restrictions and encoding behavior, but leaves offset/max_bytes semantics and return format unexplained. The truncated 'For large files...' sentence also detracts from completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with 'Purpose' and 'Constraints' labels and a concise example. However, the incomplete sentence 'For large files…' breaks the flow and suggests missing content, detracting from the overall structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and no schema descriptions, the description is insufficient. It fails to explain how offset and max_bytes work, how bounded reads operate, and the handling of large files. The presence of an output schema does cover return values, but key usage details are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains path resolution and encoding meaning, but offset and max_bytes are not described. This leaves two of four parameters without semantic clarity beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Read a bounded file chunk inside the owned container workspace', using a specific verb and resource that clearly distinguishes it from sibling tools like workspace_write_file. The example further clarifies usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading files within the workspace but provides no explicit guidance on when to use this tool versus alternatives like shell_exec. It mentions constraints but no exclusions or alternative tool recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries behavioral transparency. It discloses that extra_args accepts a defined list of flags and that XML output is parsed when possible, preserving script output fields. However, it omits details about side effects, error behavior, or what 'validated target' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with 'Purpose', 'Constraints', and 'Example' labels, front-loading the main action. It is only four sentences long, each adding useful information, though the enumeration of allowed args could be seen as slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters and no annotations, but it has an output schema, which reduces the need for return-value explanations. Still, missing usage alternatives and vague target/script_name semantics leave gaps for an agent attempting correct invocation. The description is adequate for a simple run but not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains extra_args's allowed values (-p, -sV, --script-args, --script-trace, -d, -v) and includes an example mapping target and script_name, but target format (hostname vs IP) and script_name resolution remain ambiguous. This only partially clarifies the three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run a previously written custom NSE script against a validated target.' It specifies the verb, resource, and scope, and distinguishes itself from sibling tools like nmap_scan and nmap_write_nse_script by emphasizing 'custom' and 'previously written.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides constraints ('Requires target and script_name') and an example, but does not explicitly state when to use this tool versus alternatives like nmap_scan for standard scans or nmap_write_nse_script for authoring scripts. The context 'previously written' implies a prerequisite but lacks direct comparison or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that extra_args is preserved for certain modes, which is a behavioral trait, but does not disclose potential side effects (e.g., network probing, resource usage), error conditions, or what happens if constraints are violated. The description is largely procedural and lacks transparency about the tool's operational impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with clear 'Purpose', 'Constraints', and 'Example' sections, making it scannable and front-loaded. It is concise, though the use of ellipses suggests possible truncation, and the constraints section is dense. Overall, it earns its place without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, constraints, and provides an example, and the presence of an output schema reduces the need to detail return values. However, it leaves gaps: raw_args is unaddressed, the difference between raw_args and extra_args is unclear, and there is no guidance on custom mode usage or interaction with sibling NSE tools. Given the tool's complexity, this is a minimally adequate but incomplete contextual picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to several parameters (mode, target, ports, scripts, extra_args) by explicitly linking them to mode-specific constraints and giving an example. However, it does not explain the purpose or distinction between raw_args and extra_args, and 'preserved' is vague. Given that the schema provides only defaults and enum values, the description adds some value but not enough to fully compensate for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Run Nmap' and specifies the resource (Nmap scan) with a list of modes (quick, aggressive, port, script, custom) and their high-level purposes (host discovery, service enumeration, NSE execution). This distinguishes it from sibling tools like nmap_write_nse_script and nmap_run_nse_script by focusing on scanning rather than script creation or execution exclusively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Constraints' section provides clear prerequisites for when each mode is valid (e.g., quick/aggressive/port/script require target, port requires ports, script requires scripts). However, it does not explicitly state when to choose nmap_scan over sibling tools like nmap_run_nse_script, nor does it mention alternatives for custom script handling. Thus, it gives usage context but lacks explicit alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It adds value by explaining that the default output preserves registrar, dates, nameservers, statuses, and DNSSEC, and that include_raw retrieves boilerplate/legal text. However, it does not mention error behavior, access requirements, or potential rate limits, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear 'Purpose', 'Constraints', and 'Example' sections. Every sentence provides useful information, and the front-loaded purpose makes the tool's function immediately understandable. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, default output, include_raw usage, and gives an example. An output schema exists, so return detail is less critical. However, extra_args is unexplained, no relationship to sibling tools is noted, and the lack of any usage guidance for a recon tool in a broader security context leaves it somewhat incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The domain parameter is clear from the example, and include_raw is explained with a condition. However, extra_args is entirely undocumented, and its purpose cannot be inferred from the name or description. This is a meaningful gap for a tool with only three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear, specific action: 'Collect WHOIS registration data for a domain.' This verb+resource combination distinguishes it from sibling tools like recon_dns and recon_amass, which target different DNS/asset data. The example further reinforces the intended usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a conditional hint for include_raw but gives no explicit guidance on when to choose this tool over alternatives such as recon_dns or recon_amass. It does not state prerequisites, exclusions, or contexts where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations to fall back on, so the description carries the full burden. It mentions 'Constraints' but only about parameter requirements, not about side effects (e.g., closing a session terminates the connection, stopping a job kills the process). No safety info is disclosed for destructive actions like close_session or stop_job.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with 'Purpose', 'Constraints', and an 'Example'. It front-loads the main purpose and uses a compact enum-like list. Minor deduction for the trailing ellipsis which suggests possible truncation, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though an output schema exists (so return values are covered), the description lacks critical behavioral context for a management tool with destructive actions. It does not mention error handling, prerequisites (e.g., existing sessions), or confirmations. More detail on side effects and prerequisites is needed for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does clarify conditional parameter requirements (session_id/command for interact_session, job_id for stop_job), giving meaning beyond the raw schema. However, it does not explain the purpose of timeout or the default behavior of job_id/session_id when 0.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Manage Metasploit sessions and jobs' and enumerates the specific actions via the action parameter. This distinguishes it from sibling tools like metasploit_search and metasploit_run_module by focusing on session/job lifecycle management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides per-action parameter constraints (e.g., 'interact_session requires session_id and command'), which implicitly tells the agent which action to use based on available parameters. However, it does not explicitly state when to prefer this tool over alternatives or mention scenarios where it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden for behavioral disclosure. It mentions that the URL is target-validated and output is mostly raw, which are useful constraints. However, it does not discuss potential side effects like network connectivity or authentication requirements. Some transparency provided, but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Purpose, Constraints, and Example sections. Every sentence provides valuable information without padding. It is concise, front-loaded, and easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 8 parameters and no annotations, the description covers the core purpose, key constraints, and an example. The output schema exists, so return values need not be described. Some parameter details are unexplained, but the description is reasonably complete for a curl wrapper.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains headers format (comma-separated) and gives an example with method, data, cookie. However, it does not detail include_headers, follow_redirects, or extra_args. The description adds some meaning but leaves several parameters to be inferred from their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: making HTTP requests with curl, listing specific capabilities (methods, headers, cookies, data, redirects, extra args). While it doesn't explicitly contrast with sibling tools, the 'with curl' phrasing and specific scope distinguish it from other network tools. A clear and specific purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for usage (e.g., URL validation, header format) and an example, but it does not explicitly state when to use this tool over alternatives or when not to use it. The purpose implies usage, but no exclusions or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It does mention always using --batch, requiring a workspace output directory, and target validation, which are useful behavioral traits. However, it does not disclose the potentially destructive or risky nature of actions like dump and os_cmd, nor does it explain any side effects or security implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured with labeled sections: Purpose, Constraints, and Example. Each sentence serves a distinct purpose, and the key information is front-loaded. The example adds clarity without unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the tool is complex with 17 parameters and no annotations. The description provides an example, action list, and basic constraints, but it lacks explanations of what each action does, prerequisites, or guidance on unsafe operations. It is enough for a basic understanding but insufficient for fully informed use of all capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only partially does so. It lists several parameters supported by scan_custom (method, data, cookies, level, risk, techniques, tamper, proxy, forms) and provides an example, yet it omits explanations for many parameters such as db, table, command, enum_what, extra_args, and include_raw. The description adds some value but falls short for a 17-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run sqlmap' with a specific list of actions (scan_basic, scan_custom, enumerate, dump, os_cmd), providing a precise verb+resource combination. The tool's name and description distinguish it from siblings like nmap_scan or metasploit_run_module, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool through its action list, but it does not explicitly state when this tool should be preferred over alternatives or exclude other use cases. It mentions constraints (requires target_url and validation) and always using --batch, which gives some context, but no clear 'when to use' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that httpx supports threads and whatweb uses agg_level, but it does not disclose whether the tool is read-only, whether it sends network requests, what side effects it might have, whether it requires authentication, or how long it might take. The description focuses on parameter mapping rather than behavioral traits, which is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear 'Purpose:', 'Constraints:', and 'Example:' sections, and it is mostly concise without fluff. However, the 'Constraints' section ends with an ellipsis ('…'), which may indicate truncated or incomplete information, and the constraints are presented as a run-on sentence rather than a list. Still, it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (14 parameters, 6 tool choices, no annotations, but an output schema exists), the description covers tool selection and per-tool parameter constraints, which is valuable. However, it does not explain which tools are suited for which targets (e.g., wpscan for WordPress), whether urls is required for each tool, or what the output will look like (though the output schema may cover that). The ellipsis also suggests missing content, making it moderately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning by listing tool-specific parameter constraints (e.g., 'httpx accepts urls or target and supports threads', 'wpscan supports enumerate and api_token'), which clarifies how to use many of the 14 parameters. However, it does not explain parameters like title, status_code, tech_detect, include_raw, or extra_args, so coverage is incomplete. The example also helps illustrate usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool runs one of six web fingerprinting scanners (httpx, whatweb, wafw00f, nikto, wpscan, arjun), selected via the 'tool' parameter. This is a specific verb+resource+scope and distinguishes it from sibling tools like nmap_scan or sqlmap_run, which are for different types of scanning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for web fingerprinting (via 'web fingerprinting scanner') and provides per-tool parameter constraints, but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions (e.g., 'use nmap_scan for network scans' or 'use web_vuln_scan for vulnerability assessment'). The usage context is implied but not clearly differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does reveal that the tool accepts 'raw administrator input' and can run 'ANY agent-browser command,' which implies broad execution capability. But it does not explicitly mention potential side effects, error modes, or the impact on the stealth session, leaving some uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses labeled sections (Purpose, Constraints, Example) which makes it scannable and front-loaded. Each part is useful, though the 'COMPLETE browser…' phrase is somewhat vague and the ellipses suggest incomplete content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a clear purpose, a prerequisite, and an example, which is good for a complex escape-hatch tool. However, it leaves 'json' and 'timeout' semantics undocumented and does not address error behavior or side effects. The presence of an output schema reduces the need to describe return values, but the parameter gaps keep it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It defines 'args' as raw administrator input and the example shows 'session' usage, but 'json' and 'timeout' are not explained at all. The description adds some value for the required parameter but leaves most parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'runs ANY agent-browser command against the current stealth session,' which is a specific verb+resource+scope. It also self-identifies as an 'escape hatch' for features absent from structured tools, distinguishing it from siblings like browser_open and browser_act.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly frames the tool as an escape hatch for 'controller features absent from structured tools,' which tells the agent when to use it over alternatives. It also states a mandatory prerequisite: 'Call browser_skill(name='core', full=True) first.' However, it does not provide explicit exclusions or directly name which structured tool to prefer for simpler cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits itself. It mentions that the target is validated and that the output summary keeps credential findings, which adds some insight. However, it does not disclose network activity, rate limiting, error handling, or potential side effects, leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for Purpose, Constraints, and Example. It is concise, uses no filler, and the example is practical and easy to understand. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the essential purpose, required parameters, and an example, making it usable for a straightforward call. The presence of an output schema reduces the need to describe return values. However, it misses optional parameters and any caveats about prerequisites or operational impact, making it adequate but not fully complete for a brute-force tool with six parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains target, service, usernames, and passwords, including the 'file:' prefix for wordlists, and gives an example. However, it omits the 'port' and 'options' parameters entirely, leaving two of six parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Run Hydra for online credential testing against a service,' clearly stating the tool's function with a specific verb and resource. It distinguishes itself from offline cracking tools like crack_john by emphasizing 'online,' and the example reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists required inputs and provides an example, giving some usage context. However, it does not explicitly mention when to use this tool over alternatives (e.g., crack_john) or state when not to use it. The phrase 'online credential testing' implies a distinct use case but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It reveals a key side effect (writes payload bytes to /opt/workspace/payloads/) and the fallback mechanism (RPC to msfvenom). This is valuable context beyond the schema, though it omits failure modes or exact side effects of overwriting files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Purpose, Constraints, Example) and is compact. Every sentence serves a purpose, and the example illustrates usage without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose, constraints, side-effect location, and an example. It lacks details on error handling, format options, or when to use the RPC vs fallback path, but the presence of an output schema may partially compensate for return format. Context is adequate but has clear gaps for a tool with nested options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does add meaning by explaining that options should include LHOST/LPORT and that format controls output format, plus an example payload. However, it does not enumerate possible formats or all option fields, leaving gaps for a nested object with additionalProperties true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a payload via Metasploit RPC or msfvenom fallback, which is a specific verb+resource. It does not explicitly distinguish itself from sibling Metasploit tools, but the purpose is unambiguous and the payload generation scope is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives usage constraints like passing payload and options (LHOST/LPORT) and controlling format, but it does not explicitly state when to use this tool versus alternatives (e.g., metasploit_run_module). Usage is implied from the purpose, but no when-not-to-use or alternative references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only mentions that the module is run through the RPC API and gives an example, but it does not disclose execution model (synchronous vs background), potential side effects of running an exploit, required permissions, or what happens to sessions/jobs on completion. This is a meaningful gap for a tool that can run exploits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with Purpose, Constraints, and Example sections. Every sentence contributes useful information, and the example makes the invocation pattern concrete without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters, nested objects, and full schema coverage, the description covers the essential invocation guidance and provides a concrete example. It does not detail differences between auxiliary/post modules or edge cases, but the presence of an output schema and detailed parameter descriptions reduces the need for more. Still, a bit more context on execution behavior would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that options should contain datastore options like RHOSTS/RPORT/TARGETURI and that payload/payload_options are used for exploits, which helps an agent construct correct argument combinations beyond the schema's terse field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Run a Metasploit exploit, auxiliary, or post module through the RPC API,' identifying a specific verb and resource. It distinguishes this tool from sibling metasploit_search, metasploit_manage, metasploit_generate_payload, and metasploit_start_listener by focusing on executing a module rather than searching, managing, generating, or listening.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful constraints ('module_type is usually exploit, auxiliary, or post', 'options should contain module datastore options') and clarifies payload usage for exploits, giving clear context for argument preparation. However, it does not explicitly state when to use this tool over sibling tools or when not to use it, so it only partially addresses usage selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses tool-specific constraints and the single/bulk distinction, but does not explicitly state that lookups are read-only, describe output behavior, or mention safety/rate-limit characteristics. It adds some behavioral context but not rich enough for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and structured with Purpose/Constraints/Example, front-loading the core action. The trailing '…' suggests possible truncation, but for a 9-param tool, the description remains economical. Not a 5 because information is telegraphic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-mode tool with 9 parameters, it covers the purpose and param split, and an output schema exists so return values are handled. However, it lacks operational details like how to specify multiple domains for bulk resolution and what constitutes valid extra_args/server input, so an agent might not correctly invoke dnsx mode.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It names all parameters in the constraints and provides an example, mapping params to the selected tool. Yet it doesn't define parameter formats or expected values (e.g., server syntax, extra_args conventions, silent meaning), leaving semantic gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Run DNS lookups with tool=dig|dnsx' – a specific verb and resource, and further differentiates single-record queries vs bulk resolution. This clearly distinguishes it from siblings like recon_whois and recon_amass by naming the DNS-lookup scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit internal usage guidance: 'dig uses target, record_type, server, short, axfr, and extra_args' and 'dnsx uses domains or target and silent/extra_args', plus an example invocation. However, it does not mention when to choose recon_dns over sibling recon tools or list exclusions, so it falls short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It adds useful details like Dalfox mapping threads to --worker and supports cookie/extra_args, but does not explain include_raw or broader side effects (e.g., network traffic, output formatting). This is moderate transparency but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: Purpose, Constraints, Example. It avoids waste, though the trailing ellipsis suggests truncation. It efficiently conveys key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters, no annotations, and an output schema. The description covers the core purpose, constraints, and parameter mappings, but lacks guidance on when to choose this over other scanners, omits include_raw, and does not describe the output or side effects. This is adequate but not fully complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains the purpose of tool, target_url (via example), threads mapping, cookie, extra_args, and data (for commix), but omits include_raw. This is strong compensation for most parameters, but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb+resource ('Run web vulnerability scanners') and distinguishes it from siblings by naming the supported scanners (dalfox, commix). This makes the purpose unambiguous and unique among the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need to run dalfox or commix scans) but does not explicitly state when not to use it or compare it to alternatives (e.g., sqlmap_run, nuclei_run). It provides constraints but no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals a key behavioral trait: without a passphrase, Hercules passes an empty one to avoid an interactive prompt. This is valuable context, but it does not disclose potential side effects of 'extract' (e.g., writing files to disk) or other operational nuances. Since no annotations exist, the description carries the full burden and could be more thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured: a 'Purpose' line, a 'Constraints' line, and an 'Example'. Every sentence earns its place, front-loading intent and providing a practical illustration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and an output schema, the description covers essential usage. It gives an example and explains passphrase handling. It does not mention output format, but the output schema presumably covers that. It is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well: it explains the meaning of 'action' (info|extract), the requirement for 'filepath', the default behavior of 'passphrase', and the role of 'extra_args'. The example further clarifies usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Inspect or extract steghide payloads' with explicit action values (info|extract). It uses a specific verb and resource, making it distinct from generic tools, though it does not explicitly contrast with sibling tools like ctf_binwalk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is clear: required filepath, optional passphrase, and the behavior of using an empty passphrase to avoid interactive prompts. It also mentions extra_args for tuning. However, it does not state when to prefer this tool over alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It mentions thread control, tool defaults, and the behavior when wordlists are missing. However, it doesn't discuss side effects like load/congestion, authentication requirements, or result handling, though an output schema exists. The provided edge-case help is useful, but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured as Purpose, Constraints, and Example. It is concise, every sentence serves a purpose, and the example is illustrative without being verbose. Front-loaded purpose makes it immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the core use case, required input, tool selection, concurrency control, and a wordlist-missing edge case. However, with 7 parameters and no schema descriptions, the lack of explanation for extensions, extra_args, and include_raw leaves the description incomplete for advanced usage. The presence of an output schema reduces the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains target_url, tool, threads, and wordlist, but omits extensions, extra_args, and include_raw. Since it covers 4 of 7 parameters with meaningful context, it provides some value but leaves significant gaps for the remaining ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Discover web paths with gobuster or ffuf', immediately stating the tool's purpose. It also distinguishes itself from siblings by naming the specific fuzzing tools and mentioning thread control. The example further reinforces the intended use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context: requires target_url, explains the default tool (gobuster) and how to switch to ffuf, and notes that threads controls concurrency. It does not explicitly list alternatives or when-not-to-use, but the purpose and constraints are sufficiently clear for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It discloses the JSONL output format and comma-separated target constraint, and mentions rate_limit for tuning. However, it does not disclose potential intrusiveness, error behavior, or side effects of running templates against targets, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear Purpose, Constraints, and Example sections. It is concise, with no redundant information, and front-loads the main purpose in the first sentence. The example is useful and directly illustrates usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters, no annotations, and an output schema is said to exist but not shown. The description covers the main execution aspects but omits include_raw behavior, detailed output structure, error handling, and any prerequisites. This is adequate for basic use but lacks depth for a complex security tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains targets, templates, severity, tags, rate_limit, and extra_args, and provides an example with rate_limit. However, include_raw is not mentioned at all, and the format for extra_args is not detailed, so it only partially compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Run Nuclei templates against one or more targets with JSONL output,' which is a specific verb+resource+output format. It clearly distinguishes this from sibling tools like nuclei_write_template by describing execution rather than writing. The example further anchors the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating templates can come from nuclei_write_template or installed paths, implying when to use this tool. However, it does not explicitly state exclusions or compare with other scanners like nmap_scan or web_vuln_scan, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden. It discloses selector compatibility and provides an example, but it omits behavioral details such as side effects, failure modes, or authentication requirements. The visible constraints are useful but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured into Purpose, Constraints, and Example. Every sentence contributes value, though the trailing ellipsis after the action list is slightly untidy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, action-target compatibility, and gives an example, but with 7 parameters and no in-schema descriptions, it leaves gaps around exact/name semantics and return behavior. The output schema exists but is not included, so the description alone is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema parameter descriptions are entirely absent (0% coverage), so the description must compensate. It explains the interplay between action and target_type, references name/exact for accessible matching, and supplies a concrete example with action, target, value, and session.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Interact with a page element' and enumerates all supported actions (click, fill, type, press, hover, select, check/uncheck). This clearly differentiates it from sibling browser tools like browser_open or browser_snapshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use snapshot refs and which target types support which actions. It does not explicitly contrast with alternatives like browser_eval, but the constraints are clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses useful behavior: JS is written to a temp file, evaluated to avoid quoting issues, and must return a JSON-serializable value. However, it does not warn about potential side effects of arbitrary JS (e.g., page modification, network requests, data exfiltration) or explain session-specific isolation, leaving a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses a clean, labeled structure (Purpose, Constraints, Example), front-loads the core behavior, and every sentence earns its place. The example is practical and compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's power and the lack of annotations, the description covers purpose, usage, key constraints, and an example. An output schema is present, so return format is partially covered. What's missing is any safety or side-effect guidance, but for typical use it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the 'js' parameter through the example and the JSON-serializable return constraint, but the 'session' parameter is never mentioned. Thus it partially adds meaning but leaves one of two parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Run arbitrary JavaScript in the page context and return the result', a specific verb+resource that immediately distinguishes it from sibling browser tools like browser_read or browser_act. The 'custom DOM extraction, probing JS state' examples further cement its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use ('custom DOM extraction, probing JS state'), giving useful context. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions 'Runs with light concurrency and target validation', which adds safety-relevant context. However, it does not disclose potential network impact, privilege requirements, or side effects beyond packet crafting, leaving important gaps for a security tool that sends packets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into Purpose, Constraints, and Example, front-loading the most important information. Each sentence is concise and informative, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the core usage context, constraints, and an example, which is sufficient for an agent to invoke the tool. Since an output schema exists, return values don't need to be explained. It could mention prerequisites or consequences, but it is reasonably complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It states that 'count, syn, port, and extra_args map to hping3' and gives an example, which connects parameters to the underlying tool's arguments. However, it doesn't individually explain each parameter's meaning, relying on the agent's familiarity with hping3 and the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Craft packets with hping3' which is a specific verb and resource, and explicitly mentions its purpose for firewall, service, or packet-level testing. This clearly distinguishes it from sibling tools like nmap_scan or network_curl, which focus on scanning or HTTP requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (firewall, service, or packet-level testing) and includes constraints like requiring a target. It doesn't explicitly name alternatives or say when not to use it, but the stated use cases imply appropriate selection among the sibling network tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral disclosure burden. It states that the response indicates whether a process was killed, which is useful, but it does not mention side effects, irreversibility, or what happens if the job_id is invalid or already completed. This is minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with four labeled parts: Purpose, Constraints, Use, and Example. Every sentence contributes useful information, and the most important details are front-loaded. No filler or redundancy exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with an output schema available (per context signals), the description covers the essential workflow: stop by job_id, optionally check output first, and interpret the response. It could mention that job_id originates from shell_exec_background, but overall the description is sufficient for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required string parameter with 0% description coverage, so the description must compensate. It adds 'Requires job_id' and provides an illustrative example ('http8000'), but it does not explain where a valid job_id comes from or its expected format beyond the example. This is adequate but not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Stop' and identifies the resource as 'background shell job' keyed by job_id, clearly distinguishing it from sibling tools like shell_exec_background and shell_check_job. It is immediately obvious what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides actionable guidance: 'Requires job_id' and 'Use shell_check_job first if you need final output.' This clarifies a key workflow dependency. It does not enumerate when not to use the tool, but it gives enough context for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses compact vs detailed output, iframe inlining, and stable references, but does not explicitly mention side effects or permissions. Still, it adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear sections (Purpose, Constraints, Example) and is concise. It front-loads the core purpose and uses compact phrasing, though the ellipsis suggests possible truncation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 8 optional parameters and output schema, the description covers most functionality, including narrowing/expanding options. However, it omits a full explanation of the session parameter and lacks alternative tool guidance, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the effects of compact, detailed, interactive, include_urls, depth, selector, and implies inline_iframes. Session is shown in the example but not explicitly described. Since schema coverage is 0%, this compensation is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool captures the page's accessibility tree as compact text with stable element references, using a specific verb and resource. It distinguishes itself from sibling browser tools by focusing on the accessibility tree and element references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides parameter constraints but does not explicitly compare with alternatives or state when to use this tool versus siblings. It implies usage for capturing snapshots, but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It explains the mode semantics and gives an example with 'networkidle', but does not disclose timeout behavior, failure handling, or implications of waiting on a condition. This is a moderate level of transparency for a wait operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured with 'Purpose', 'Constraints', and 'Example' sections. Each sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a wait operation, and the description covers the main modes and an example. However, it omits important operational details such as timeout limits, default wait behavior, and what happens when the condition cannot be met. Given the existence of an output schema, return values are not required, but the missing failure semantics makes it incomplete for robust use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description's explanations are critical. It adds meaning for the 'value' parameter by mapping each condition to the expected format, and it explains the 'condition' enum variants. The 'session' parameter is not described, but its role is implied by sibling context and the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Wait for a condition before continuing' and enumerates specific condition types (selector, ms, text, url, load), distinguishing it from sibling browser action tools like browser_act or browser_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Constraints' section explains how the condition parameter selects the mode and what value should contain for each mode (CSS selector, milliseconds, text, URL glob). This gives clear context for use, though it does not discuss exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses behavior for different argument values (no name vs. full=True) but does not explicitly state whether the tool is read-only or safe. Given the simple documentation-loading nature, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with labeled sections (Purpose, Constraints, Example). It front-loads the core purpose in the first phrase and contains no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two optional parameters, an output schema present, and a self-contained documentation purpose, the description covers the essential usage. It doesn't elaborate on error conditions or detailed return shapes, but those are less critical for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining 'name' (default 'core') and 'full' (default true) with their effects, plus an example call. It clarifies the primary combinations, though not every edge case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Load agent-browser's own built-in skill documentation' with a specific verb and resource, differentiating it from sibling browser_* tools that handle navigation, reading, or execution. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides concrete usage guidance: 'With no name it lists available skills; name='core' (default) with full=True returns the complete command reference.' This explains when to use the tool and how to call it, though it doesn't explicitly mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the full workflow: writes hashes to a temp file, cracks with john, shows results with john --show, and removes the temp file. This gives valuable insight into the tool's behavior and side effects (temporary file cleanup). It does not mention potential long runtimes or error handling, but the essential behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into Purpose, Constraints, and Example sections. Every sentence provides essential information without padding. It is concise, front-loaded with the main purpose, and the example grounds the abstract concepts.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, external process) and the presence of an output schema, the description adequately covers the main workflow and constraints. It explains the temporary file lifecycle and when to use format/extra_args. It does not detail return values (mitigated by output schema) or error scenarios, but for a cracking tool, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for 'format' (hash type selector) and 'extra_args' (additional John arguments), and the example demonstrates use of 'hashes' and 'wordlist'. However, 'wordlist' and 'extra_args' are not fully explained (e.g., default values, path requirements), leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run John the Ripper against supplied hashes using a wordlist.' This is a specific verb+resource statement that distinguishes it from sibling tools like bruteforce_hydra or hashcat-dependent tools. The example further reinforces the intended use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context, such as writing hashes to a temporary file and cleaning up, and explicitly instructs to use 'format and extra_args when hash type needs explicit selection.' However, it does not explicitly compare with alternatives or state when not to use the tool, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It meaningfully discloses how extract=True adds extraction flags and forces --run-as=root unless extra_args already specifies it, and how absolute paths are handled to avoid duplicate paths. This goes beyond the schema and gives important side-effect context, though it does not cover all potential behaviors like output artifacts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three labeled, compact sentences: Purpose, Constraints, and Example. It is front-loaded with the core purpose, then provides essential behavioral constraints, and ends with a useful example. Every sentence earns its place with no redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the tool's moderate complexity, the description covers the essential aspects: purpose, key behavioral constraints, and an example. It does not explicitly address when to use this versus sibling tools, but the core usage context is sufficiently clear for a CTF-oriented binwalk wrapper.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% parameter description coverage, so the description must compensate. It explains the semantics of extract (adds flags and --run-as=root) and extra_args (can override --run-as), adding meaning beyond the schema. The example clarifies filepath usage, though filepath itself is not described in detail. Overall, the description adds substantial parameter-level context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Analyze and optionally extract firmware, archives, and embedded files with binwalk.' This uses a specific verb and resource, and the mention of 'firmware, archives, and embedded files' distinguishes it from sibling tools like ctf_steghide or shell_exec.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides constraints but no explicit guidance on when to use this tool versus alternatives. The intended use is implied by the purpose statement (firmware/archives) but there is no mention of exclusions or alternative tools, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden. It notes prerequisites and the behavior that empty lists may require broader queries, but does not state whether the operation is read-only, side-effect free, or what the returned data will contain beyond 'available modules'. The presence of an output schema reduces the need for format details, but safety implications are not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with Purpose, Constraints, and Example sections. Every sentence provides useful information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter search tool with an output schema, the description covers purpose, constraints, and an example, making it largely self-contained. It lacks explicit comparison to sibling search tools but is otherwise complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining the query parameter can be a keyword, service name, or CVE, and includes a concrete example (vsftpd). This adds meaning beyond the bare 'query' name, though it could elaborate on syntax or wildcards.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches Metasploit exploit, auxiliary, and post modules by keyword, service name, or CVE. This specific verb+resource+scope fully distinguishes it from sibling tools like metasploit_run_module or searchsploit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use the tool (searching for modules) and includes prerequisites (Metasploit enabled, RPC available) and a tip to broaden query if empty. However, it does not explicitly mention alternatives such as searchsploit or when to prefer one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for disclosing behavior. It explicitly says the listener runs as a 'background job', notes required parameters and the lport range, and gives a concrete example. It does not detail failure modes or side effects beyond a background job, but covers the key operational traits for starting a listener.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly organized into Purpose, Constraints, and Example sections. It is concise, with every sentence carrying useful information and no filler. The structure makes it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects: what the tool does, prerequisites, constraints, and an example. It directs the user to metasploit_manage for job lifecycle, which is important context. While it doesn't discuss all edge cases or the output schema (which exists), the description is sufficiently complete for a listener-starting tool given its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It names the three required parameters (payload_type, lhost, lport) and provides a valid example, but it does not explain the optional 'options' parameter at all. The description adds meaning for the required fields but leaves one parameter undefined, missing full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb 'Start' and the precise resource 'exploit/multi/handler as a Metasploit background job'. This clearly distinguishes it from sibling tools like metasploit_run_module (running modules) and metasploit_manage (managing jobs), making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it requires payload_type, lhost, and lport, and tells the user to run system_network_info first for bridge-networked hosts. It also suggests metasploit_manage for job management. However, it does not explicitly state when not to use this tool versus alternatives, leaving some room for inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behaviors. It mentions the path traversal rejection and the fact that it writes to a specific directory, but it does not disclose overwrite behavior, directory creation, or error conditions. It does hint at the return path via 'using the returned path,' which adds some transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with three clear sections: Purpose, Constraints, and Example. The purpose is front-loaded, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only two parameters and an output schema exists (per context), so the description does not need to explain return values. It covers the destination directory, path constraints, validation options, and gives an example. Minor gaps remain regarding overwriting and error handling, but these are not critical for an agent selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by explaining both parameters. It shows an example using path='custom/basic-detect.yaml' and content='id: basic-detect\ninfo: ...', clarifying that path is a relative path and content is the YAML template body. It also enforces the relative-path constraint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Write a custom Nuclei YAML template into /opt/workspace/nuclei-templates.' This specifies a unique verb/resource combination and distinguishes it from generic file-write tools like workspace_write_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context: it requires relative paths ('Use relative paths such as custom/check.yaml'), explains path traversal rejection, and recommends validation via shell_exec or nuclei_run with the returned path. While it doesn't explicitly name alternatives, the purpose and constraints infer when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses the operational modes, that active=False means passive mode, that brute=True enables brute force, and the potentially long runtime. It misses details like output format or side effects, but the key behavioral traits for a subdomain enumeration tool are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized into Purpose, Constraints, and Example sections. Each sentence adds useful information without fluff, and the example is directly actionable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, return values need not be described. The description covers the core purpose, modes, constraints, runtime expectations, and provides an example. The only notable omission is extra_args, and it does not explicitly mention when to prefer lighter recon tools, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains domain, active, and brute: active=False uses passive mode, and brute=True enables brute force. However, extra_args is completely undocumented, leaving one of four parameters unexplained, which is a clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Enumerate subdomains with amass' and explicitly names the three execution modes (passive, active, brute-force). This distinguishes it from sibling tools like recon_dns and recon_whois, which serve different recon purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context: it requires a domain, explains mode selection via active and brute flags, and warns that the tool is heavy and can take up to 20 minutes. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It does reveal that tail_lines controls output length and implies a read-only nature ('Read status and tail output'), but it does not explain error behavior, handling of missing jobs, or whether output is persisted after job completion. Some useful behavioral context is present, but gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with 'Purpose:', 'Constraints:', and 'Example:' sections. It is concise, front-loaded with the core purpose, and every sentence adds value. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema present, the description covers purpose, constraints, an example, and a fallback alternative. It does not explicitly link to sibling tools like shell_exec_background for obtaining a job_id, but context from the tool name and sibling list makes this inferable. Overall, it is sufficiently complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description compensates by explaining both parameters: job_id identifies the job and tail_lines controls the amount of recent output. It also includes a concrete example showing parameter values. However, it does not state defaults or bounds for tail_lines, though the schema provides a default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Read status and tail output from a background shell job.' This distinguishes it from siblings like shell_exec (which runs commands) and shell_kill_job (which terminates jobs). The purpose is immediately clear and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context by mentioning constraints and an alternative for inspecting artifacts: 'inspect artifacts with workspace_read_file/shell_exec.' It implicitly signals that this tool is for checking output, not for starting or killing jobs, but does not explicitly exclude those use cases. The example adds practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behavioral constraints: URL scope validation, redirect revalidation, fingerprint compatibility-only with rejection of non-empty values, and proxy precedence order. This goes well beyond what the schema or annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Purpose, Constraints, and Example sections. It is front-loaded with the core purpose and every sentence adds value without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, no annotations), the description covers purpose, constraints, and a usage example. The presence of an output schema covers return-value expectations, though alternative-tool guidance is minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for url, proxy, and fingerprint via constraints, and the example shows session and timezone usage. However, locale remains unexplained, and schema descriptions are absent, leaving significant gaps for a 6-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Open a URL in cloakbrowser Chromium and start an interactive browsing session.' It clearly distinguishes this tool from sibling browser tools (e.g., browser_act, browser_snapshot) by focusing on the initial open and session start.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it ('start an interactive browsing session') and provides an example. However, it doesn't explicitly mention alternatives or exclusion criteria, relying on sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses useful behavioral traits such as returning JSON when available, degrading overly specific queries, and using include_raw to avoid result capping. However, it does not state whether the tool is read-only or requires authentication, and 'mirror' behavior remains vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with 'Purpose', 'Constraints', and 'Example' sections. Every sentence provides value, and the information is front-loaded and concise without redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description does not need to detail return values. It covers the two actions, parameter semantics, and key constraints. The presence of '…' suggests possible missing content, and 'mirror' is not fully elaborated, but overall it is adequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage, so the description compensates by explaining action via the enum values, include_raw as avoiding result cap, and giving an example for query_or_id. This adds practical meaning to all parameters, though the exact format for 'get' action is not specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search or mirror Exploit-DB entries with action=search|get', identifying the specific resource (Exploit-DB) and the two main actions. This distinguishes it from sibling tools like metasploit_search or web_scan, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for searching or mirroring Exploit-DB entries, with practical constraints on query degradation and result capping. However, it does not explicitly mention alternatives or when not to use this tool, so it lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses non-interactivity, mentions 'safety bounds', and explains raw=True's effect. However, 'safety bounds' is vague and it doesn't mention potential destructive outcomes or permissions, but the safety profile is partially addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact with labeled sections (Purpose, Constraints, Example). Every sentence adds value, and the example is illustrative without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is generic shell execution with high potential risk. The description covers purpose, non-interactive behavior, safety constraints, and alternatives. It omits timeout semantics, but the presence of an output schema reduces the need to explain return values. Overall, it is sufficiently complete for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains `raw` in detail and gives an example for `command`, but does not explain `timeout`. This is incomplete for a tool with three parameters and no schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a non-interactive shell command inside the Kali container' – a specific verb and resource. It also distinguishes itself from shell_exec_background explicitly, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides direct usage guidance: 'use shell_exec_background or ncat/listeners for long-running jobs' and explains when not to use this tool. This clearly tells the agent when to choose this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly indicates that the command runs in the background, requires a job_id, and shares the container session. However, it does not describe what the tool returns immediately (e.g., whether it returns job status or just a success indicator) or address potential side effects beyond process lifetime.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured, with clear 'Purpose' and 'Constraints' labels followed by a concrete example. Every sentence adds value: purpose, constraint, related tools, session-sharing note, and example. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description is largely complete. It covers purpose, required parameter, relationship to sibling tools, and a usage example. The only minor gap is not explaining what the immediate call result looks like, but the output schema presumably covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The text states 'Requires job_id' and gives an example with both parameters (command='python3 -m http.server 8000', job_id='http8000'). This clarifies the basic usage but does not explain what job_id represents beyond being a required identifier or any constraints on command formatting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Start a long-running shell command as a background job.' This uses a specific verb ('start'), identifies the resource ('shell command'), and distinguishes it from the sibling 'shell_exec' by specifying background execution and the need for a job_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the companion tools for managing the background job: 'Use shell_check_job to read output and shell_kill_job to stop the process.' It also notes that 'Background jobs share the current container session,' which is important context for usage. This provides clear when-to-use and how-to-manage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden and does well by disclosing atomicity, path restriction, symlink/reparse escape rejection, content/base64 exclusivity, and default mode. It does not mention whether directories are auto-created or what the return value indicates, but the core behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with labeled sections for purpose, constraints, and an example. Every sentence adds value and there is no redundant repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description is sufficiently complete for invoking the tool correctly. It covers path safety, content selection, and defaults, which are the main contextual details needed. Minor behavioral gaps remain, such as overwrite behavior and directory creation, but these are partially inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains path resolution, the mutually exclusive content/content_base64 parameters, and the mode default. The example also clarifies usage, though content_base64 is only implied rather than explicitly described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes content to a file in the owned container workspace, using a specific verb and resource. It distinguishes itself from the sibling workspace_read_file tool by focusing on the write operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, such as writing files in the workspace and respecting path constraints. It does not explicitly mention exclusions or alternatives, but the purpose and constraints make the intended use unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly discloses limitations: url/title are page-level, ref/CSS support text/html/value, semantic role/text/label support text only with optional name/exact. This gives the agent a concrete model of the tool's behavior. It also states that unsupported combinations should use snapshot/ref or CSS, setting expectations. This is strong transparency for a read tool, so 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labels (Purpose, Constraints, Example) and is concise—each section adds useful information. The example is helpful. However, there is a truncation ellipsis ('…') that suggests some content may be missing, which slightly reduces clarity. Otherwise it's efficient, so 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (6 parameters, 5 enum values) and the presence of an output schema, the description covers the main facets: what data can be read, the valid target types, and the constraints on combinations. It lacks a full explanation of the target and session parameters, and the fallback instruction is somewhat ambiguous. With the output schema covering return values, this is well-rounded but has a few gaps, so 4.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the meaning of the 'what' parameter by listing the supported values, and it clarifies how 'target_type' interacts with these values (e.g., role/text/label only support text). It also mentions the 'name' and 'exact' parameters as optional for semantic roles. However, it does not explicitly explain the 'target' and 'session' parameters; the example shows session usage, but target is left implicit. Still, this is a substantial addition beyond the bare schema, so 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear purpose statement—'Read data from the page'—and enumerates the specific data types (text, HTML, value, URL/title). This directly distinguishes it from sibling browser tools like browser_act or browser_eval, so it earns a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use this tool (to read data from the page) and includes constraints on which target types support which data types. It also suggests using snapshot/ref or CSS for unsupported combinations, offering a fallback. However, it does not explicitly name alternative sibling tools or give definitive when-not-to-use criteria, so it's a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It explicitly states 'Does not modify the container' and mentions the specific return fields (active_session, total_sessions), which is helpful for understanding side effects and output. Minor gap: no mention of permissions or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is compact and clearly structured with Purpose, Constraints, and Example. Every sentence adds value; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (no params) and presence of an output schema, the description is complete. It covers purpose, constraints, and example invocation, making it self-sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100%. The description adds no parameter-specific info but doesn't need to. Baseline 4 is appropriate for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'List Hercules session workspaces on the host.' It directly distinguishes from siblings like system_start_new_session and system_stop_container by indicating a read-only listing action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to list sessions on the host. It does not name alternatives but the sibling context makes the read-only nature obvious. No explicit exclusions are needed for a simple list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses important runtime behavior, such as the possibility that concurrent IDE clients may receive different ports, and clarifies the scope of returned information. It does not discuss side effects, but the 'Inspect' framing strongly implies a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into Purpose, Constraints, and Example sections in just four short lines. Every sentence provides useful information, and the key content is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are no parameters and the tool has an output schema, the description sufficiently covers the purpose, key return values, and a runtime caveat. The example call rounds out the usage picture, making the description complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The example 'system_network_info()' correctly demonstrates that no arguments are required, and the description adds no unnecessary parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Inspect') and defines the resource scope ('host/container networking, browser host access, and callback routes'). It also lists concrete outputs like effective RPC/listener/stream ports and LHOST guidance, making it clearly distinguishable from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when the agent needs networking details such as ports, LHOST, localhost scope, or the Docker-host alias. It does not explicitly name alternatives or exclusion criteria, but the purpose and constraints provide enough guidance for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It clearly states side effects: 'It stops background jobs and container-side processes,' and the constraint that containers cannot run until a new session starts. It also reassures about workspace file preservation. This is transparent about the destructive nature and post-conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using just three clearly labeled sentences: Purpose, Constraints, and Example. Each sentence contributes essential information without redundancy. The structure front-loads the purpose and immediately follows with critical constraints, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no nested objects) and the presence of an output schema, the description covers all necessary aspects: what it does, what side effects occur, and an example invocation. It effectively explains the post-conditions and session impact, leaving no obvious gaps for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema already fully describes the input space (empty object). The description adds no parameter-specific details, but none are needed. Per the baseline for zero-parameter tools, a score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Stop and remove the current Hercules container while preserving workspace files.' It identifies the specific resource (Hercules container) and the two distinct actions (stop and remove), while also adding a key nuance (preserving workspace files). This distinguishes it from sibling tools like system_start_new_session and shell_exec.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context about consequences ('MCP tools that require the container cannot run until a new session is started') but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or name alternative tools. Usage is implied by the purpose rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It reveals that Hercules sanitizes the name, writes to /opt/workspace/nmap-scripts/<name>.nse, and updates the Nmap script database. This is meaningful behavioral context, though it does not mention overwrite behavior or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: Purpose, Constraints, and an Example. Every sentence adds value, and the example illustrates usage effectively without unnecessary prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-param write tool with no annotations, the description covers the main aspects: purpose, destination path, side effect (DB update), and follow-up action. It does not address potential failure cases, but given the existence of an output schema and the moderate complexity, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by explaining the name constraint (no path separators) and showing an example with both name and content. It adds context about how the name becomes a .nse file path, but does not further detail content format beyond being NSE script code.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Write a custom NSE script into the container and update the Nmap script database.' This clearly distinguishes it from siblings like nmap_run_nse_script (execution) and workspace_write_file (generic file writing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs the user to use nmap_run_nse_script to execute the written artifact, providing a clear alternative. It also gives a constraint (pass name without path separators) that informs correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that it creates a new workspace, stops the current container, preserves previous host data, and reinitializes Metasploit RPC when enabled—important behavioral traits for a session-mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three labeled sections (Purpose, Constraints, Example) deliver the essential information in a compact, front-loaded format with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description fully covers purpose, side effects, and usage. It is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so baseline is 4 per rubric. The description does not need to explain parameters; the schema is trivially complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource: 'Start a fresh Hercules container session with a clean mounted workspace.' This distinguishes it from siblings like system_list_sessions (listing) and system_stop_container (stopping), and the example reinforces usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Purpose' line makes the intended use clear, and the constraints explain key side effects. However, it does not explicitly reference alternative tools or exclusions, though the context is strong enough for an agent to infer when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![hercules-mcp MCP server](https://glama.ai/mcp/servers/0xMihirK/hercules-mcp/badges/card.svg)](https://glama.ai/mcp/servers/0xMihirK/hercules-mcp)

Score Badge

Copy to your README.md:

[![hercules-mcp MCP server](https://glama.ai/mcp/servers/0xMihirK/hercules-mcp/badges/score.svg)](https://glama.ai/mcp/servers/0xMihirK/hercules-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/0xMihirK/hercules-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server