https://github.com/user-attachments/assets/ba467fae-a4c9-4f63-b2e6-3fc30fb023f3
完全ローカルで動作する自律型AIペネトレーションテストエージェント — Gemma 4-12B が偵察・攻撃・レポート作成を担う42ツールの武器庫を駆動し、標準の Model Context Protocol (MCP) サーバーとして公開されます。クラウドもAPIキーも不要です。
機能概要 · ツール · アーキテクチャ · 技術スタック · クイックスタート · 変更履歴 · コントリビューション
HALOは、ローカルLLM — Gemma 4-12B（アンセンサード / アブリテイテッド）をLM Studio経由で動作させるLinux環境内で稼働する自律型セキュリティエージェントです。計画の立案、偵察の実行、発見した内容に基づく攻撃の連鎖、そしてプロフェッショナルなペネトレーションテストレポートの自動作成までを単独で行います。すべてがローカルで完結し、クラウドもAPIキーも不要で、データがマシンの外に出ることはありません。
一言でエンゲージメントが始まります：engage。
🔍 自律型偵察 — masscan + nmap でオープンポートとサービスを発見
⚔️ 自律型攻撃ループ — 発見結果に基づいてツールを選択し、連鎖させる
🌐 Web偵察 → 攻撃パイプライン — apexドメインからURLまでの列挙（サブドメイン、ホスト、履歴URL）、コンテンツ発見、テンプレートスキャン、XSSを実行し、CTF形式のWebターゲットでは自動のフラグキャプチャを実施
✅ バナーではなく検証済みの侵害 — すべての試行には使い捨てのチャレンジ/ノンスが付与され、エクスプロイトは取得したシェルの内部からそのノンスをエコーバックする必要があります。素の uid=0 バナーやターピットでは偽造できないため、確認された侵害は本物です（実行由来の証拠、ゲートでの消費1回限り）
🎯 厳選されたPoCライブラリ — 決定論的で自明なエクスプロイト（vsftpd 2.3.4、ingreslock、UnrealIRCd）を、推測ではなく実際のシェルを返すサンドボックス化されたデリバリプリミティブを通じて実行
🧠 永続的な失敗体験キャッシュ — すべてのセッションでの失敗を学習し、実証済みの行き止まりにサイクルを浪費しない
🧩 適応型スキル注入 — 現在の目標に基づいて関連する攻撃プレイブックをプロンプトに読み込む
📝 自動HTMLレポート — 終了時に発見結果をブランド入りレポートにまとめる
🔒 100%ローカル — LM Studio 上の Gemma 4-12B。マシンの外に出るデータはありません
Related MCP server: Debugg AI MCP
エージェントの意思決定ループの背後には42のツールがあり、すべて同じ失敗キャッシュ層を経由します。ツールは halo_tools.py 内の TOOLS スキーマレジストリに一度だけ定義され、両方のトランスポート（MCP と HTTP）で提供されます。
偵察 & OSINT
ツール | 目的 |
| サブドメイン列挙 |
| パッシブOSINT — メール、サブドメイン、ホスト |
| HTTPプロービングとフィンガープリンティング |
| Webクローリング |
| 90以上のプラットフォームでのユーザー名OSINT |
| インターネット露出情報の検索 |
| 電話番号OSINT |
| 電話番号OSINT / 抽出 |
| ユーザー名 / IP / 電話番号のOSINT |
| クラウドインフラストラクチャの列挙 |
| WAF / セキュリティソリューションのフィンガープリンティング |
| サブドメイン列挙（デフォルトでパッシブ） |
| DNS解決とプロービング |
| OTX / Wayback / Common Crawl からの既知のURL取得 |
| Wayback Machine からの履歴URL取得 |
| 視覚的偵察のためのWebスクリーンショット |
| ヘッドレスなマルチモジュールOSINTスキャン |
| recon-ng OSINTフレームワーク（非対話型） |
スキャン
ツール | 目的 |
| 高速ポート発見 |
| 詳細なサービス/バージョンスキャン |
| Web脆弱性スキャン |
| テンプレートベースの脆弱性スキャン |
| ネットワーク接続解析 |
Web & ファジング
ツール | 目的 |
| Webディレクトリのブルートフォース |
| Webファジング |
| 再帰的なコンテンツ発見 |
| XSSスキャン（反射型 / 格納型 / DOM型） |
| HTTPリクエストテスト |
| ファイル取得 |
エクスプロイテーション
ツール | 目的 |
| SQLインジェクションテスト |
| エクスプロイト検索 |
| 選択したMetasploitモジュールをターゲットに発射（人間の承認が必要） |
| カスタムPoCスクリプトのサンドボックス化実行 |
| ソーシャルエンジニアリングツールキット |
認証情報
ツール | 目的 |
| 認証情報のブルートフォース |
| ネットワーク認証のクラッキング |
| 高速な並列ブルートフォース |
| ハッシュクラッキング |
列挙 & システム
ツール | 目的 |
| SMB / Samba の列挙 |
| 任意コマンド実行 |
| ファイル内容の読み取り |
| 出力をファイルに書き込み |
単一のツールエンジン（halo_tools.py）がツール群とそのスキーマを保持し、その上に2つの軽量トランスポートが載るため、ツールは一度だけ定義されます：
agent_loop.py ──HTTP─► tool_server.py ─┐
├─► halo_tools.py ──► security tools
MCP clients ──stdio► mcp_server.py ──┘ (42-tool engine +
schema registry)
│
├─► agent_cache.py (persistent negative-experience cache)
├─► skills.py (adaptive playbook injection)
└─► report_generator.py (auto HTML pentest report on exit)mcp_server.py — 仕様準拠の Model Context Protocol サーバー（stdio、JSON-RPC 2.0）。任意のMCPクライアント（Claude Desktop、IDEエージェント、インスペクタ）またはMCPレジストリから接続すれば、HALOのツール群を標準ツールとして利用できます。
tool_server.py — 自律エージェントループが駆動するローカルなFlask HTTPツールサーバー（ポート8000）。
// e.g. an MCP client config
{
"mcpServers": {
"halo": { "command": "python3", "args": ["/abs/path/to/mcp_server.py"] }
}
}提出可能なレジストリマニフェストは server.json にあります。
エンゲージメントは、共有メッセージスキーマ（agent_schema.py）をやり取りする専門エージェント群によって調整されます：
エージェント | 役割 |
| 目標を順序立てた計画に変換 |
| タスクを適切な専門エージェントにルーティング |
| 候補となる脆弱性を提示 |
| 脆弱性クラス別の専門エージェント（SQLi、ブルートフォース、IDOR、SSRF、XSS、認証）に分岐 |
| 発見を確定前に実際の証拠と照合して確認 |
| 失敗したツール実行を診断して調整 |
失敗体験キャッシュはすべてのツール呼び出しのフィンガープリントを記録します。失敗した呼び出しには1回のリトライが与えられ、2回失敗するとブラックリスト入りするため、エージェントはその作業に適した別のツールへと進みます。エンゲージメントを通じて、エージェントは自らの試行錯誤学習を構造化します — コンテキストを構築し、実証済みの行き止まりを回避し、知的にエスカレーションする — すでに機能しないと証明されたものを再実行するのではなく。
自律型攻撃者にとって難しい問題は、実際に侵入に成功したのか、それとも希望的なバナーを繰り返しただけなのかを判断することです。HALOはこれをチャレンジレスポンスゲートで解決します：
オーケストレーターは発射前に、そのターゲットと正確なペイロードハッシュに紐づく試行ごとのノンスを発行します。
侵害が認定されるのは、ツール出力が構造化された HALO-EVIDENCE nonce=… level=… 行でそのノンスをエコーバックした場合のみです — デリバリプリミティブ（pocs/_delivery.py）は、取得したと主張するシェルの内部でコードを実行することでしかこれを生成できません。
ノンスは消費1回限りです：ゲート（exploitation_core.py:breach_confirmed）はリプレイされた、または発行されていないノンスを拒否するため、ターピット、反射された文字列、静的な uid=0 バナーでは確認を偽造できません。
pocs/ 内の厳選されたPoCは、決定論的で自明なバグ（vsftpd 2.3.4、ingreslock 1524、UnrealIRCd 3.2.8.1）であり、このゲートを正直に通過します — 実際のrootシェルを獲得するか、何も報告しないかのどちらかです。
HALOは、独学の開発者兼セキュリティリサーチャーによって、ゼロから6ヶ月足らずで単独で構築されました。マルチエージェントコアは専門エージェントを1つずつ追加しながら組み上げられ、それぞれが実際のターゲットに対して検証されてから次の段階に進みました：
共通言語： エージェント同士が会話できる共通メッセージスキーマ（agent_schema.py）
プランナー： 目標を順序立てた計画に変換し、稼働中のLM Studioに対して検証
オーケストレーター： 各タスクを適切な専門エージェントにルーティング
脆弱性発見： 候補となる脆弱性を提示し、稼働中のMetasploitableターゲットに対してテスト
攻撃者： SQLi / ブルートフォース / IDOR / SSRF / XSS / 認証の専門エージェントに分岐
デバッガー： 失敗したツール実行を診断して調整
バリデーター + レポート： 発見は確定前に実際の証拠と照合して確認され、その後クライアントが読めるレポートにまとめられる
そこからツール群は42ツールへと成長し、フラグキャプチャを備えた完全なWeb偵察 → 攻撃パイプライン、チャレンジレスポンス方式の侵害確認が追加されました。一方、失敗体験キャッシュは試行錯誤をセッションをまたいだ永続的な学習へと変えました。現在も活発に開発が続いており、新機能は定期的に追加されています。リリース済みのマイルストーンは変更履歴を参照してください。
モデル： Gemma 4-12B Instruct Abliterated（LM Studio経由のGGUF）— 任意のローカルモデルで動作します
エージェント： MCPツール呼び出しを使用するPython自律ループ
ツールトランスポート： MCPクライアント向けのModel Context Protocolサーバー（stdio）、およびエージェントループ向けのFlask HTTPツールサーバー（ポート8000）
OS： Kali Linux（Apple Silicon M1上のUTMでテスト済み）
ハードウェア参考： MacBook Pro M1、16 GB RAM
完全なセットアップ手順は docs/QUICKSTART.md を参照してください。簡単に言うと：
git clone https://github.com/XenoCoreGiger31/GEMMA-by-GOOGLE.git
cd GEMMA-by-GOOGLE
python3 -m pip install -r requirements.txt
cp engagement.example.yaml engagement.yaml # then fill in authorization + scope_targets
python3 tool_server.py # terminal 1 — HTTP tool server on port 8000
python3 agent_loop.py # terminal 2 — the agent
>>> engage 203.0.113.3 # full autonomous recon + attack
>>> run nmap on 10.0.0.1 # single-goal query
>>> exit # triggers HTML report generation注: エンドポイントとパスは、デフォルトで標準的なローカル設定（
localhost:1234上の LM Studio、localhost:8000上の HTTP ツールサーバー）になっています。それらのいずれもHALO_*環境変数で 上書きできます — 環境オーバーライド テーブルを 参照してください。いくつかの作者固有のログ/キャッシュパスのデフォルトはagent_cache.pyとtool_server.pyに残っていますが、環境変数はそれらもカバーします。
agent_loop.pyはengagement.yamlなしでは起動しません — これはすべてのツール呼び出しが通過する 認可 + スコープゲートであり、オプション設定ではありません。 クイックスタートのステップ5 を参照してください。
ユニットテストは Python 組み込みの unittest を使用します — 追加の依存関係はありません：
python3 -m unittestセキュリティ、AI、Python コミュニティからのコントリビューションを歓迎します — CONTRIBUTING.md を参照してください。役に立った場合はリポジトリにスターを付けてください。または PR を開いて、一緒に何かを作りましょう。
独立した独学の開発者兼セキュリティリサーチャーによって積極的に開発されています。新しい機能が定期的にプッシュされています。
これは独立した開発者によるコミュニティプロジェクトです。Google LLC とは提携しておらず、承認も受けておらず、スポンサーでもありません。 "Gemma" は Google LLC の商標です。
⚠️ コンテンツ警告: 参照されているモデルは大幅にアブリテーションされており、通常のガードレールなしでセンシティブなリクエストに応答します。責任を持って、適切な環境でのみ使用してください。
🔒 法的警告: このツールは、所有しているシステム、またはテストするための明示的な書面による許可を得ているシステムに対する、許可されたペネトレーションテストとセキュリティリサーチ専用です。無許可での使用は違法です。
MIT License の下で公開されています。
Read and return the contents of a file.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Path to read. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but offers minimal behavioral disclosure. It omits critical traits such as how it handles missing files, binary files, large files, or encoding. The agent cannot anticipate error behavior or limitations.
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 extremely concise with a single sentence that immediately conveys the action. Every word earns its place; there is no fluff.
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 the tool's simplicity (one parameter, no output schema), the description is largely complete. However, it could briefly mention that the tool returns file contents as text, but that is implied by 'contents.' It adequately covers the core functionality.
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 parameter 'filename' described as 'Path to read.' The description does not add extra meaning beyond the schema. Baseline 3 is appropriate as the schema already defines the parameter.
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 'Read and return the contents of a file' uses a specific verb ('Read') and resource ('file'), clearly stating the tool's function. It distinguishes itself from siblings like write_file (write) and run_command (execute commands), 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like run_command with cat or run_cat. The description does not mention contexts, prerequisites, or exclusions, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enumerate the attack surface of an AWS environment.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | AWS profile name. | default |
| command_type | No | cloudfox subcommand. | all-checks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully convey behavioral traits. It fails to mention whether the tool modifies the environment, requires AWS credentials, or has side effects. The single sentence offers no insight into the tool's impact or requirements.
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 a single, clear sentence with no superfluous words. It is as concise as possible while conveying the core purpose.
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 the simplicity of the tool (2 optional parameters, no output schema), the description is incomplete. It lacks context about the tool's typical output, whether it is safe to run in read-only mode, and what 'enumerate the attack surface' entails in practice.
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?
Both parameters have descriptions in the input schema (profile and command_type), giving 100% coverage. The tool description adds no additional meaning beyond what the schema already provides, such as acceptable values for command_type or how the profile parameter is used.
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 'Enumerate the attack surface of an AWS environment' clearly states the tool's purpose: to run CloudFox for AWS enumeration. It distinguishes run_cloudfox from sibling tools that target different domains (e.g., network scanning with run_nmap, web enumeration with run_ffuf).
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 provides no guidance on when to use this tool versus alternatives like run_nuclei or run_searchsploit. There is no mention of prerequisites, common use cases, or scenarios where this tool is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute an arbitrary shell command with sudo auto-escalation on permission errors.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Full shell command line to execute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose all behavior. It mentions sudo auto-escalation but omits critical traits: destructive potential, security implications, timeout behavior, output format, environmental constraints. For an arbitrary command execution tool, this is insufficient.
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?
Single sentence with no filler. Front-loaded with verb and resource. Every word earns its 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?
No output schema or annotations. Given the complexity of arbitrary command execution, the description should cover return values, error handling, and safety warnings. It is under-specified for safe agent usage.
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 covers 100% with clear parameter description. The tool description adds only the auto-escalation context, which is behavioral not semantic. Baseline 3 is appropriate since schema already handles parameter meaning.
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?
Description uses specific verb 'Execute' and resource 'arbitrary shell command', clearly distinguishing it from sibling run_* tools that are specific to particular executables. The auto-escalation detail further clarifies capability.
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?
No guidance on when to use this generic tool versus the many specific run_* siblings (e.g., use run_nmap for nmap scans). Lacks when-not-to-use or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue an HTTP request and return the verbose response.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Request URL. | |
| data | No | Request body for POST/PUT/PATCH. | |
| method | No | HTTP method. | GET |
| headers | No | Single header string. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure burden, but it only states it returns the verbose response. It does not mention timeout, error handling, redirects, authentication, or other important HTTP behaviors.
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 a single sentence that efficiently communicates the tool's purpose without any wasted words or structure.
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 tool with 4 parameters and no output schema, the description is minimal but sufficient for a simple HTTP request tool. It covers the core functionality but lacks detail on edge cases or response format.
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 baseline is 3. The description adds no additional meaning beyond the schema, but the schema already adequately defines each parameter.
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 clearly states it issues an HTTP request and returns the verbose response, which is a specific verb and resource. It distinguishes from sibling tools like run_ffuf (fuzzing) or run_nmap (network scanning) by being a general HTTP client, but does not explicitly differentiate from run_wget.
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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical use cases, or exclusions, leaving the agent to infer 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.
Enumerate SMB/Samba shares, users, and policies on a host.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target host. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations given; description does not disclose authentication needs, potential destructiveness, or rate limits. Simply states 'enumerate' without behavioral details.
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?
Single sentence, no unnecessary words, but lacks depth; still concise and front-loaded.
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?
Adequate for a simple one-parameter tool, but lacks behavioral context and output description; not fully complete given no annotations.
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?
Only one parameter with full schema coverage; description adds no additional meaning beyond the schema's 'Target host.'
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?
Description clearly states the tool enumerates SMB/Samba shares, users, and policies, which is specific and distinguishes it from other run_* tools like run_nmap or run_sqlmap.
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?
No guidance on when to use this tool vs alternatives, no prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
LAST RESORT: run a custom Python PoC in the isolated sandbox runner. Requires operator approval upstream.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Full Python script source. | |
| phase | No | 'test' (no network) or 'attack'. | test |
| target | No | Target ip or ip:port. | |
| timeout | No | Seconds before kill. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions isolated sandbox and operator approval, but lacks details on error handling, return value, or logging. Does not disclose what happens on failure or success.
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?
Extremely concise: two short sentences, front-loaded with 'LAST RESORT'. No redundant 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?
Covers main purpose and safety, but fails to explain what happens after execution (e.g., output, results). No output schema, so description should mention return behavior.
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 has 100% coverage with descriptions for all parameters. Tool description adds context (custom PoC, sandbox) but does not enhance parameter semantics beyond what schema 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?
Clearly states the tool runs a custom Python PoC in an isolated sandbox, distinguishing it from sibling tools like run_nmap or run_sqlmap which are specific tools. The 'LAST RESORT' emphasizes its use case.
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 marks as 'LAST RESORT', implying other tools should be tried first, and requires operator approval. Does not name specific alternatives but context from sibling tools provides that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fast web fuzzer for directories, parameters, and vhosts.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL containing or receiving the FUZZ marker. | |
| param | No | Fuzz marker. | FUZZ |
| wordlist | No | Wordlist path. | /usr/share/seclists/Discovery/Web-Content/common.txt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations and the description only says 'Fast web fuzzer', which does not disclose behavioral traits such as destructive potential, authentication needs, rate limits, or output format. Basic transparency is lacking.
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 extremely concise (6 words) but lacks sufficient detail for an agent to use the tool effectively. It is efficient but at the cost of completeness.
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 no output schema, no annotations, and a minimal description, the context is incomplete. An agent would need more information about expected output, prerequisites, and tool behavior to use it 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% with descriptions for all 3 parameters. The tool description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.
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 clearly identifies it as a 'web fuzzer' for directories, parameters, and vhosts, which is a specific verb+resource. However, it does not differentiate from sibling tools like run_gobuster, which has overlapping capabilities.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., run_gobuster, run_nuclei). The description merely states what it is, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Brute-force web content, DNS, or vhosts against a wordlist.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | gobuster mode: dir/dns/vhost. | dir |
| target | Yes | Base URL or host. | |
| wordlist | No | Wordlist path. | /usr/share/seclists/Discovery/Web-Content/common.txt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states 'brute-force' implying potentially aggressive behavior, but does not mention rate limiting, authentication needs, resource impact, or whether the tool is read-only. This is insufficient for an agent to anticipate side effects.
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 a single concise sentence. It is front-loaded with the core action, though could be more structured with explicit mode mention.
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 the tool's complexity (multiple modes, no output schema, no annotations), the description is insufficient. It fails to explain return values, progress indication, or how it differs from similar tools in the sibling list.
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 parameters are already documented. The description adds minimal extra meaning beyond listing modes. It does not clarify path formats or expected input conventions.
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 clearly states the tool brute-forces web content, DNS, or vhosts using a wordlist. It identifies the verb and resources, but does not explicitly distinguish from closely related sibling tools like run_ffuf.
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?
No guidance is provided on when to use this tool versus alternatives such as run_ffuf, run_nikto, or run_nmap. There is no mention of prerequisites, exclusions, or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Probe hosts for live HTTP services (status, title, tech detection).
| Name | Required | Description | Default |
|---|---|---|---|
| flags | No | Override httpx flags. | |
| target | Yes | URL or host. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states it probes for live HTTP services. It does not disclose behavioral details like redirect handling, timeout, rate limits, or response format, leaving agent uncertain about execution.
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?
Description is a single, front-loaded sentence with no redundant information. Every word serves a purpose, making it efficient for quick comprehension.
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 no output schema, no annotations, and sibling tools with similar names, the description is overly minimal. It lacks details on output structure, default ports, or how it differs from run_curl, leaving gaps 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds context about expected results (status, title, tech detection) which indirectly informs parameter usage, but does not elaborate on flags format or target specifics, so baseline 3 is appropriate.
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?
Description clearly states it probes hosts for live HTTP services, listing specific actions (status, title, tech detection), and the tool name 'run_httpx' aligns with the tool's purpose. It distinguishes from siblings like run_curl (custom HTTP requests) and run_nmap (port scanning).
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?
No guidance on when to use this tool versus alternatives such as run_curl or run_nikto. The description implies it's for initial probing but fails to specify conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parallelized network login brute-forcer across many protocols.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target host. | |
| service | No | Protocol, e.g. ssh/ftp/http-get. | ssh |
| threads | No | Parallel tasks. | 16 |
| username | Yes | Username to test. | |
| wordlist | No | Password wordlist path. | /usr/share/seclists/Passwords/Common-Credentials/darkweb2017_top-1000.txt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It mentions parallelism and brute-forcing but fails to disclose potential consequences like account lockouts, network disruption, or legal implications. The description does not warn about destructive nature or authorization requirements.
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 a single efficient sentence with no waste. However, for a sensitive tool, it could benefit from additional context without being overly long. Still, it is front-loaded and clear.
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 the tool's complexity (5 parameters, no output schema, no annotations) and sensitivity, the description is incomplete. It does not explain return values, success/failure behavior, or safety considerations. Sibling tools are similar but no differentiation is provided.
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 descriptions for each parameter already exist. The tool description adds no parameter-specific meaning beyond the general statement. Baseline 3 is appropriate as schema already documents parameters well.
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 clearly states it's a 'parallelized network login brute-forcer across many protocols,' specifying the verb (brute-force), resource (network login), and scope. This distinguishes it from sibling tools like run_ncrack or run_medusa which target specific protocols or are general crackers.
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 for brute-forcing network logins but does not provide explicit guidance on when to use this tool over alternatives or any prerequisites. No exclusions or context are given for selecting protocols or handling potential lockout risks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crack password hashes with John the Ripper against a wordlist.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Force a hash format. | |
| wordlist | No | Wordlist path. | /usr/share/seclists/Passwords/Common-Credentials/darkweb2017_top-1000.txt |
| hash_file | Yes | Path to the hash file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only states the basic action without mentioning potential side effects (e.g., system resource usage), output location, error conditions, or required permissions. Important for a security tool that may be destructive.
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 a single succinct sentence that conveys the core purpose without extraneous information. It is well-structured and front-loaded, though it could include more detail without becoming verbose.
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 no output schema, no annotations, and three parameters, the description is insufficient. It does not explain what happens after cracking (success output, logging), potential hash format constraints, or the role of the default wordlist. A more complete description would improve usability.
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 baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter (format, wordlist, hash_file). It does not clarify expected formats or relationships between parameters.
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 clearly states the tool cracks password hashes with John the Ripper using a wordlist, providing a specific verb and resource. However, it does not differentiate from sibling tools like run_hydra or run_ncrack that also perform password cracking.
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?
No guidance is given on when to use this tool versus alternatives such as run_hydra (online brute-force) or run_searchsploit (exploit search). The description lacks any context about appropriate use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Crawl a web target and map its attack surface.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Crawl depth. | 3 |
| target | Yes | Seed URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks disclosure of behavioral traits. No mention of potential side effects like network requests, noise, authorization needs, or what 'attack surface' mapping entails. With no annotations, the burden is high but unmet.
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 a single, front-loaded sentence with no wasted words. It is appropriately concise for the information it conveys.
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?
Despite having only 2 parameters and no output schema, the description is too brief. It omits details about output format, error handling, depth behavior, and the scope of 'attack surface'. Incomplete for a scanning tool.
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. The description adds no extra meaning beyond the schema's 'Seed URL' and 'Crawl depth' descriptions. No additional value from the description.
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 'crawl' and resource 'web target' with outcome 'map its attack surface'. This is clear but does not explicitly differentiate from sibling reconnaissance tools like run_gobuster or run_ffuf, though the concept of crawling is distinct.
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 provides no guidance on when to use this tool versus alternatives. No context on prerequisites, suitability, or scenarios where katana is preferred over other similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
High-speed asynchronous TCP port scan of a target or CIDR range.
| Name | Required | Description | Default |
|---|---|---|---|
| rate | No | Packets per second. | 1000 |
| ports | No | Port or range. | 1-65535 |
| target | Yes | IP, hostname, or CIDR to scan. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions 'high-speed asynchronous' which implies network impact, but lacks details on permissions, potential destructiveness, rate limiting, or response handling. Basic but insufficient for informed selection.
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?
Single sentence with no redundancy. Key information is front-loaded ('High-speed asynchronous TCP port scan'). Every word contributes to purpose.
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 the tool's complexity (security scanning, potential for misuse) and lack of output schema, the description is too sparse. Missing details on output format, execution context, warnings, or integration with other tools. Needs expansion for safe and effective use.
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. The description adds no extra parameter information beyond the schema definitions. It does not enhance understanding of parameters or provide usage examples.
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 clearly states the tool performs a 'high-speed asynchronous TCP port scan' on a 'target or CIDR range', using specific verb 'scan' and resource. It distinguishes from siblings like run_nmap by emphasizing high-speed and asynchronous nature.
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?
No explicit guidance on when to use this tool versus alternatives (e.g., run_nmap, run_ffuf). The description implies speed advantage but does not specify context, prerequisites, or timeouts when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fast, parallel, modular network login brute-forcer.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target host. | |
| service | No | Protocol module. | ssh |
| username | Yes | Username to test. | |
| wordlist | No | Password wordlist path. | /usr/share/seclists/Passwords/Common-Credentials/darkweb2017_top-1000.txt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits. It mentions 'fast, parallel, modular' but omits important details like destructiveness, authentication requirements, rate limiting, or that brute-forcing may be disruptive.
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 a single sentence, which is concise but too brief to fully inform. It lacks structure and detail, though it is front-loaded.
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 it is a brute-forcing tool with no output schema or annotations, the description is incomplete. It does not describe return values, error behavior, or other critical context.
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 baseline is 3. The description adds no additional parameter information beyond what is in 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?
The description clearly states it is a 'network login brute-forcer', which is a specific verb-resource combination. However, it does not differentiate from sibling tool run_hydra, which performs similar brute-forcing.
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?
No guidance on when to use this tool versus alternatives like run_hydra, or any context for preferred usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
High-speed network authentication cracking.
| Name | Required | Description | Default |
|---|---|---|---|
| users | No | Comma-separated usernames. | root,admin,administrator |
| target | Yes | Target host. | |
| service | No | Protocol. | ssh |
| wordlist | No | Password wordlist path. | /usr/share/seclists/Passwords/Common-Credentials/darkweb2017_top-1000.txt |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must cover behavioral traits. It only states 'High-speed network authentication cracking,' which implies brute-force attacks but does not disclose potential side effects like rate limits, stealth options, server load, or account lockouts. For a security tool, this is insufficient.
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 a single sentence with no extraneous words. It is maximally concise and front-loaded with the key 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?
Despite having 4 parameters and no output schema, the description is extremely brief. It does not explain the significance of parameters, default values, or how to use them effectively. For a potentially dangerous tool like Ncrack, more context (e.g., warnings, expected outcomes) is needed for safe and 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 description coverage is 100%, with each parameter having a basic description. However, the tool description adds no additional meaning beyond these minimal schema comments. For example, 'Comma-separated usernames.' and 'Protocol.' are terse. The description does not provide examples, format details, or usage notes, so it meets the baseline but adds no extra value.
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 'High-speed network authentication cracking' clearly states the tool's purpose with a specific verb and resource. It distinguishes itself from siblings like run_hydra, run_medusa, and run_john by emphasizing 'high-speed' and 'network', though it doesn't explicitly differentiate from hydra/medusa. Still clear enough for an agent to understand the core function.
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?
No guidance is provided on when to use this tool vs alternatives like run_hydra or run_medusa. There are no mentions of prerequisites, when not to use, or typical scenarios. The description offers no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List network connections and listening sockets (falls back to 'ss').
| Name | Required | Description | Default |
|---|---|---|---|
| flags | No | netstat/ss flags. | -tuln |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions a fallback to 'ss' but lacks details on permissions, output format, or side effects.
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?
One sentence with no wasted words. Could be slightly more structured but is efficient and to the point.
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 no output schema and minimal annotations, the description is insufficient. Lacks return value information, usage context, and fails to explain how results are presented.
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 parameter, so baseline is 3. The description does not add significant meaning beyond the schema's 'netstat/ss flags.'
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 clearly states it lists network connections and listening sockets, with a fallback to 'ss'. It provides a specific verb and resource, but could better distinguish from sibling network tools like run_nmap.
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?
No guidance on when to use this tool versus alternatives. The description does not include when-not-to-use or mention any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a web server for known vulnerabilities and misconfigurations.
| Name | Required | Description | Default |
|---|---|---|---|
| ssl | No | Use HTTPS. | |
| port | No | Target port. | 80 |
| target | Yes | Host or URL to scan. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It does not mention that Nikto is a network vulnerability scanner, potential intrusiveness, or any side effects. Minimal disclosure.
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 a single sentence, efficient and front-loaded. However, it could include slightly more detail without becoming verbose.
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 the complexity of a vulnerability scanner and absence of output schema or annotations, the description is insufficient. It lacks details on output, authentication, or risk.
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 schema already explains each parameter. The description adds no new semantic meaning beyond the schema, warranting baseline score.
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 clearly states the tool scans a web server for vulnerabilities and misconfigurations. It uses a specific verb and resource, but does not explicitly distinguish from siblings like run_nmap or run_gobuster.
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?
No guidance is provided on when to use this tool versus alternatives. Given many siblings are scanning tools, explicit when-to-use or when-not-to-use would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detailed port/service scan with version and script detection.
| Name | Required | Description | Default |
|---|---|---|---|
| flags | No | nmap flags. | -sV |
| target | Yes | IP or hostname to scan. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It mentions version and script detection, but does not disclose potential side effects like network traffic, root requirements, or scan duration. Provides basic behavior but lacks depth.
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 a single concise sentence that front-loads the main purpose. No unnecessary words or redundancy.
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 the complexity of nmap and the absence of an output schema, the description is somewhat incomplete. It does not mention scanning behavior, limitations, or performance considerations, but it provides a high-level overview sufficient for basic understanding.
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% (both parameters are described in the input schema). The description does not add additional meaning beyond the schema, so a baseline score of 3 is appropriate.
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 clearly states it performs a 'Detailed port/service scan with version and script detection' using nmap, which is specific and distinguishes it from sibling tools like run_curl or run_enum4linux.
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 provides no guidance on when to use this tool versus alternatives such as run_masscan or run_nikto. No when/when-not or comparative context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run community vulnerability templates against a target.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target URL. | |
| severity | No | Severity filter, e.g. 'medium,high,critical'. | |
| templates | No | Template path or tag filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are given, and the description does not disclose behavioral traits such as potential destructiveness, network impact, authentication requirements, or whether the tool sends intrusive requests. This is a significant gap for a vulnerability scanning 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?
The description is a single sentence, front-loaded with the purpose. However, it lacks additional context that would justify its brevity; it feels underspecified rather than concise.
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 the tool's complexity (vulnerability scanning with parameters for severity and templates) and lack of output schema or annotations, the description is insufficient. It does not explain expected output, template syntax, or potential risks, making it incomplete for an AI agent.
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 already documents parameters. The description adds no extra meaning beyond the basic action, but the baseline of 3 is appropriate since it doesn't contradict or misuse 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?
The description clearly states the tool runs community vulnerability templates against a target, using a specific verb and resource. It distinguishes itself from sibling tools like run_nmap or run_gobuster, which have different purposes.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., run_nmap for port scanning, run_sqlmap for SQL injection). There are no prerequisites or context on appropriate targets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
OSINT footprinting of a phone number (carrier, region, formatting).
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Phone number in international format. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only offers a high-level overview ('footprinting'). It fails to disclose details like network requests, output format, or any potential side effects. The word 'footprinting' is vague and does not clarify read-only vs. active reconnaissance.
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 a single sentence that immediately conveys the core purpose. It is efficient and front-loaded, though it could be slightly more informative without sacrificing conciseness.
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 simple tool with one parameter and no output schema, the description is minimally adequate. However, it lacks context on what exactly the output contains, how the tool behaves (e.g., live query vs. local database), and any usage constraints.
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 'number', which has a clear description ('Phone number in international format'). The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.
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 clearly states 'OSINT footprinting of a phone number' and specifies the key outputs (carrier, region, formatting). It uniquely identifies the tool's purpose and distinguishes it from sibling tools like run_sqlmap or run_nmap which target different resource types.
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 use for phone number investigation but provides no explicit guidance on when to use versus alternatives (e.g., run_sherlock for usernames, run_shodan for IPs). There is no mention of when not to use the tool or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Exploit-DB archive for known exploits by keyword.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Optional exploit type filter. | |
| keyword | Yes | Service and version, e.g. 'vsftpd 2.3.4'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully convey behavioral traits. It only states a simple search action, omitting details like output format, pagination, or potential limits. The description adds minimal behavioral information.
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 a single, clear sentence without any fluff. Every word is necessary and contributes to the purpose.
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 the simple nature of the tool and no output schema, the description is adequate but not comprehensive. It lacks details on return format or what constitutes a successful search, which could be helpful.
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 description's role is minimal. The description reiterates example usage ('vsftpd 2.3.4') already present in the schema, adding no new meaning beyond 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?
The description clearly states the action (search), the resource (Exploit-DB archive), and the input (keywords for known exploits). It effectively distinguishes from sibling tools like run_exploit or run_nmap by specifying the database.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., run_exploit, run_nmap). The description does not include any context about prerequisites or situations where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drive the Social-Engineer Toolkit for a scripted attack scenario.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | Target for the SE attack. | |
| attack_type | No | SET menu selection. | 1 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits like potential destructiveness, interactive requirements, or network effects. The phrase 'scripted attack scenario' implies automation but is insufficient.
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 a single sentence and avoids verbosity, but it is overly brief and lacks key details, making it less useful despite its brevity.
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?
No output schema exists, and the description fails to explain what happens after execution (e.g., output files, logs, success indicators). For a tool with two parameters and a potentially complex behavioral profile, this is inadequate.
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% and the description adds no additional meaning. It does not clarify the format or purpose of 'target' (e.g., IP, domain) or the meaning of 'attack_type' options beyond the schema defaults.
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 names the Social-Engineer Toolkit but uses the vague verb 'Drive' and does not specify what action is performed (e.g., launch, configure). It partially distinguishes from siblings like run_nmap by mentioning 'scripted attack scenario' but lacks precision.
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?
No guidance on when to use this tool versus alternatives such as run_exploit or run_sqlmap. No mention of prerequisites, scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hunt a username across social networks and public sites.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | Username to search for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavioral traits. It only states the action without disclosing how the search is performed (e.g., asynchronous, rate limits, network requirements), what the output looks like, or whether the tool is read-only or destructive. This lack of transparency hinders an agent's ability to anticipate 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?
The description is a single 9-word sentence that immediately communicates the core action. It is efficiently structured with the verb first. While concise, it sacrifices completeness for brevity, which is acceptable for a simple tool but borderline under-specified.
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 the tool has no output schema and no annotations, the description should provide more context about what happens after invocation, such as whether results are returned, how to interpret them, or any network dependencies. The current description is insufficient for an agent to fully understand the tool's complete behavior and output.
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 input schema covers 100% of parameters with a clear description for 'username'. The tool description adds context that the username is searched across social networks and public sites, reinforcing the parameter's purpose. However, it does not add extra constraints or format details beyond what the schema provides, so a baseline score of 3 is appropriate.
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 uses a specific verb 'hunt' and clearly identifies the resource 'username across social networks and public sites'. It effectively distinguishes itself from sibling tools like run_nmap or run_gobuster, which are focused on different tasks such as port scanning or directory enumeration.
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 lacks any guidance on when to use this tool versus alternatives. It does not mention prerequisites, contexts where it is appropriate, or situations where another tool would be preferable. The agent is left to infer usage 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.
Look up an internet-exposed host in Shodan (open ports, services, banners).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | IP address or hostname. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral transparency. It only states the lookup action but does not disclose whether it is read-only, requires authentication, has rate limits, or any side effects. The minimal description leaves the agent uninformed about important operational constraints.
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 a single sentence, perfectly front-loaded with the essential purpose. No redundant words; every part contributes to understanding. Given the tool's simplicity, this is optimal conciseness.
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 simple lookup tool with one parameter and no output schema, the description covers the basic functionality. However, it lacks details about return format, pagination, error handling, and any dependencies (e.g., network access). The absence of usage context relative to 28 sibling tools also reduces completeness.
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% (one parameter 'query' with description 'IP address or hostname'). The description adds a slight nuance by specifying 'internet-exposed host', which clarifies the scope of the query. However, it does not elaborate on input format, validation, or examples. At high coverage, the baseline of 3 is appropriate.
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 clearly states the action ('look up an internet-exposed host'), the target resource (Shodan), and the information returned (open ports, services, banners). It distinctly separates this tool from siblings like run_nmap (network scanning) or run_httpx (HTTP probing) by specifying Shodan as the data source.
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?
No usage guidance is provided. The description does not indicate when to prefer this tool over alternatives (e.g., run_shodan vs run_nmap for external recon), nor does it mention prerequisites (e.g., API key) or limitations (e.g., only works for publicly exposed hosts). The agent must infer context from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Automated SQL injection detection and exploitation against a URL.
| Name | Required | Description | Default |
|---|---|---|---|
| dbms | No | Force a DBMS backend. | |
| risk | No | Risk level 1-3. | 1 |
| level | No | Test level 1-5. | 1 |
| target | Yes | Target URL with parameters. | |
| technique | No | Injection technique letters. | B |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must convey behavioral traits. It mentions 'detection and exploitation' implying aggressive actions, but lacks details on safety, permissions, or side effects.
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?
Single sentence is concise and front-loaded with key action. However, slightly under-specified for a complex 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?
For a complex penetration testing tool like sqlmap, the description is too sparse. It omits risk of exploitation, return values, and operational context. Incomplete given no 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?
Input schema has 100% parameter description coverage, so description adds no additional parameter meaning beyond the schema. Baseline of 3 is appropriate.
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?
Description clearly states it detects and exploits SQL injection against a URL, which is specific and distinguishes from sibling tools like run_nmap or run_ffuf. However, it could elaborate more on the automation aspect.
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?
No guidance on when to use or avoid this tool. It simply describes functionality without context of alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Passively enumerate subdomains of a domain.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Apex domain. | |
| silent | No | Silent output. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The term 'passively' indicates a non-intrusive behavior, which is helpful. However, no annotations are provided, and the description lacks details on output format, dependencies, or potential limitations (e.g., API keys, network access).
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?
Single sentence, no fluff, front-loaded with the key action. Every word earns its 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?
For a simple tool with two parameters, the description is minimal. It omits important context like expected output, passive sources used, and whether internet access is required. Given the large number of sibling tools, more context would aid correct selection.
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 input schema already provides descriptions for both parameters ('domain' and 'silent'), achieving 100% coverage. The tool description does not add extra semantic value beyond what the schema offers.
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 clearly states the verb 'enumerate', the resource 'subdomains', and the scope 'of a domain', which is specific and distinguishes it from sibling tools like run_nmap or run_gobuster that perform active scanning.
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?
No guidance on when to use this tool versus alternatives, such as run_ffuf or run_gobuster. The description does not mention prerequisites, limitations, or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fingerprint the web application firewall / security solution in front of a target.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | URL or host to fingerprint. |
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 does not mention that the tool sends HTTP requests, may be blocked, or any consequences. This is insufficient for an agent to understand the tool's side effects.
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 a single sentence that conveys the essential purpose without any unnecessary words. It is perfectly concise.
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 simple tool with one parameter and no output schema or annotations, the description is minimally adequate. However, it lacks details about output format, prerequisites, or limitations, leaving gaps for the agent.
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 input schema has one parameter with a description ('URL or host to fingerprint.'). The tool description adds no additional meaning beyond the schema, and schema coverage is 100%. Baseline 3 is appropriate.
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 clearly states the verb 'Fingerprint' and the resource 'web application firewall / security solution in front of a target', making the tool's purpose immediately understandable. It distinguishes from sibling tools like run_nmap or run_curl by specifying WAF fingerprinting.
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 for identifying WAFs but provides no explicit when-to-use, when-not-to-use, or alternatives among sibling tools. The context of siblings (e.g., run_nmap, run_curl) suggests this is for after initial reconnaissance, but no guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a file or mirror content from a URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to fetch. | |
| output | No | Output filename. | |
| recursive | No | Recursive download. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states the basic action, omitting details like redirect handling, timeouts, authentication, or error behavior. This is insufficient for an agent to anticipate side effects 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the core purpose. It could be expanded to include additional behavioral context without losing conciseness.
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 the low complexity (3 params, no output schema, no nested objects), the description is adequate for basic use. However, it does not elaborate on common use cases like website mirroring or recursive behavior, which are hinted at by the parameter 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% with clear parameter descriptions (url, output, recursive). The tool description adds no additional semantic value beyond the schema, so baseline of 3 is appropriate.
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 clearly states the action ('download' or 'mirror') and the resource ('file or content from a URL'). Among sibling tools, particularly 'run_curl' which also fetches URLs, the mention of mirroring helps differentiate wget's specific capability.
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?
No guidance on when to use this tool versus alternatives like 'run_curl'. For a download and mirroring tool, it would be helpful to indicate preferred use cases 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.
Write content to a file, escalating to sudo if the path is protected.
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | File content. | |
| filename | Yes | Destination path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses sudo escalation for protected paths, which is valuable. However, it does not mention overwrite behavior, file creation, or error handling, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains only essential information. Every word earns its place with no redundancy.
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 few parameters and no output schema, the description covers core purpose and a key behavior (sudo). However, it omits important details like whether the file is overwritten or appended, and what happens on failure, making it minimally complete.
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. The description adds context for the filename parameter (sudo escalation) but provides no additional semantics for the content parameter beyond the schema's 'File content.'
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 uses a specific verb 'write content to a file' and clearly identifies the resource. It distinguishes from sibling tools like read_file (reading) and run_* (command execution) by core action. The mention of sudo escalation adds specificity.
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 for writing files, but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or exclusions, relying on sibling names for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0read_filerun_cloudfoxrun_commandrun_curlrun_enum4linuxrun_exploitrun_ffufrun_gobusterrun_httpxrun_hydrarun_johnrun_katanarun_masscanrun_medusarun_ncrackrun_netstatrun_niktorun_nmaprun_nucleirun_phoneinfogarun_searchsploitrun_setoolkitrun_sherlockrun_shodanrun_sqlmaprun_subfinderrun_wafw00frun_wgetwrite_fileScored across 29 tools
Tools cover distinct security testing subdomains, but several have overlapping purposes (e.g., multiple brute-forcers and port scanners). Descriptions help differentiate them, reducing confusion.
Most tools follow a 'run_<toolname>' pattern, but 'read_file' and 'write_file' break the convention, creating inconsistency.
29 tools is on the high side for a penetration testing toolkit but remains within reasonable scope for comprehensive coverage.
Covers major security testing areas (scanning, brute-force, web, OSINT), but lacks post-exploitation and some common utilities like DNS enumeration, leaving notable gaps.
Cybersecurity MCP server for URL scanning, threat intelligence, and domain reputation.
MEOK MCP Hardening MCP — automated security red-team for any MCP server. Maps OWASP LLM Top 10
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
MCP server for building and testing AI agents with multi-model experimentation and insights.
