Cybersec Toolkit

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds real value beyond that by enumerating the five detection strategies and disclosing that a host argument switches to an SSH-based 'which <binary>' check. Only the absence of failure-mode or return-behavior detail keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, followed by the detection strategies and the remote-host behavior. Three short paragraphs, every sentence carrying information, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be recounted, and annotations cover the safety profile. Between purpose, detection strategies, and remote-host semantics, an agent has everything needed to call this correctly in either local or remote mode.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. The description still adds meaning by explaining what host actually causes (remote SSH installation check) and anchoring tool_name to tools_config.json, going beyond the schema's phrasing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Check if a specific cybersecurity tool is installed on the system.' This is clearly distinct from run_tool, list_tools, or get_tool_info. It does not explicitly name or route away from those siblings, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by explaining that supplying host triggers a remote SSH check, which hints at the local-vs-remote decision. However, it never says when to use this versus list_tools or get_tool_info, and offers no exclusions or prerequisites. Usage is implied rather than stated.

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

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

Adds substantial context beyond the annotations: local-first/deterministic behavior, that it returns ready-to-run run_tool("curl", ...) commands rather than performing network fetches, that external lookups are gated by CYBERSEC_MCP_ALLOW_EXTERNAL, and that an authorization-gate skill must be cleared first. This explains the openWorldHint=false annotation and the safety profile rather than merely restating it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose, then groups the input contract, return behavior, and safety prerequisite into distinct, information-dense paragraphs. No sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be enumerated, and the description still previews the return shape (skills, tools with install status, modules). It is complete for normal use, though it omits edge-case behavior such as an unknown or ambiguous CVE id.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description goes further by listing concrete nickname examples ('log4shell', 'eternalblue', 'zerologon', 'printnightmare') and the CVE-YYYY-NNNN form, which helps the agent normalize input beyond the schema's brief wording.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ('map a CVE to the toolkit's tools, skills, and modules') and specifies the accepted input forms (CVE id or nickname). It is readily distinguishable from siblings like get_tool_info and get_module_info, which operate on the toolkit's own inventory rather than mapping an external CVE.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains when it acts locally versus when it defers to curl commands, and names a hard prerequisite ('always clear the authorization-gate skill before testing'). It gives clear operating context but does not name an alternative tool for cases the caller might prefer instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds that it returns the module description, its tools, and management commands, but says nothing about unknown-module behavior or result size.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that names the resource first and enumerates the payload; nothing is padded or redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one documented parameter, read-only annotations, and an output schema that carries the return structure, the description covers everything needed to invoke the tool correctly. Only the installed/prerequisite condition is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema description coverage, including examples ('web', 'pwn', 'forensics'). The description adds no meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Get') and resource ('module') plus the shape of what comes back (description, tools, management commands). It is distinguishable from sibling get_tool_info by operating on a module rather than a tool, though it never explicitly names that sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisite (e.g. must the module be installed first?), and no routing toward alternatives like get_tool_info or list_tools. The agent must infer the context entirely.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is fully covered. The description adds that results are grouped by module with per-tool install status, which is useful, but does not disclose anything about auth or rate limits beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and efficiently sized at two short sentences. There is mild redundancy, since 'List every tool that a specific profile would install' and 'returns the complete list of tools' carry nearly the same information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a one-parameter, read-only tool with an output schema present and annotations covering safety, the description supplies everything needed to invoke it correctly. Return-value details are appropriately left to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'profile' parameter already documents example values ('ctf', 'redteam', 'web', 'full'). The description only restates 'Given a profile name,' adding no format or validation detail beyond the schema — the baseline 3 for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'List every tool that a specific profile would install' — and adds scope detail, returning tools grouped by module. This clearly separates it from siblings like list_tools (all tools) and get_tool_info (single tool).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description supplies a concrete use context: 'This lets you see exactly what you get before running the install command,' which implies previewing before install. It stops short of naming explicit alternatives (e.g., list_profiles for discovering valid names), so it is clear but not fully exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the result includes install method, module, URL, install status and management commands, which is useful behavioral context, but it says nothing about what happens for an unknown tool_name or any rate limits. Given annotations carry the main burden, a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, purpose front-loaded, no filler. The second sentence enumerating return fields is slightly redundant given an output schema exists, which keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since an output schema exists, the description need not explain return values, so its core obligation is purpose plus routing. Purpose is covered; what's missing is any signal about when to prefer this over list_tools, check_installed, or get_module_info, and what happens on a bad tool name.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single documented parameter, so the baseline 3 applies. The description adds no format, casing, or matching-rule detail (e.g., exact name vs alias) beyond the schema's 'Name of the tool to look up.'

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Get detailed information about a cybersecurity tool') and even enumerates the fields returned, so an agent knows exactly what comes back. It does not, however, differentiate itself from nearby siblings like get_module_info or check_installed, which also return tool/module metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use statement. The description never mentions list_tools (browse the catalog) or check_installed (installation state), even though this tool overlaps heavily with both, leaving the agent to infer routing from the name alone.

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

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

Beyond annotations (destructiveHint=true, openWorldHint=true), the description discloses governed execution checks ('target scope, external-network, shell-injection, and blocked-flag checks'), confirms no auto-run in the default call, and explains that autonomous mode may create, save, and run scoped helper scripts, persisting reusable ones under manual_scripts/. It also states that authorization_confirmed is required before any network step executes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and is dense with useful operational detail. It is a bit paragraph-heavy and could be more scannable, but given the complexity of the orchestration behavior, most sentences earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be fully explained, yet the description still summarizes what companion mode returns and what autonomous mode bootstraps. Combined with the annotations and 100% schema coverage, the definition gives an agent enough context to choose and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter semantics already live in the input schema. The description largely repeats default values and enum-like options (mode companion/autonomous, workflow auto, target_type auto) without adding substantial syntax or format guidance beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific compound verb+resource: 'Plan, guide, or autonomously solve a security task over the MCP toolchain.' It immediately positions the tool as an 'orchestrator on top of the registry, advisors, install checks, audit logging, and execution policy,' which cleanly distinguishes it from sibling tools like run_tool, run_pipeline, and suggest_for_*.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly explains the default companion mode versus opt-in autonomous mode, and explicitly routes simple recon/HTTP commands to run_tool instead. It does not, however, give a full when-not-to-use rule or spell out the exact conditions under which autonomous mode should be preferred over companion mode, leaving some inference to the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and closed-world behavior, so the safety profile is covered. The description adds genuine context beyond that: exactly 14 profiles, the osint-to-full size range, and that each is a curated module set. The 'Returns' sentence overlaps the output schema and is somewhat redundant.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and size, and the supporting sentences are short. The trailing 'Returns:' block restates what the earlier sentence ('Shows module count, tool count, and install command') already established, which is mild duplication.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value detail is not strictly required, and the description supplies scope, size, and content shape. It is essentially complete for a zero-param read tool, with the only gap being guidance on when to prefer it over adjacent discovery tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% and the description correctly implies no filtering options.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List all 14 available installation profiles') with explicit scope and quantitative detail. Clear enough to distinguish from siblings like get_profile_tools or recommend_install, which deal with a single profile or a recommendation rather than the full catalog.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the discovery framing but never stated: it does not say when to call this versus get_profile_tools, recommend_install, or check_installed. No exclusions or prerequisites are given, though the context is reasonably inferable for a list tool.

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

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

Annotations already declare readOnly, idempotent, closed-world behavior, so the safety profile is covered. The description adds valuable context about data provenance (drawn from tools_config.json, shared with installer/advisors) and return shape (total count, available filters, one entry per tool), which goes beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action, then provides provenance, filter examples, and entry-point guidance. Efficient and well-ordered, though the provenance sentence is slightly verbose for a list tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description fills remaining gaps: data source, filter combinations, and the tool's role in the workflow relative to siblings. Nothing essential is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so baseline is 3, but the description adds semantic value by giving concrete examples of the three filters and showing combinations, which helps an agent reason about filter interaction beyond the schema's individual parameter docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (list/filter) and resource (670+ cybersecurity tools in the registry), and grounds it in the shared tools_config.json registry. Distinguishes from siblings by naming check_installed and get_tool_info as downstream steps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Start here to discover what exists before check_installed or get_tool_info,' giving a clear entry-point role, and offers concrete filter combinations (module="web", method="pipx", installed_only=True) to guide use.

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

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

Annotations already flag destructive/openWorld/non-idempotent, and the description adds genuinely new behavioral context: the StrictHostKeyChecking=accept-new policy, that the first-seen key is pinned in ~/.ssh/known_hosts and later changes are rejected, and the out-of-band fingerprint verification advice. That is security-relevant disclosure beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then enumerates actions, then ends with the SSH key-pinning caveat. Every paragraph adds information, though the per-action enumeration is dense and slightly overlaps the schema's own descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-action mutation tool with side effects, an output schema present (so returns need no explanation), and full annotation coverage, the description supplies the missing pieces: action semantics, credential requirements, and the connection-security caveat. An agent has enough to select actions and call them correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: which parameters each action requires (name for add/remove/test, hostname for add) and what tool_allowlist actually does (restricts which tools may run on that host, with None meaning all). It stops short of restating defaults like user='kali' or port=22.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Starts with a specific verb set (add/list/test/remove) and a concrete resource (SSH remote hosts), and names the dependent sibling tools run_tool and check_installed. An agent can immediately distinguish this registry-management tool from the execution tools in the sibling list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains that the action parameter selects the operation and gives per-action conditions (add needs name+hostname, remove takes a name, test opens a connection), plus the prerequisite context that hosts enable remote execution via run_tool. It does not, however, state explicit when-not-to-use cases or an ordering rule such as 'add before test before run_tool'.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds useful context by clarifying this is an advisory recommendation engine rather than an installer, despite the 'install' in the name, and explains the over-install avoidance behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action in the first sentence, followed by scope and rationale. All sentences are relevant, though the second sentence could be slightly trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a present output schema, full parameter documentation, and complete annotations, the description covers everything an agent needs to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'task' parameter, so the schema already explains it. The description's reference to a 'natural-language description of what the user wants to do' merely restates the schema, adding no syntax or format detail beyond it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (recommend) and resource (profile, modules, or individual tools to install), and scopes the output range from a full profile down to a few tools. It does not explicitly name or contrast with siblings like list_profiles or get_profile_tools, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage ('Analyzes a natural-language description of what the user wants to do') and gives a rationale ('Avoids installing everything when only a subset is needed'), but provides no explicit when-to-use guidance or alternatives among the many sibling tools (list_profiles, get_profile_tools, check_installed).

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false, but the description still adds real value: per-step validation before any process starts, a 200KB per-step stdout/stderr cap, a truncation marker, and the returned `truncated` flag. It omits what happens to earlier steps if a later step fails, which matters for a destructive pipeline, so it is strong but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, followed by the motivating example, then the safety/bounding guarantees. Every sentence carries concrete information (validation order, 200KB cap, truncation marker) with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be re-described, and the description covers the semantics an agent needs: step structure, validation, bounding, and truncation signaling. The main residual gap is failure/partial-execution behavior across steps in a destructive multi-step run.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema itself documents `host` (reserved), the step-list shape with the max-10 constraint, and the timeout default/max. The description adds no further parameter-level syntax or semantics, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Execute a pipeline of tools') plus the precise mechanism (stdout piped to stdin of the next step), which implicitly separates it from the single-invocation siblings run_tool and run_script. It does not explicitly name those alternatives, so an agent still has to infer the routing, keeping it short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when to reach for it: replacing shell piping such as `strings binary | grep flag` with a safe, no-shell alternative. That is a concrete usage trigger, though it stops short of explicitly contrasting with run_tool/run_script or stating when not to use a pipeline.

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

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

Annotations already flag destructive/openWorld/non-idempotent, and the description meaningfully extends them: it discloses the temp-file write-then-delete lifecycle, the interpreter used, and two independent gating/containment flags. The non-sandboxing warning is exactly the kind of consequence an agent needs before calling a mutating execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with what the tool does and the effect, followed by execution mechanics and then the opt-in/containment caveats. Every sentence contributes information an agent would not otherwise have.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return-value explanation is unnecessary, and the description covers the remaining risk surface: execution mechanism, cleanup, and the two environment flags governing permission and containment. Nothing material is missing for a correct call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the venv, timeout, language, and working_dir semantics are already fully documented in the schema, including defaults and the venv/bash interaction. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb+resource pair ('Write and execute a Python or Bash script') plus the scope of the effect ('returning its output'), which is enough to separate it from sibling run_tool and run_pipeline. Nothing about the action is left ambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states the precondition for use (CYBERSEC_MCP_ALLOW_SCRIPTS=1) and the security posture (not OS-sandboxed, not bound by CYBERSEC_MCP_ALLOW_EXTERNAL). It stops short of naming when to reach for run_tool/run_pipeline instead of scripting an ad-hoc program, so it lacks an explicit alternative-routing clause.

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

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

Annotations declare destructive/openWorld/non-idempotent, and the description adds substantial context on top: argument sanitization against shell injection, timeout clamping to 1-300s, 200KB output truncation, default local/private network restriction with an env-var escape hatch, and SSH semantics where the tool need only exist on the remote host.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then layered constraints in short, well-separated paragraphs. Every sentence carries operational information (sanitization, timeout clamp, truncation, network policy, SSH) with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a high-risk execution tool: safety profile is covered by annotations, argument and host semantics by the description, and return values by the existing output schema. An agent has everything needed to call it correctly and safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for 'host' (executed remotely via SSH, tool need not be installed locally) and for 'args' (sanitized to prevent shell injection). Timeout and tool_name semantics are largely left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Execute') and resource ('an installed cybersecurity tool or system utility') plus the outcome ('return its output'). It clearly separates itself from siblings like run_script and run_pipeline by scoping to registry tools and a fixed set of allowed system utilities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives rich context: registry vs. ~120 built-in system utilities, network tools restricted to local/private targets unless CYBERSEC_MCP_ALLOW_EXTERNAL=1, and remote execution when host is supplied. It never explicitly says when to prefer run_script/run_pipeline or the suggest/recommend siblings, so routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds real behavioral value by disclosing what the response contains: curated tools with installation status, methodology steps starting with scope verification, common vulnerabilities, and quick wins.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose in the first sentence, then supporting detail. The alias list is somewhat long but each entry maps useful input strings, so it earns its place; no filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, yet the description still sketches the response shape. Combined with the enum-free parameter being fully enumerated, the definition is complete enough for an agent to invoke correctly, missing only explicit sibling routing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% but the schema has no enum for target_type; the description supplies the seven valid values (web_app, api, mobile_app, cloud, network, iot, llm) and the accepted aliases, which the schema alone does not convey. This meaningfully extends parameter semantics beyond the structured field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Suggest cybersecurity tools') plus the scope ('for a bug bounty target type'), immediately distinguishing it from the sibling suggest_for_ctf. An agent can tell what this returns without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The context of use is implied by 'bug bounty target type' and the enumerated target list, but there is no explicit when-to-use / when-not guidance and no routing to alternatives such as suggest_for_ctf or guided_assessment. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds useful operational context beyond them: that recommendations are curated and include installation status, and that 14 named categories are supported. It does not discuss result size or ordering, but the output schema presumably covers returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then the category list and alias list in separate, scannable sentences. Slightly list-heavy, but each element earns its place by supporting valid parameter values.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, output-schema-backed read tool, the description covers what it does, the full valid value space, and the fact that install status is included. Nothing critical is missing; only cross-tool routing is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter, so the baseline is 3, but the description goes further by enumerating all 14 accepted challenge_type values and a set of aliases (re/rev, binary/exploitation, steganography, network, recon). Since the schema declares no enums, this enumeration is genuinely additive and prevents wrong-value calls.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Suggest cybersecurity tools for a CTF challenge category'), which the agent can immediately act on. It does not name or contrast with the obvious sibling suggest_for_bounty, so differentiation from that near-twin is left implicit via the word 'CTF'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for a CTF challenge category' implies the use context, but there is no explicit when-to-use / when-not guidance and no reference to the adjacent suggest_for_bounty or recommend_install tools. The agent must infer that this is the CTF-scoped path.

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