Allows the server to query a Neo4j graph database for infrastructure relationships, enabling cloud attack path analysis and reachability assessment between internet-facing entry points and valuable resources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@EasyHunt-AI run a nuclei scan on our staging server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An agentic VAPT orchestrator where the control plane — not the model — is the security boundary.
Authorized testing only. Owned assets, an in-scope bug bounty program, or org
assets with documented written approval. The scope.yaml you write is the
authorization boundary, and the server refuses every request that falls outside
it. This tool will not help you test something you have no permission to test.
Most AI security tools give a model a shell and a system prompt telling it to behave. Cordon gives the model no shell at all. Every capability is an MCP tool that passes through a fixed sequence — scope, sanitize, budget, rate-limit, approval, sandbox, parse, audit — enforced in code, server-side, with no path that skips a step. The model supplies strategy. The control plane decides what is permitted. A jailbroken prompt cannot reach the network.
Related MCP server: aegis
Every call descends from L5 to L2 and crosses L3. There is no code path that routes around it — not a wrapper, not a chained validator, not the unattended pipeline.
Six design decisions, each of which came from something breaking in production.
This is the whole thing. A killed scan, a tool that could not write its config, and a genuinely secure target all produce zero findings — and zero findings reads as good news.
flowchart LR
A[nuclei exits 0] --> B{why?}
B --> C[tested 13,391 templates<br/>found nothing]
B --> D[could not write its config<br/>tested NOTHING]
C --> E["findings: 0 ✓"]
D --> E
style D fill:#7f1d1d,color:#fff
style E fill:#78350f,color:#fffBoth branches used to print the same result. Every wrapper now distinguishes tested and clean from not tested, and says which in words:
"zero findings here means UNTESTED, not clean."
Twenty-five instances of this defect have been found and fixed in this codebase
— including nuclei exiting 0 while unable to create its config directory,
and a command-injection tool that discarded its own target flag for the
project's entire life and reported "no injectable parameter" every time.
scope.yaml is transcribed by hand from the program's published policy. The
installer refuses to create one for you — it used to copy a template that
declared authorization: bug-bounty and a fetched_at date nobody had earned,
and three separate green ticks then confirmed it.
An absent scope is a correct state. A fabricated one is not.
The limiter charges per request, not per tool call — so a scanner with its
own thread pool cannot out-run the published ceiling while the audit log shows
one compliant call. Every rate flag is derived from scope.rules, then clamped
to what the binary actually accepts.
pip install nuclei gets you a 2018 Kaggle package. slither on PyPI is a
children's Scratch-for-Python toy. Kali's medusa is a password brute-forcer;
ours is a fuzzer. Cordon executes each candidate and keeps the one that
identifies itself — and never "fixes" a collision by uninstalling your software.
cordon doctor executes every tool inside the container it will actually
run in, under the real read-only root and dropped capabilities. Checking the
host copy answers a question about a different program — that is how tools
shipped broken for days behind a green tick.
Finding.confirm() requires reproduction steps and an observed result. AI
triage may rank, downgrade and drop; a taskflow that declares a confirm
verdict is rejected at load time. Scanner output is a candidate, permanently,
until a human or a validator proves it.
git clone https://github.com/iamsecure1920/Cordon-AI.git && cd Cordon-AI
./bootstrap.shThat is the whole install. bootstrap.sh is idempotent and is also the repair
path: system packages, Go and Python runtimes, Docker enabled at boot, the
Cordon package, the tool suite, the cordon:latest image, the per-tool
images, then cordon doctor.
Budget 30–45 minutes for a first run. Needs ~15 GB free and Python ≥ 3.11.
Flag | Effect |
| skip the image build (≈46 tools then run on the host) |
| skip images entirely — no container isolation |
| package only |
cordon:latest is built from this repo's Dockerfile and is not on any
registry, so docker pull cannot find it. bootstrap.sh builds it, or:
docker build -t cordon:latest .
cp scope.example.yaml scope.yaml
$EDITOR scope.yaml # transcribe the program's published policy
cordon scope validate
cordon doctor # expect 0 brokenIn any MCP-capable AI agent CLI: /cordon, or cordon connect prints the
exact registration for Claude Code, Cursor, Windsurf, Gemini CLI, Copilot, or
any stdio client.
# Unattended, all phases, gated
./scripts/hunt.sh target.example.com
# Several targets
./scripts/hunt.sh a.example.com b.example.com
# Pick phases, or resume
./scripts/hunt.sh target.example.com --only probe,scan
./scripts/hunt.sh target.example.com --from scan
# Exploitation — refused unless scope.yaml permits it. Chains the validators
# over the injection points the earlier phases discovered.
./scripts/hunt.sh target.example.com --exploitEach phase appends to status.jsonl so a human or a model can watch without
touching the run:
{"phase":"probe","state":"ok","tool":"http_probe","seconds":4.1,"produced":248,"findings":0}
{"phase":"cors","state":"failed","tool":"cors_audit","message":"killed at the timeout — UNTESTED, not clean"}One MCP server per engagement phase. Each exposes only that phase's tools plus
the shared control surface — scope_check, job_status, job_list/
job_fetch/job_cancel, fetch_slice, the task graph, brain recall/state,
cordon_status, cordon_capabilities, audit_tail, rules_list — so an
agent does not page through 101 tools to do recon:
Server | Surface |
| subdomain enum, DNS, CDN, TLS, whois, ASN |
| liveness, tech fingerprint, WAF/CORS posture, |
| gau/waybackurls/katana crawling, arjun/paramspider params, content discovery, JS analysis |
| nuclei, jaeles, ports, services, general scanners |
| every injection validator + the auto-chain |
| engagements, resumable pipeline, findings, reports |
Slicing happens at registration time only — every tool still runs through the identical scope → sanitize → budget → rate → approval → audit chain.
Cordon speaks MCP stdio, which Claude Code, Cursor, Windsurf, Gemini CLI,
GitHub Copilot and any other MCP client already understand. Pick the agent and
the phase, and cordon connect prints the exact registration (or runs it for
CLIs that support one-line registration):
# The agent you use is auto-detected; prints the registration for it
cordon connect --phase recon
# Or target one explicitly; Cursor/Windsurf/Gemini/Copilot print the config
# JSON for their mcp.json, Claude Code registers directly
cordon connect --agent claude --phase probe
cordon connect --agent cursor --phase scan --print-only
cordon connect --agent generic # raw stdio command for any MCP client101 MCP tools over 83 catalogued binaries.
· passive · ! aggressive · !! exploit — the mode decides whether a human is consulted.
Category | Binaries |
Recon |
|
HTTP / TLS |
|
Content & params |
|
Scanning |
|
Exploitation |
|
Takeover |
|
Secrets |
|
Cloud |
|
Smart contracts |
|
LLM security |
|
Run cordon doctor for the live picture, and see
USERMANUAL.md for every MCP tool
grouped by phase.
Read this | For |
The invariants. Loaded automatically by the Claude CLI; read it first. | |
The complete reference — install, configuration, API keys, architecture, how the modules interlink, running an engagement, troubleshooting. | |
Every binary: flags, when to reach for it, what it costs. | |
Picking the project up cold: what exists, what is measured, what is left to build. | |
Architecture, bootstrap, payload store, per-class techniques. |
.venv/bin/python -m pytest tests/ -q # 2,268 tests
.venv/bin/ruff check cordon/ tests/
cordon doctor # executed, not just found on PATHNearly every test in the suite exists because something broke against a live target. That is the working loop: run it against something real, distrust every clean result, verify hits by hand, fix the class rather than the instance, encode the bug in a test, then re-measure.
See LICENSE. Third-party tools retain their own licenses — several are
AGPL-3.0, and nmap ships under a custom non-OSI license. cordon doctor
prints the license of every tool it finds.
[AGGRESSIVE — requires human approval] Create a test account and register the resulting session.
This is the one action in the authenticated toolchain that creates state
rather than reading it, so it is refused unless the program said it may
happen: rules.allow_self_registration in scope.yaml, which is
transcribed from the program's published policy and defaults to false.
signup_url is the form's action (where the signup POST goes).
username_field/password_field/email_field name the form fields.
Credentials default to generated values; pass them to register a specific
account. The session that comes back (cookies + headers) is registered
under name so authz_compare can use it immediately.
The response is masked; the generated credentials are returned once so the operator can store them, and never logged.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| name | No | ||
| role | No | user | |
| No | |||
| password | No | ||
| username | No | ||
| signup_url | Yes | ||
| email_field | No | ||
| password_field | Yes | ||
| username_field | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses that it requires human approval, creates state, returns masked credentials that are never logged, and that the session can be used by authz_compare.
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 well-structured, front-loading the approval requirement and then detailing parameters and behavior. It is concise and free of 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?
It provides context about the tool's place in the authenticated toolchain, the approval mechanism, and the subsequent use of the session. It does not detail the output schema or error handling, but the essential information is present.
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?
It explains the meaning of signup_url, username_field, password_field, email_field, and name, and notes that credentials default to generated values. However, it omits descriptions for host and role.
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 that the tool creates a test account and registers the session, and it identifies itself as the one action in the toolchain that creates state, distinguishing it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that it requires approval and is refused unless rules.allow_self_registration is set, and it contrasts with other actions that read state. However, it does not explicitly name alternative tools or conditions for when to use them instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List aggressive actions parked awaiting human approval.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates a non-mutating operation, and the description aligns with that by using 'List'. The phrase 'parked awaiting human approval' adds minor context about the state of the listed items, but no further behavioral details are provided.
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 directly states the tool's function without unnecessary words. It is well-structured and easy to parse.
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 read-only listing tool with no parameters, the description is mostly complete. It clearly states what is listed, though it does not specify the output format or any filtering options, which could be considered a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the schema coverage is 100%. Since there are no parameters to describe, the 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 clear verb 'List' and specifies the resource 'aggressive actions parked awaiting human approval', making the tool's purpose unambiguous. It stands out from sibling tools by focusing on pending approvals.
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 approval_respond or other listing tools. No conditions, prerequisites, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Relay a HUMAN decision on a parked approval. Do not call this on your own initiative — only when a person has told you their decision.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| token | Yes | ||
| decision | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description transparently indicates that this tool relays a human decision (implying a state change to an approval) and includes a behavioral constraint against autonomous invocation. However, it does not detail specific side effects (e.g., notifications, audit logs) beyond the core action, so a slight deduction is warranted.
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 concise (two sentences), front-loaded with the primary purpose, and includes a clear usage caveat. It avoids unnecessary wording and efficiently communicates the necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool and the presence of an output schema (noted in context), the description covers the essential context: what it does, when to use it, and the caution. It does not explicitly explain parameter values or return format, but the parameter names and output schema likely compensate for that; a slightly richer explanation would make it fully 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?
The schema provides zero descriptions for the three parameters (note, token, decision), and the description does not clarify their meaning or expected values. While parameter names are somewhat self-explanatory, the description fails to compensate for the lack of schema-level detail, leaving some ambiguity for critical inputs like 'decision'.
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's purpose (relaying a human decision on a parked approval) with a specific verb ('relay') and resource ('parked approval'). It also distinguishes from autonomous use by explicitly noting it should only be called when a person has provided a decision.
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 explicit usage guidance: 'only when a person has told you their decision' and instructs 'Do not call this on your own initiative.' This leaves no ambiguity about when the tool should or should not be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up ASN and netblocks for a domain or organization.
Netblocks are returned for context only — an ASN belonging to the target does not put its ranges in scope. Check anything you find with scope_check before touching it.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint and destructiveHint annotations, explicitly stating that data is 'returned for context only' and that scope must be verified separately. It does not mention any rate limits or potential external side effects, but the openWorldHint annotation already covers external access, so the description adds meaningful scope-related transparency.
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 two sentences long, front-loads the primary action, and packs the essential caveat about netblocks and scope into a concise follow-up. Every sentence adds value 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?
The description mentions that the tool returns ASN and netblocks, which is the core output expectation, and the scope caveat adds important context. However, with no output schema, it does not explain the structure of the response, possible error conditions, or whether an organization name is resolved differently from a domain, leaving some gaps for a simple lookup 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?
The schema provides no description for the required 'target' parameter (0% coverage), and the description only says it can be a 'domain or organization' without specifying accepted formats, examples, or whether IPs are supported. This is insufficient compensation for the complete lack of schema-level parameter documentation.
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 'Look up' and the resource 'ASN and netblocks for a domain or organization', making the core purpose unambiguous. However, it does not explicitly distinguish itself from sibling recon tools like whois_lookup or dns_resolve, so it misses the top score for explicit sibling differentiation.
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 useful operational guidance by noting that netblocks are for context only and advising to check scope before touching anything. However, it does not explain when to prefer this tool over alternatives or when not to use it, so the usage guidance remains implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent audit records, including refusals. The engagement's evidence trail.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate read-only behavior (readOnlyHint true). The description adds that it includes refusals and is the evidence trail, but does not elaborate on side effects, data scope, or any other behavioral nuances beyond what annotations convey.
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 brief, with two sentences that directly convey the tool's purpose without any redundant or filler content. It is optimally 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 simple read-only nature of the tool and the presence of an output schema (indicated in context), the description is largely complete. It could potentially mention the default count or filtering behavior, but the essential context is covered.
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 includes a single 'count' parameter with a default, but the description does not explain how count affects results. The schema provides type and default, but without semantic meaning the parameter remains underspecified.
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 returns recent audit records and positions it as the engagement's evidence trail. It effectively conveys the core purpose, though it does not explicitly contrast with sibling audit tools like cloud_audit or code_audit.
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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or context. It simply states what it is, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Crawl an application as a registered session and map what is behind the login.
session names a session from session_register; it is only sent to the
host it was issued for.
Before crawling, the entry point is fetched with and without the session. If the two responses are identical the session authenticates nothing, and the crawl is refused — a list of public pages labelled "authenticated surface" would poison every conclusion drawn from it.
When a page turns out to be a single-page-app shell, its same-origin script
bundles are fetched and mined for paths — API literals, request call sites,
and the route table. Those become crawl seeds under the same guards as a
link, and are counted separately in coverage so it is visible how much
of the map a link crawler alone would have missed. max_bundles bounds
the extra requests.
Returns the discovered URLs, the forms found (read-only ones submitted with
empty values, state-changing ones reported and never touched), and — the
useful part — the URLs carrying an object reference, which is what
authz_compare must be pointed at. A URL with no identifier in it belongs
to everyone and proves nothing about access control.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| session | Yes | ||
| timeout | No | ||
| max_depth | No | ||
| max_pages | No | ||
| max_bundles | No | ||
| liveness_every | No | ||
| max_form_submissions | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is transparent about the tool's aggressive nature, the need for human approval, the session isolation behavior, and the handling of single-page-app bundles and state-changing forms. It explicitly states it never touches state-changing form submissions. No contradiction with the provided annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear paragraphs, each covering a distinct aspect (purpose, authentication check, SPA handling, output). It is concise and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the tool's output (discovered URLs, forms, object references), its relationship with authz_compare, and its place among other tools. It covers the key context needed for an agent to decide when and how to use it, including the human approval requirement and the refusal condition.
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 description explains only 'session' and 'max_bundles' in passing. Other parameters like target, timeout, max_depth, max_pages, liveness_every, and max_form_submissions are not described beyond their schema types and defaults. With 0% schema description coverage, the description does not compensate for the missing parameter explanations.
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 crawls an application as a registered session to map the authenticated surface. It uses specific verbs and distinguishes its output (URLs with object references) from sibling tools like authz_compare and auth_surface.
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 explains when to use the tool (to discover authenticated endpoints), explicitly mentions it requires human approval, and describes the refusal condition when the session authenticates nothing. It also instructs the user to point authz_compare at the discovered object-referencing URLs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect authentication functionality and rank hosts by account-worthiness.
target takes one host or a comma-separated list — normally the live
URLs http_probe found, which is how scripts/hunt.sh chains it. Targets
are scope-checked before this body runs, so the list cannot be widened here.
Every request is a GET against a conventional path. Nothing is submitted,
no account is created, and no credential is sent. The output is a
recommendation to a human: register on these hosts, by hand, if the
program's rules permit it — then bring the sessions back with
session_register and authz_compare can finally test authorization.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| timeout | No | ||
| max_hosts | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description adds specific behavioral details: 'Every request is a GET against a conventional path. Nothing is submitted, no account is created, and no credential is sent.' This fully clarifies the tool's safe, non-intrusive nature.
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 slightly verbose with multiple paragraphs, but each sentence serves a purpose—purpose, usage context, safety, and output—so it remains well-structured and not overly long.
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?
The description covers what the tool does, how it's used in a pipeline, its safety, and its output ('a recommendation to a human'). It also mentions next steps (session_register, authz_compare), providing sufficient context for an agent to decide when to invoke it.
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 the 'target' parameter is explained ('takes one host or a comma-separated list'). The other parameters ('timeout' and 'max_hosts') are not described, and schema description coverage is 0%, so the description must compensate but only does so partially.
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's purpose with a specific verb ('Detect' and 'rank') and resource ('authentication functionality' and 'hosts by account-worthiness'). It distinguishes itself from sibling tools like authz_compare and account_register by focusing on detection and ranking for manual registration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context on when to use it: 'normally the live URLs `http_probe` found' and that it's part of a script chain. It also explains the intended workflow (register manually, then use session_register and authz_compare). While it doesn't explicitly compare to alternatives, the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Fetch one URL as two identities and report whether the server told them apart.
The core authorization test. If A can read A's resource and B can read it too, the server is not checking ownership — that is an IDOR. If B is refused, it is.
Restricted to GET and HEAD on purpose. Proving broken access control never requires writing: reading another user's record is the proof, and writing to it modifies data that is not yours, which every program in this space forbids outright.
Reports a CANDIDATE, never a confirmed finding. Two identical responses can also mean the resource is public, or that neither session is actually authenticated. The result says which checks would settle it.
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | GET | |
| target | Yes | ||
| session_a | Yes | ||
| session_b | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: readOnlyHint is false, but the description states the tool is restricted to GET/HEAD, which are read-only methods. This is a direct conflict—an agent following the annotations may expect side effects, while the description claims safety. The description otherwise adds useful context about candidate vs confirmed findings, but the contradiction overrides that.
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 longer than minimal but every sentence adds value—purpose, rationale for method restriction, and the candidate vs confirmed nuance. It is front-loaded with the core action and reasoning, making it easy to scan.
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 presence of an output schema and the tool's focused scope, the description covers the essential decision-making context: what it does, why it is safe, and how to interpret results. It could mention prerequisites (e.g., authenticated sessions) but these are implied and covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the burden. It explains the purpose of target (the URL), session_a and session_b (two identities), and method (restricted to GET/HEAD, default GET). This adds meaning beyond the bare parameter names, though it does not detail session formats or edge cases.
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 (fetch), the resource (one URL), and the specific goal (compare server responses for two identities to detect authorization flaws). It distinguishes this tool as the core authorization test, setting it apart from the many scanning and recon siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly frames when to use this tool (core authz test) and gives strong guidance on method restriction (GET/HEAD) with reasoning. It does not name alternatives but provides enough context for an agent to know this is the right tool for comparing access control between two sessions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map attack surface with BBOT. The primary recon entrypoint.
Presets: subdomain-enum (default), cloud-enum, code-enum, email-enum, web-basic, baddns, fast. Aggressive presets (web-thorough, spider, paramminer, web-screenshots, baddns-thorough, kitchen-sink) are routed through bbot_scan_active instead, which requires approval.
Returns inline if the scan finishes within wait_seconds; otherwise returns a job_id — poll it with job_status and read results with fetch_slice.
| Name | Required | Description | Default |
|---|---|---|---|
| preset | No | subdomain-enum | |
| target | Yes | ||
| modules | No | ||
| max_events | No | ||
| wait_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses key behaviors: it can return inline if the scan finishes within wait_seconds, otherwise it returns a job_id and directs to poll with job_status and read with fetch_slice. This is valuable operational behavior not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: one sentence for purpose, a compact list of presets, a sentence about aggressive presets routing, and a clear explanation of return semantics. No fluff or unnecessary detail.
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?
The description provides essential context for choosing this tool over similar siblings: it names the aggressive presets that go to bbot_scan_active and explains the inline vs. job_id return mechanism. It also positions the tool as the primary recon entrypoint, which is sufficient for an agent to decide when to invoke it.
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 description explains the preset parameter by listing its valid values and mentions wait_seconds behavior. However, it does not explain the modules parameter (what modules can be specified) or max_events (its purpose or effect). With 0% schema description coverage, these gaps leave the agent partially uninformed about two 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 maps attack surface via BBOT and identifies it as the primary recon entrypoint. It distinguishes from the sibling bbot_scan_active by specifying which presets are routed there.
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 explicitly lists the available presets and the default, and explains that aggressive presets are routed to bbot_scan_active which requires approval. It also explains the return behavior and how to poll and read results, giving clear guidance on when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Actively probe with BBOT (web-thorough, spider, paramminer, screenshots).
Requires human approval. Prefer bbot_scan first: active probing on an unmapped surface wastes the program's rate limit on hosts you have not yet established are interesting.
| Name | Required | Description | Default |
|---|---|---|---|
| preset | No | web-thorough | |
| target | Yes | ||
| modules | No | ||
| max_events | No | ||
| wait_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is not read-only and not destructive, and the description adds that the tool is aggressive, active, consumes rate limits, and requires approval. It could mention more side effects, but the key behavioral implications are disclosed.
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 brief and front-loaded with the most important risk and usage information: aggressive, requires approval, prefer bbot_scan first. There is no filler or redundant wording.
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?
The description covers purpose, risk, and ordering relative to bbot_scan, but it omits parameter documentation and does not explain what output or return behavior to expect. Given the output schema exists, a bit more behavioral context would help.
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 schema has five parameters but zero description coverage. Only 'web-thorough' hints at the preset value; target, modules, max_events, and wait_seconds are left undefined, so the agent must infer their meaning from names alone.
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 actively probes with BBOT and names the involved techniques (web-thorough, spider, paramminer, screenshots). It also distinguishes itself from the sibling bbot_scan tool by explicitly recommending bbot_scan first, so an agent can tell what this tool does.
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 explicitly states that human approval is required and gives concrete when-to-use/when-not-to-use guidance: prefer bbot_scan first because active probing on an unmapped surface wastes rate limits. This is strong actionable usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The brain's episodic memory: what happened before, in order — every sensed tool call across engagements, filterable by phase, tool, or outcome. This is the 'what failed, what succeeded, what was a false positive, what was a true finding' record the synapse weights cannot express on their own.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No | ||
| event | No | ||
| limit | No | ||
| phase | No | ||
| outcome | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates no side effects, and the description reinforces this by referring to a 'record' and 'what happened before'. It adds context about the content (failures, successes, false positives, true findings) but does not detail output format or limitations. Since annotations cover the key behavioral trait, the description adds some but not extensive value.
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 two sentences, front-loading the purpose. There is slight redundancy between 'what happened before, in order' and the enumeration of outcomes, but it remains concise and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema is present (from context), and the description gives a clear sense of what data is returned (historical tool calls across engagements) and how it can be filtered. The omission of 'event' and 'limit' semantics is a minor gap, but the overall context is sufficient for an agent to decide when to invoke this 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?
The description explicitly mentions three of five parameters as filters ('phase, tool, or outcome'), but leaves 'event' and 'limit' unexplained. With zero schema description coverage, this partial explanation is helpful but incomplete.
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 this tool retrieves a historical record of tool calls ('every sensed tool call across engagements') with filtering options ('filterable by phase, tool, or outcome'). The metaphorical language ('brain's episodic memory') does not obscure the core purpose.
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 does not provide explicit guidance on when to use this tool versus sibling tools like brain_recall or memory_recall. It only describes what it does, without stating conditions such as 'use this when you need to review past tool executions' or contrasting with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Teach the neuron brain an observed outcome: a validator HIT, a CLEAN pass, or a FALSE_POSITIVE (the scanner fired and was wrong). The brain uses these to rank future plans and to suppress known-FP tools on similar targets. Use after a validator run, or when triage drops a finding — teaching it the false positive is what stops the same noise being re-filed next engagement. Stores methods and outcomes only.
| Name | Required | Description | Default |
|---|---|---|---|
| outcome | Yes | ||
| technique | Yes | ||
| vuln_class | Yes | ||
| waf_vendors | No | ||
| technologies | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and openWorldHint=false, so the tool mutates state. The description adds behavioral context: it stores 'methods and outcomes only' and explains the downstream effect (ranking and suppression). It doesn't disclose side effects like whether existing data is overwritten or if there are idempotency constraints, but the key behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with no redundancy. The first sentence establishes the core action, the second explains the purpose, the third gives usage context, and the fourth clarifies storage scope. Information is front-loaded and each sentence 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?
The tool has an output schema, so return values are covered. The description explains when to use, what it does, and what it stores. It lacks explicit parameter documentation, but given the tool's simplicity and the presence of an output schema, it's largely complete. The main gap is parameter semantics, but that's already accounted for in that dimension.
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 0%, so the description must explain parameters. It defines outcome values (HIT, CLEAN, FALSE_POSITIVE) and mentions 'methods' (likely technique) and outcomes, but it doesn't explicitly describe vuln_class, waf_vendors, or technologies. While it gives some meaning to outcome, the other parameters remain ambiguous. The description partially compensates but not fully.
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's purpose: teaching the brain an observed outcome (HIT, CLEAN, FALSE_POSITIVE) to influence future plan ranking and suppress false-positive tools. It distinguishes itself from sibling tools like brain_recall (querying) and brain_state (viewing) by emphasizing the 'learn' action. Specific verb 'Teach' and resource 'neuron brain' with concrete outcomes.
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?
Provides explicit triggers for use: 'Use after a validator run, or when triage drops a finding.' This clearly indicates when to call the tool. It doesn't mention alternatives or when not to use, but the context is specific enough for an agent to decide. It explains the benefit of teaching false positives, which reinforces the use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the neuron brain has LEARNED about testing this kind of target: which validators/techniques actually paid off on this vulnerability class with this observed technology stack and WAF, ranked by cross-engagement experience. Consult before choosing validators or designing a test plan — the brain remembers outcomes the static index cannot. Empty results mean no prior experience on this shape; proceed from the technique index.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| vuln_class | Yes | ||
| waf_vendors | No | ||
| technologies | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=true and openWorldHint=false, so the base behavior is transparent. The description adds useful behavioral context beyond that: it explains that the tool returns ranked validators based on cross-engagement experience and that empty results signal no prior knowledge. This enriches the agent's understanding of what to expect, aligning with the lower bar set by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and well-structured, front-loading the purpose and then providing usage guidance and fallback behavior. Every sentence adds value, with no redundant or filler content. The format is easy to parse and directly actionable.
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 that an output schema exists, the description does not need to detail return values. It adequately covers when to use the tool, what it provides, and how to interpret empty results. It also distinguishes itself from the technique index. The context is sufficient for an agent to decide whether to invoke this tool, though a bit more specificity about the ranking criteria could push it to a perfect score.
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 0%, so the description must compensate. It does reference the key parameters implicitly: 'vulnerability class' maps to vuln_class, 'technology stack' to technologies, and 'WAF' to waf_vendors. However, it does not explicitly explain the 'limit' parameter or provide detailed semantics for each field. The parameter names are self-explanatory, but coverage is incomplete, warranting a mid-range 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 explicitly states the tool's purpose: recalling what the 'neuron brain' has learned about testing, specifically which validators/techniques were effective for a given vulnerability class, technology stack, and WAF. It uses a clear verb ('recall') and identifies the resource (brain knowledge) and the output (ranked techniques). It also distinguishes itself from the static index, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: 'Consult before choosing validators or designing a test plan.' It also indicates when not to use it by stating 'Empty results mean no prior experience on this shape; proceed from the technique index,' which contrasts with alternative sources. This gives clear decision criteria for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the neuron brain senses right now: the phase and tool currently running, the most recent tool calls, and the memory store's stats. The brain senses every tool call through the audit log, so this is a live pulse of the whole engagement, not a report.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation indicates no side effects, and the description supports that by calling it a 'live pulse' and 'not a report'. It doesn't mention any side effects, so it's transparent. Credit for annotation.
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 slightly verbose with redundant metaphor ('neuron brain senses') but overall it's short and structured. It could be more concise but acceptable.
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?
It covers what the tool provides (phase, tool, recent calls, memory stats) and distinguishes it from a report. Given the lack of parameters and output schema, this is sufficient 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?
The tool has no parameters, so the description doesn't need to explain any. Baseline for zero-param tools is 4, and the description doesn't conflict.
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 provides current state: phase, running tool, recent calls, and memory stats. The metaphorical language 'neuron brain senses' slightly obscures but the explanation 'live pulse' clarifies. Overall, purpose 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 notes it's 'not a report' and gives a live view, which hints at usage. But it doesn't explicitly contrast with other status tools like dashboard_state or job_status. It lacks explicit when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Verify a candidate in a real browser and capture evidence.
url is the target URL. param names a query parameter and payload
is what to put in it (an XSS payload, a canary token, a URL for open
redirect — passed unescaped; this tool builds the URL itself). The
browser loads the page and reports:
reflection — raw / escaped / none (unescaped reflection
of the payload is a reflected-XSS candidate),
executed — whether the payload ran (dialog, page error, or console
message containing it) — the strongest signal,
redirect — final_url host differing from the requested host
(open-redirect candidate),
console messages and page errors,
screenshot / dom_excerpt — saved to the workspace evidence/
dir and referenced from the filed finding.
A finding is filed for raw reflection (MEDIUM), execution (HIGH), or a
host-changing redirect (LOW) — all needs_manual_review with the
screenshot as evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| param | No | ||
| payload | No | ||
| screenshot | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds critical behavioral context beyond annotations: it requires human approval (AGGRESSIVE tag), it builds the URL itself with an unescaped payload (which could trigger dangerous actions), it files findings with severity levels, and it captures screenshots. These are not in the annotations (readOnlyHint false, openWorldHint true, destructiveHint false), so the description carries the burden well. It doesn't mention all side effects (e.g., network requests) but covers the essential ones.
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 well-structured with a leading warning, a clear purpose, and bullet-like output details. It is moderately lengthy but each sentence adds value, explaining the tool's behavior, output fields, and finding logic. It could be tightened slightly, but the structure is logical and front-loads the most important constraint (approval) and 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 (browser, security testing) and the presence of an output schema, the description covers the key outputs (reflection, executed, redirect, console, screenshot) and the finding levels. It also mentions evidence storage and that findings are marked needs_manual_review. It lacks explicit error handling or prerequisites, but the description is sufficiently complete for an agent to call it correctly. The output schema likely covers the return structure, so the description doesn't need to repeat it.
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?
With 0% schema description coverage, the description fully compensates by explaining url, param, and payload in detail, including that payload is passed unescaped and the tool constructs the URL. It also implies the screenshot parameter by describing evidence capture. The description gives semantic meaning that the schema's bare parameter names lack.
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 action ('Verify a candidate in a real browser and capture evidence') with clear outputs (reflection, executed, redirect) that distinguish it from sibling validation tools like xss_validate or sqli_validate. The verb 'verify' and the resource 'candidate' are concrete, and the mention of 'capture evidence' differentiates it from mere probes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage when a candidate needs browser-level confirmation (reflected XSS, execution, open redirect) and mentions the filing of findings. However, it does not explicitly state when NOT to use it or name alternatives, leaving some inference to the agent. The context of 'verify a candidate' suggests it follows detection, but no exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Send one HTTP request per target through the operator's Burp proxy.
target is one or more comma-separated URLs (at most
BURP_HANDOFF_MAX_TARGETS); every one is scope-checked before anything
is sent. method is one of GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS.
headers overrides the default tagged User-Agent; body is the
request body for POST/PUT/PATCH.
Each request goes through the local Burp proxy (tools.burp.proxy_url
in config.yaml), lands in Burp's history, and the responses are returned so
the caller can attach them to leads. If Burp is not listening the call
fails with burp_not_running — start Burp and retry.
This is a human-handoff primitive, not a scanner: one request per target, nothing automated, and the classes it serves (IDOR, business logic, race conditions, cache poisoning) are exactly the ones that end in a human reading a request.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | ||
| method | No | GET | |
| target | Yes | ||
| headers | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description transparently discloses that the tool requires human approval (AGGRESSIVE), goes through the Burp proxy, records in Burp history, and fails if Burp is not listening. No contradiction with annotations (readOnlyHint=false is consistent with sending requests).
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 slightly verbose, repeating 'one request per target' and 'human-handoff primitive' multiple times. However, the structure is clear and the extra detail is useful, so it only loses one point for 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?
The description provides sufficient context for a simple tool, including scope-checking, approval, and failure behavior. It lacks information about the return format, but given the tool's purpose as a human handoff, this is a minor gap. Overall, it is complete enough for correct 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?
The description explains each parameter: target (comma-separated URLs, max from constant), method (list of allowed verbs), headers (overrides default User-Agent), and body (for POST/PUT/PATCH). It also notes defaults and nullable fields, adding meaning beyond the bare 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 sends an HTTP request through the operator's Burp proxy, distinguishing it from a scanner. It explicitly mentions 'human-handoff primitive' and lists example use cases (IDOR, business logic, race conditions, cache poisoning), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: for cases that end in human reading a request, and explicitly states it is not a scanner. It also mentions scope-checking and human approval requirements, giving clear selection criteria relative to sibling scanning tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify which hosts sit behind a CDN, WAF, or cloud provider.
Worth running before any port scan: scanning a CDN edge tells you about the CDN, wastes the program's rate limit, and occasionally violates the CDN's own terms rather than the target's.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions that scanning may violate the CDN's terms, which adds behavioral nuance beyond the read-only annotation. It implies network probing but does not fully detail the exact requests or side effects, so it falls short of full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences that are well-structured and to the point. It efficiently conveys purpose and usage guidance without unnecessary verbosity.
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?
While the description covers purpose and usage advice, it does not describe the output format or any additional details an agent might need to interpret the results, leaving some contextual gaps.
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 schema defines a single required parameter 'target' with no description, and the tool description does not elaborate on its format or expected values. This leaves the parameter ambiguous and under-specified.
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's purpose: identifying hosts behind a CDN, WAF, or cloud provider. It also gives context on when it is useful, making the intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends running this tool before any port scan and explains the reasoning, providing clear guidance on when to use it. It does not, however, mention alternative tools or conditions for not using it, so it is not a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Discover public cloud storage by guessing names from a keyword.
Runs cloud_enum and S3Scanner. Every discovered bucket is checked against the engagement scope and against ownership evidence before it counts — name similarity is not ownership.
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | ||
| providers | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond the annotations: it says the tool is aggressive, requires human approval, runs specific external scanners, and applies verification steps (checking against engagement scope and ownership evidence). This adds transparency not present in the readOnlyHint or destructiveHint flags.
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 concise and well-structured: it opens with a warning, states the purpose, and then adds relevant details about the tools used and the verification steps. It contains no unnecessary 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?
The description gives a solid overview but lacks details about the return format (despite having an output schema) and does not explain the optional providers parameter. Nevertheless, it provides enough context for the primary use case.
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 schema has two parameters: keyword (string, required) and providers (array of strings, optional). The description explains the role of keyword ('guessing names from a keyword') but provides no information about the providers parameter. Since schema descriptions are absent, the description only partially compensates for the parameter semantics.
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's purpose: 'Discover public cloud storage by guessing names from a keyword.' It specifies verb (Discover) and resource (public cloud storage), and distinguishes it from siblings by mentioning that it runs cloud_enum and S3Scanner.
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 usage guidance by labeling the tool as 'AGGRESSIVE — requires human approval,' indicating caution and the need for authorization. It also notes that results are filtered against engagement scope and ownership. However, it does not explicitly compare with alternative discovery tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Build attack paths from cloud configuration (Prowler + Cartography graph).
Turns a list of misconfigurations into reachability: which public entry points lead to which privileged roles, and in how many hops. That chain is what makes a cloud finding worth a severity rating.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | default | |
| max_hops | No | ||
| provider | No | aws |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly=false, destructive=false), the description adds the 'AGGRESSIVE — requires approval' trait, which is important behavioral information. It does not clarify other potential side effects, but this extra disclosure is valuable.
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 concise and well-structured. The action verb 'Build' appears in the first sentence, followed by a clear explanation of the output. No redundant information is included.
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?
The description explains the tool's purpose but lacks parameter semantics and does not describe the output structure beyond a high-level concept. Even though an output schema exists, it is not shown, and the description does not cover what the agent needs to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for parameters, and the description does not mention 'profile', 'max_hops', or 'provider' at all. Since the schema provides no descriptions, the description fails to compensate, leaving these parameters undefined.
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 builds attack paths from cloud configuration, and explains the output as reachability from public entry points to privileged roles with hop counts. This is specific and distinguishes it from sibling tools like cloud_asset_discovery or cloud_permissions.
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 when you have a list of misconfigurations and need to assess severity via reachability. It does not explicitly contrast with alternatives, but the purpose is distinct enough for an agent to infer when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Audit cloud posture with Prowler and ingest failed checks as findings.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | default | |
| provider | No | aws | |
| services | No | ||
| severity | No | high,critical |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and open-world behavior, but the description adds value by explicitly warning 'AGGRESSIVE — requires human approval' and stating that failed checks are ingested as findings, which implies a write operation. This is consistent with annotations (readOnlyHint=false, destructiveHint=false) and adds the approval requirement beyond what annotations cover.
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 a prominent warning prefix. It's concise and front-loads the critical approval requirement. No fluff, but it sacrifices parameter detail for brevity, which is acceptable given the other dimensions.
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?
The tool is complex (external audit, findings ingestion) and has 4 parameters with no descriptions. The presence of an output schema likely documents findings, but the description omits parameter semantics and any guidance on expected inputs or behavior. An agent would need to guess how to set services or severity correctly. The lack of context on what happens after ingestion (e.g., where findings go) leaves gaps.
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?
With 0% schema description coverage, the description must explain parameters, but it doesn't mention profile, provider, services, or severity. An agent cannot infer what 'services' means (e.g., which AWS services to audit) or how severity filtering works. The defaults exist but their semantics are opaque. This is a significant gap.
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 (audit), the resource (cloud posture), the tool (Prowler), and the outcome (ingest failed checks as findings). It distinguishes itself from siblings like cloud_asset_discovery or cloud_attack_paths by specifying the audit-and-ingest behavior. The aggressive/approval warning is front-loaded and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but gives no explicit guidance on when to use it versus alternative tools like k8s_posture or cloud_permissions. It doesn't mention conditions like 'use when you need to check cloud compliance' or 'prefer this over cloud_asset_discovery for failed checks'. The approval requirement hints at its seriousness but doesn't provide routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Map principals, permissions, and privilege-escalation paths with CloudFox.
Requires credentials the program gave you. Read-only enumeration.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | default | |
| provider | No | aws |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There is a direct contradiction: the description claims 'Read-only enumeration' while the annotation readOnlyHint is false, meaning the tool is not read-only. This is a serious inconsistency. Additionally, openWorldHint true suggests potential external side effects, further conflicting with the read-only claim. The description does not disclose any behavioral traits beyond the contradictory read-only statement, and annotations are not adequately reflected.
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 concise and front-loaded with the critical warning '[AGGRESSIVE — requires human approval]'. Each sentence adds information: the first defines the function, the second gives credential requirements and a read-only claim. There is no fluff, but the read-only claim is misleading and detracts from structure quality.
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 an output schema, the description is sparse. It does not explain what the output looks like, what parameters affect, or how it differs from similar cloud tools. The low schema coverage (0%) places a heavy burden on the description, which it fails to meet. The tool appears moderately complex, yet the description leaves many gaps.
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 0%, and the description does not mention the parameters (profile and provider) at all. Since the schema itself lacks parameter descriptions, the description fails to compensate for the lack of semantic meaning. An agent would not know what values to provide for profile or provider or what they control.
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 a specific action ('Map principals, permissions, and privilege-escalation paths') and names the tool (CloudFox). It is not a tautology and gives a clear resource focus. However, it does not differentiate from sibling tools like cloud_attack_paths or cloud_asset_discovery, which could overlap in purpose.
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 gives a prerequisite ('Requires credentials the program gave you') and states it is read-only enumeration, which implies appropriate contexts. But it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or conditions where other tools are preferred. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Detect OS command injection with commix. Detection only, never a shell.
parameter restricts testing to one parameter; leave it unset to let
commix test every parameter it finds in the URL. level (1-2) widens the
payload set.
The techniques available here are classic, eval-based and time-based — the three that answer "does this execute" by observing output or delay. File-based is excluded: it proves the same thing by writing a file into the target's web root, which is a change to the target, not evidence.
Read the tool-availability note if this returns UNTESTED. PyPI's
commix package is not commixproject/commix; it is an unrelated 2019
package that only knows how to print a banner. This spec carries an identity
marker so the impostor is refused rather than run — a refusal here means the
real tool is missing, and the surface is untested.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ||
| target | Yes | ||
| parameter | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description claims 'never a shell' and explicitly excludes file-based techniques because they 'change the target', but annotations mark destructiveHint=true and readOnlyHint=false. This is a direct contradiction about whether the tool may alter or damage the target.
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 compact and mostly purposeful; the PyPI identity-marker note is somewhat tangential but relates to avoiding a fake package. Overall it stays focused and front-loads the key behavior.
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?
Provides enough operational detail to invoke correctly: target, optional parameters, safety constraints, and technique limitations. Output schema exists but is not shown, so the lack of output explanation is acceptable.
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 no parameter descriptions, but prose explains that parameter restricts testing to one parameter and level widens the payload set. 'target' is not described but is obvious from the tool's purpose and required status.
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 it detects OS command injection using commix, explicitly limits to detection ('Detection only, never a shell'), and distinguishes itself from exploitation tools. The resource (target URL with optional parameter) and action (probe) are obvious despite the 'EXPLOIT' label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains parameter and level mechanics but does not say when to choose this tool over the many sibling injection/validation tools. It gives a boundary ('detection only') but no explicit use-case comparison or trigger condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the white-box code audit over source in the engagement workspace.
Scans path (relative to the workspace, default source — the
directory source_fetch clones into) with Semgrep's parsing rules and
gitleaks, then writes a merged deliverable:
code-audit.json — structured, redacted records from both tools.
code-audit.md — human-readable audit with attack-surface
implications.
Semgrep hits are filed as CANDIDATE findings (reachability is a later question — static analysis finds sinks, not exploits). Gitleaks hits are redacted and kept in the deliverable only: unvalidated regex matches are not findings, and the secret-scanning phase owns that class.
With no source in the workspace the phase reports count: 0 — run
source_fetch(repo_url=...) first and confirm the repository belongs to
the program.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | source | |
| wait_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context beyond annotations: it explains that Semgrep hits are filed as CANDIDATE findings (not exploits) and that gitleaks hits are redacted and kept only in the deliverable, not as findings. It also details the output files. This enriches the agent's understanding without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core action, followed by concise bullets and clarifying notes. It avoids fluff—every sentence adds either behavioral detail, parameter context, or usage guidance. The formatting (code blocks, bullets) makes it scannable.
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 presence of an output schema (not shown but indicated), the description sufficiently covers what an agent needs: it explains the tool's inputs (path), outputs (two files with their formats), the distinction between findings and candidates, and the prerequisite for using it (source_fetch). It also addresses the no-source case. This is comprehensive for a read-only audit tool with clear 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?
Schema coverage is 0%, so the description carries the burden. It explains the 'path' parameter (relative to workspace, default 'source') and its relationship to source_fetch, but does not mention 'wait_seconds' at all. Since wait_seconds is a numeric parameter with a default, its purpose is inferable, but the description adds no explicit meaning. Partially compensates but leaves one parameter unexplained.
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's purpose: 'Run the white-box code audit over source in the engagement workspace.' It specifies the exact resource (source code) and the two scanning tools (Semgrep and gitleaks), and differentiates itself from siblings like semgrep_scan and secret_scan by describing a merged audit deliverable. The verb 'run' and resource 'white-box code audit' make it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it instructs the agent to run source_fetch first if no source exists, and to confirm repository ownership. It also clarifies what the tool does NOT do (unvalidated gitleaks regex matches are not findings), preventing misuse. This exceeds basic when-to-use guidance by naming a prerequisite and exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Brute-force paths with ffuf, at the engagement's rate limit.
wordlist is either a name from the vetted payload store ("admin",
"juicy-paths", "api-routes" — call payload_catalog for the list) or a
path to a file inside the engagement workspace.
There is no default. The size of the wordlist is the size of the impact on the target, and that should be a deliberate choice.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| wordlist | Yes | ||
| extensions | No | ||
| max_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the tool is aggressive, requires human approval, respects the engagement's rate limit, and warns that wordlist size affects target impact. This adds useful behavioral context beyond the openWorldHint and destructiveHint values.
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 relatively compact but includes some redundancy, such as repeating the AGGRESSIVE warning and the impact statement. The sentence 'The size of the wordlist is the size of the impact on the target...' is slightly verbose but not overly long.
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?
The tool has an output schema, so omitting output details is acceptable. However, the description lacks practical context such as typical use cases, dependency on prior recon, or how the tool fits into a larger workflow. It covers safety and wordlist semantics but not enough for full operational 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?
Only the 'wordlist' parameter is explained in detail (vetted payload store names or file paths, no default). The 'target', 'extensions', and 'max_seconds' parameters are not described at all, leaving a significant semantic gap given the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Brute-force paths with ffuf', which is a specific verb (brute-force) and resource (paths). It clearly indicates this tool performs content/path discovery, distinguishing it from sibling tools like param_discovery or endpoint_discovery.
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 does not provide explicit guidance on when to use this tool versus alternatives. It mentions 'AGGRESSIVE' and 'at the engagement's rate limit', but does not describe typical scenarios or contrast with sibling tools such as endpoint_discovery or fuzz_compare. Users are left to infer appropriate usage from the tool name and verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run Slither over a Solidity project and normalize the detector output.
repo is a path inside the engagement workspace. Analysis is local: no
network request is made and no contract is executed, which is why this is
passive and costs no budget.
Every result is a CANDIDATE. Slither's high-impact detectors fire on safe code often enough that a finding without a runnable PoC is not submittable on any platform that pays for smart-contract bugs.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| exclude_informational | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description explicitly states 'no network request is made' and 'Analysis is local', while annotations include openWorldHint: true, which typically indicates possible external/world interaction. This contradiction undermines transparency, so score is 1 despite additional candidacy caveats.
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 clear and well-structured, with the core purpose in the first sentence and additional context in short paragraphs. The candidacy warning is somewhat verbose but relevant and useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description sufficiently covers input, behavior, and the safety/profile of the tool. It could be slightly more explicit about what 'normalize the detector output' means, but the output schema likely covers that.
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 no descriptions for the two parameters, but the description explains `repo` as a path inside the engagement workspace. `exclude_informational` is left entirely to inference from its name and default 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?
Clearly states it runs Slither over a Solidity project and normalizes detector output. This is specific and distinct from generic audit or scan siblings, identifying both tool and target.
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?
Provides useful context that the analysis is local, passive, and budget-free, and warns that findings are candidates requiring PoC. However, it does not explicitly tell when to choose this over sibling tools like semgrep_scan or contract_toolchain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report which smart-contract tools are present and correctly identified.
Absence is reported per tool rather than as an overall failure, so a missing fuzzer never reads as "the contract is fine".
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description adds a meaningful behavioral nuance: 'Absence is reported per tool rather than as an overall failure, so a missing fuzzer never reads as "the contract is fine"'. This clarifies the output interpretation and is valuable context. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The primary purpose is front-loaded, and the second sentence adds a critical behavioral detail about per-tool absence reporting. 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 read-only, zero-parameter tool with an output schema, the description fully covers what an agent needs to know: what it reports and how absence is handled. The output schema handles return format details, so no further information is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema has 100% coverage (empty object). Per the baseline rule for 0 parameters, a score of 4 is appropriate. The description correctly avoids parameter details since none exist.
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 'Report' and the resource 'which smart-contract tools are present and correctly identified.' It conveys the tool's purpose without ambiguity. However, it does not explicitly contrast with any sibling like 'contract_static_scan' or 'code_audit', though the distinct focus on toolchain presence makes differentiation implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention any conditions or exclusions, nor does it reference other tools like 'contract_static_scan' or 'code_audit' that might overlap. The context is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List registered capabilities with their phase, mode, and origin.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| phase | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description matches the readOnlyHint annotation by indicating a listing action with no side effects. However, it does not elaborate on any filtering behavior or output details, leaving some ambiguity about the exact behavior beyond the annotation.
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, extremely concise and well-structured. It communicates the core functionality without unnecessary words, achieving high efficiency.
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, the description is incomplete because it does not clarify the role of the parameters, does not mention any output schema (despite one being present), and lacks usage guidance. This leaves gaps for an agent trying to understand how to invoke and interpret results 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?
The input schema includes two optional parameters (mode and phase) but the description does not explain their purpose. It is unclear whether they are filters or output projections, and the description mentions 'phase' and 'mode' as output fields, which could confuse. No parameter description is provided, leading to poor semantics.
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 (List) and the resource (registered capabilities) along with the output fields (phase, mode, origin). It is distinct from sibling tools like cordon_status, but does not explicitly differentiate itself from other listing tools, so it's slightly below perfect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as cordon_load_scope or cordon_status. The description simply states what it does without any context on appropriate use cases or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close the engagement: flush findings and assets to disk and seal the audit log.
| Name | Required | Description | Default |
|---|---|---|---|
| outcome | No | completed |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses significant side effects: flushing findings/assets to disk and sealing the audit log. This goes beyond the annotation (readOnlyHint=false) by specifying exactly what mutation occurs and implies the action is irreversible ('seal'). It does not mention potential state requirements or idempotency, but the disclosed behaviors are substantial.
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, well-structured sentence that front-loads the primary action ('Close the engagement') and then details the consequences. There is no redundant information or filler, making it highly efficient.
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?
While the description covers the main action and its side effects, it omits explanation of the 'outcome' parameter and does not explicitly warn about irreversibility or required preconditions. Since an output schema exists, return details are not needed, but the missing parameter guidance and lack of explicit 'final step' context leave the definition incomplete.
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 only parameter, 'outcome', has a default but no enum and is not mentioned in the description. With schema description coverage at 0%, the agent receives no guidance on what values are acceptable or what effect this parameter has. This is a clear gap that the description fails to fill.
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's purpose: 'Close the engagement' and lists specific actions (flush findings/assets to disk, seal audit log). This distinguishes it from siblings like cordon_status (status query) and cordon_load_scope (scope loading) by specifying a unique finalization action.
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 this is the final step of an engagement but does not explicitly state when to use it versus alternatives, nor does it mention prerequisites or when not to use it. For example, it does not warn that it should be called only after all work is complete or that it is irreversible, leaving usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load and validate an engagement scope file, creating the workspace. Must succeed before any target-taking tool will run.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | No | ||
| scope_path | Yes | ||
| config_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only signal readOnlyHint=false and openWorldHint=false, so the description carries most of the behavioral burden. It does disclose that the tool creates a workspace and is a required gate, which is useful, but it does not explain failure behavior, idempotency, or whether existing workspaces are replaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the action, the side effect, and the ordering constraint are all front-loaded and clearly stated. Every sentence 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?
Despite having an output schema and a relatively simple operation, the definition is incomplete: it leaves all three parameters semantically unexplained and omits details about validation outcomes and failure modes. The ordering gate is helpful but not enough to make the tool safely callable by an 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 0%, and the description does not explain scope_path, workspace, or config_path beyond implying that a scope file is loaded. With three parameters and no compensating detail, the description adds almost no meaning beyond the schema's bare names and 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 clearly states a specific action (load and validate an engagement scope file) and a concrete outcome (creating the workspace), which distinguishes it from later target-taking tools. It does not explicitly name sibling tools such as scope_check or program_scope_fetch, so it loses the top score.
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 clear contextual guidance: this tool must succeed before any target-taking tool will run, establishing it as a prerequisite/setup step. It does not mention alternatives or explicitly say when not to use it, so it misses the highest score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current engagement: scope summary, assets, findings, budget, rate limits, approvals.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, covering the safety profile. The description adds value by listing the type of information returned (scope, assets, findings, etc.), which helps an agent set expectations. However, it does not disclose any additional behavioral traits such as potential rate limiting on the tool itself or data freshness, so it adds only modest context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that immediately identifies the subject ('Current engagement') and lists the key content. It is front-loaded and has no filler or redundant phrasing, making it highly efficient.
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 that the tool has an output schema and read-only annotations, the description sufficiently conveys the purpose and content. It lists the major categories an agent would expect, and the output schema handles return details. It does not mention any prerequisites or failure conditions, but for a status tool this is acceptable and complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the schema coverage is effectively 100% (vacuous). No further parameter information is required.
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 provides a status summary of the current engagement, enumerating specific content categories (scope, assets, findings, budget, rate limits, approvals). This distinguishes it from siblings like cordon_load_scope (which loads scope) and cordon_finish (which finalizes). The verb 'Current engagement' implies a retrieval operation, though it is slightly terse.
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 offers no explicit guidance on when to use this tool versus alternatives. It does not mention any conditions for use, exclusions, or relationships to related tools such as scope_check or approval_pending. The use case is implied (when you need engagement status) but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a URL's CORS policy for origin reflection and trust-boundary bugs.
Passive: a handful of GETs with different Origin headers, reading the
Access-Control-Allow-* response headers. Nothing is submitted, nothing
changes state.
A permissive policy is only a vulnerability when the endpoint returns data
worth stealing and Allow-Credentials is true — findings are filed as
candidates, never as confirmed.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by explicitly stating 'Nothing is submitted, nothing changes state,' reinforcing the read-only and non-destructive nature. It also discloses that findings are 'filed as candidates, never as confirmed,' which is a behavioral trait not captured in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-organized, with two short paragraphs covering purpose, method, and limitations. No unnecessary details are included, and the passive/active distinction is clearly stated.
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?
The description covers the tool's purpose, behavior, and even the condition for vulnerability (data worth stealing + Allow-Credentials). It lacks explicit output format details, but since an output schema is indicated, the description provides sufficient context for an agent to decide when to use it.
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 only parameter, 'target', is not described in the schema, but the description implies it is a URL by referring to 'a URL's CORS policy.' This indirect definition is sufficient for a generic string parameter, though a direct explanation would improve clarity.
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's purpose: 'Check a URL's CORS policy for origin reflection and trust-boundary bugs.' The verb 'check' and the specific object 'CORS policy' make the function unambiguous, and the mention of 'origin reflection' and 'trust-boundary bugs' further clarifies the scope.
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 when to use the tool by focusing on CORS checks, but it does not explicitly state conditions for use or contrast with alternative tools. It mentions the passive nature, which suggests it's for low-impact assessment, but lacks direct guidance on when to prefer this over other scanning tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report bug-class coverage: what Cordon finds, confirms, and bypasses.
The completeness check a client asks for before a test. Every row grades a
bug class as auto (a validator proves it), detect-only (found but not
confirmed), or manual (inherently judgement-shaped). A class is never
silently absent — gaps are named, with what would close them. Touches nothing
and costs no budget.
class_name — one class in full ("sql-injection", "xxe-injection")
status — everything of one grade ("auto", "detect-only", "manual")
gaps_only — just the non-auto classes, the watch-list
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| gaps_only | No | ||
| class_name | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Touches nothing and costs no budget,' aligning with the readOnlyHint and destructiveHint annotations. It also describes output behavior—every row grades a bug class and gaps are never silently absent—providing useful side-effect and result transparency beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a short purpose statement, a clear grading model, a side-effect note, and a bullet list for parameters. No redundant or misleading text is present.
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 parameter set, the description covers purpose, output semantics, side-effect profile, and parameter meanings. It does not detail the exact output schema, but the row-based grading description is sufficient for this tool's complexity.
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 0%, but the description bullet list explains all three parameters with concrete examples (e.g., 'sql-injection', 'auto', 'just the non-auto classes'). This fully compensates for the missing schema descriptions and clarifies filtering intent.
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 reports bug-class coverage for Cordon, specifying what it finds, confirms, and bypasses. It distinguishes itself from broader reporting tools by focusing on coverage grades (auto, detect-only, manual) and explicitly naming gaps.
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 gives a clear use case: 'the completeness check a client asks for before a test.' It also notes the tool touches nothing and costs no budget, implying safe pre-test usage, though it does not explicitly contrast with alternative reporting tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The live engagement dashboard blob: which phase is running, each phase's outcome, the findings ledger with severity/status, discovered assets, and the brain's recent sensed activity. One JSON snapshot of the whole run — use it to answer 'where is the scan, what has it found' without reading workspace files directly. The CLI mirrors this as cordon dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=false, and the description aligns by calling it a snapshot and stating it avoids direct file reads. No side effects are mentioned or implied, so the description is consistent with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loads the returned content, then adds usage context. It is reasonably concise, though the term 'dashboard blob' is slightly informal and the list of contained data could be tightened without losing clarity.
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?
The description enumerates the key fields in the snapshot, explains the use case, and notes the output is a JSON blob. Since no parameters exist and the output schema is referenced but not shown, the description adequately covers what an agent needs to decide whether to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so no parameter explanation is needed. The baseline score of 4 applies; there is no additional semantic detail to provide.
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 returns a live engagement dashboard snapshot including phase, outcomes, findings ledger, assets, and brain activity. It names the CLI mirror and specifies the intended use for answering scan status questions, though it does not explicitly contrast with similar sibling tools like cordon_status.
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 explicit guidance to use this tool for answering 'where is the scan, what has it found' and notes it avoids reading workspace files directly. It does not enumerate alternatives or state when not to use it, but the primary use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Generate subdomain permutations with alterx and resolve them with dnsx.
Finds hosts that no passive source knows about. Requires approval: this is a brute-force pattern, just against DNS rather than HTTP.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond annotations by clearly warning that the tool is aggressive, requires human approval, and performs brute-force DNS resolution; however, it does not detail potential side effects like high query volume or rate limiting.
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 concise and well-structured, starting with a clear warning and then stating the action and purpose without unnecessary 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?
While the purpose is clear, the description lacks essential invocation details such as accepted target formats, meaning of the limit parameter, and expected output, making it incomplete for an agent to use confidently.
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 description provides no explanation for the 'target' or 'limit' parameters, leaving the agent to guess that target is a domain and limit is a count; schema itself has no descriptions, so this is a significant gap.
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 generates subdomain permutations with alterx and resolves them with dnsx, and explicitly distinguishes its intent (finding hosts unseen by passive sources) from other DNS tools.
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?
Mentions that this is an aggressive brute-force pattern requiring approval and contrasts DNS with HTTP, but does not explicitly say when to prefer this over sibling tools like dns_resolve or subdomain_enum.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve hosts and return A/AAAA/CNAME/MX/NS/TXT records.
Flags hosts whose CNAME resolves but which have no address record — the shape of a dangling delegation. Those are candidates for takeover_verify, never findings on their own.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| record_types | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation and further clarifies that the tool does not produce final findings but only candidates, adding transparency beyond the annotation.
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 concise and well-structured, combining the core action with a relevant caveat about dangling delegation, with no superfluous 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?
The description adequately conveys the main behavior and output (records plus flags), and the existence of an output schema is noted. Minor gap: exact output format is not described, but the simple nature of the tool makes it sufficiently 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 description coverage is 0% and the description does not explain the parameters 'target' or 'record_types'. The names are somewhat self-explanatory, but the description fails to compensate for lack of schema-level descriptions, leaving ambiguity for an agent.
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 it resolves hosts and returns specific record types (A/AAAA/CNAME/MX/NS/TXT), and distinguishes its role from sibling tools like dns_permute by mentioning the dangling delegation 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?
Provides explicit guidance on when to use: for resolving DNS records and identifying potential dangling delegations, and explicitly says these are candidates for takeover_verify, not findings on their own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Collect known URLs for a domain from public archives.
Sources: gau (Wayback + Common Crawl + URLScan), waybackurls, waymore. These query archives, not the target, so they cost the program nothing.
include_crawl adds a shallow katana crawl, which does touch the target — keep it off unless the archives came back thin.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| include_crawl | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that archive queries cost nothing to the program and that enabling include_crawl actively touches the target. This goes beyond the readOnlyHint annotation by detailing the conditional side effect.
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 compact and well-structured, with the core purpose first and the important caveat about include_crawl clearly separated. No redundant wording.
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 purpose, sources, and side-effect tradeoffs sufficiently for an agent to decide when to invoke it. Since an output schema exists, omitting return details is acceptable; slightly more detail on expected target format could improve 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?
Describes include_crawl's behavior and explicitly states target is a domain, compensating for the schema's lack of parameter descriptions. The target parameter is clear from context, though format expectations could be slightly more explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States clearly it collects known URLs for a domain from public archives, with a specific verb and resource. Distinguishes itself from active scanning siblings by emphasizing archive sources.
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 explains that the default behavior queries archives and does not touch the target, while include_crawl adds a shallow katana crawl that does. This gives concrete guidance on when to enable the optional parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-attach to an existing engagement workspace by path.
Loads the workspace's scope, budget ledger, assets, findings, sessions and pipeline state so a new session continues exactly where the previous one left off — background jobs included, because they live in the server's event loop rather than in a dead shell process.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | Yes | ||
| scope_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only behavior, and the description reinforces this by stating it 'loads' state rather than mutating it. It also transparently explains that background jobs are included because they live in the server's event loop, adding useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and contains no redundant or irrelevant information. It efficiently communicates the tool's purpose and key behavior in two sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the tool's purpose and side effects well, and an output schema is present so return values need not be described. However, the ambiguity around the parameters leaves a notable gap in completeness for a tool with an otherwise clear purpose.
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 provides no descriptions for 'workspace' or 'scope_path', and the description does not clarify the distinct meaning or format of these parameters. The phrase 'by path' is ambiguous as to which parameter is the path, so the description insufficiently compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Re-attach') and resource ('existing engagement workspace'), and distinguishes this from creating a new engagement. It also explains what loading the workspace entails.
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 when to use the tool: when resuming an existing engagement workspace. It does not explicitly name alternative tools like engagement_new or session_register, but the 're-attach to an existing' phrasing provides sufficient contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create (or re-open) an engagement and make it the active one.
This is cordon_load_scope plus the resumability an agent needs: passing
an existing workspace directory re-opens it — budget, assets, findings,
sessions, task graph and the phase runner state are all inherited — so a
session that dropped mid-run resumes instead of starting over.
Returns the workspace path; every later tool call acts on this engagement
until another engagement_new/engagement_attach switches it.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | No | ||
| scope_path | Yes | ||
| config_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description directly contradicts the annotations. It states 'Create' and 'make it the active one,' which are state-changing actions, while annotations declare readOnlyHint: true. This is a serious inconsistency that misleads the agent about 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 front-loaded with the primary purpose and uses clear paragraphs. It is somewhat long but each sentence contributes useful context about resumability and active-engagement behavior, so it is appropriately structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters, no schema descriptions, and an output schema present, the description does not fully cover what an agent needs to call this tool correctly. It omits parameter explanations, return format details beyond the workspace path, and does not address the contradiction with annotations. Significant gaps remain.
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 0%, so the description must compensate by explaining parameters. It mentions 'passing an existing workspace directory' but does not clarify the roles of scope_path, workspace, or config_path, nor how they relate. It fails to add meaningful semantic value 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 verb and resource: 'Create (or re-open) an engagement and make it the active one.' It also distinguishes from sibling cordon_load_scope by describing itself as 'cordon_load_scope plus resumability,' giving an agent immediate differentiation.
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 explains when to use this tool by mentioning that passing an existing workspace directory re-opens it for resumption, and it notes that the engagement stays active until switched by another tool. It references cordon_load_scope and engagement_attach as related but does not explicitly state when to choose alternatives, so it is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Run the exploit validators across discovered injection points.
target is the comma/newline-joined list of URLs the earlier phases found
(the pipeline passes the asset store's URLs). Each URL's query parameters are
extracted and tested one at a time, capped at limit injection points.
include_heavy adds sqlmap and dalfox on top of the native probes. Every
result is a CANDIDATE; the validators store their own findings.
Returns tested (injection points actually probed) for the pipeline's
"did it do anything" gate, plus a per-point summary.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| target | Yes | ||
| include_heavy | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it runs exploit validators, generates candidate results rather than confirmed findings, and that validators store their own results. It also notes the need for human approval, which aligns with the destructiveHint annotation and gives a reasonable understanding of 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 concise and well-structured, using backticks for parameters and clearly separating the return value. It is slightly verbose in repeating the pipeline context, but overall it is efficient and easy to parse.
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?
The description provides enough context for an agent to use the tool, including the parameters, the purpose, and the return summary. It does not include an explicit output schema, but the mentioned return fields ('tested' and per-point summary) are sufficient for basic 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?
Every parameter is explained: target is the list of URLs, limit caps injection points, and include_heavy adds sqlmap and dalfox. This adds meaningful detail beyond the bare schema, which had zero parameter descriptions.
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 that the tool runs exploit validators across discovered injection points, and it explicitly notes that it requires human approval. This makes the primary 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?
The description mentions it operates on injection points found in earlier phases and that it is part of a pipeline, but it does not explicitly contrast this tool with alternative validation or scanning tools. The guidance on when to use it versus other tools is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The prompt pack for one vulnerability class.
bug_class is one of: sqli, nosqli, xss, ssti, ssrf, cmdi, lfi, redirect,
auth, authz, business_logic, cache_poisoning, race_condition, takeover,
deserialization, file_upload, graphql, injection.
The pack names the role, objective, scope (including what is not allowed), the success criteria a candidate must meet before it may be called a finding, and the evidence fields a reproducible PoC must fill. Use it before driving a live test or writing up a candidate: a finding that cannot fill the evidence fields is a lead, not a finding.
| Name | Required | Description | Default |
|---|---|---|---|
| bug_class | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, open-world, and non-destructive behavior, and the description's 'prompt pack' framing aligns with an informational tool. It does not explicitly say that no scans or tests are performed, but the annotations cover this and the description does not contradict them.
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 compact and well structured, combining allowed values, tool behavior, and usage context without unnecessary detail. Every sentence adds useful 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?
It covers the tool's role, objective, scope constraints, success criteria, and evidence fields, which provides solid context for the single-parameter input. The output schema is mentioned as present but not shown, so output completeness cannot be fully verified, but the description gives enough practical 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?
The only parameter, bug_class, is explained with a complete list of accepted values in the description. There is no per-value detail, but the list is sufficient to use the parameter correctly.
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 returns a prompt pack for one vulnerability class and enumerates all valid bug_class values. It is slightly abstract ('prompt pack'), but the role and scope are understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete timing guidance: use before live testing or writing up a candidate, and explains the finding-versus-lead distinction. However, it does not mention sibling tools or conditions for choosing an alternative, so usage guidance is partial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pull one window of a job's result instead of the whole set. path=dotted path into the result, where=regex filter, fields=keys to keep. Use this rather than job_fetch whenever a scan produced many rows.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| limit | No | ||
| where | No | ||
| fields | No | ||
| job_id | Yes | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation is true, and the description aligns with a read-only operation ('Pull' a window). The description adds context about parameter meanings but does not go beyond the annotation to discuss side effects, permissions, or failure modes. Since annotations already cover safety, the bar is lower; the description adds some value but not rich behavioral detail.
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 two sentences long, direct, and free of unnecessary wording. It front-loads the core purpose and then gives parameter hints, making efficient use of space.
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?
The tool has an output schema (indicated in context signals), so the description need not explain return values. The description covers the primary use case and selection criteria relative to a sibling tool. It is complete enough for a simple tool, though a bit more detail on offset and job_id could have elevated it further.
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 0%, so the description is the sole source for parameter meaning. It explains path, where, and fields, but omits job_id (required) and offset (pagination). While job_id may be inferable from context, it is not explicitly described, and offset is not mentioned at all. The explanation is partial, covering 3 of 6 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 purpose: 'Pull one window of a job's result instead of the whole set.' It uses a specific verb ('Pull'), identifies the resource ('job's result'), and distinguishes itself from job_fetch by explicitly saying 'instead of the whole set.' No ambiguity.
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?
Explicit guidance is given: 'Use this rather than job_fetch whenever a scan produced many rows.' It also briefly explains three parameters (path, where, fields) inline, giving enough context for common use. The condition for choosing this tool over the sibling is concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full record for one finding, including evidence and PoC.
| Name | Required | Description | Default |
|---|---|---|---|
| finding_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context by stating the response includes evidence and PoC. It is consistent with the readOnlyHint and destructiveHint annotations, and there is no contradiction. It does not discuss error behavior, but the annotations already cover the safety profile.
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 with no unnecessary detail or repetition. It efficiently conveys the tool's core purpose and output scope.
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 read-only lookup with a single required parameter, the description conveys the essential purpose and return content. It could mention finding_id format or error conditions, but the presence of an output schema partially reduces the need to describe return structure.
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 schema only defines finding_id as a required string with no description, and the description does not explain how to obtain or format finding_id. Since schema coverage is effectively 0%, the description needed to compensate, but it only refers to 'one finding' without explicitly mapping that to the finding_id 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 that the tool returns the full record for one finding, including evidence and PoC, which distinguishes it from list-oriented tools like findings_list. However, it lacks an explicit verb such as 'retrieves' or 'gets', so purpose is slightly less direct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Full record for one finding' implies this is appropriate when detailed evidence and PoC are needed for a single finding. It does not explicitly name alternatives, such as findings_list for summaries or finding_note for adding notes, so guidance is only implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach an analyst note to a finding. Notes appear in the report.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | ||
| finding_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a write operation ('attach') but annotations declare readOnlyHint: true. This is a direct contradiction. The only behavioral detail is that notes appear in the report, but the contradiction invalidates the annotation and the description does not clarify.
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 with no fluff. It is front-loaded with the action, but it is minimal to the point of lacking necessary detail.
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 contradictory annotation and missing parameter guidance, the description is incomplete. It does not explain the write nature, prerequisites, or return behavior, leaving the agent under-informed.
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 0%, and the description adds no meaning to the parameters. The parameter names (finding_id, note) are self-explanatory, but the description does not specify formats, constraints, or how the note is used beyond appearing in the report.
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: attach a note to a finding. It is specific and unambiguous, and no sibling tool performs this exact function, so it stands apart.
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 finding_detail or validate_findings. It does not mention prerequisites, conditions, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List findings, optionally filtered by status and severity.
Returns a compact table by default. Set detail=True for full records — prefer the compact form while planning; it costs a fraction of the tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| detail | No | ||
| status | No | ||
| min_severity | No | info |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint: true and destructiveHint: false, covering the safety profile. The description adds that it returns a compact table by default and full records with detail=True, plus a note about token cost. This enriches behavioral understanding beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, then the output detail and a usage tip. It is concise, well-structured, and every word adds value.
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 that an output schema exists (as per context signals), the description needn't explain return values in depth, but it does describe the two output modes. It provides useful context about token usage and planning. Missing some parameter specifics, but overall adequate.
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 0%, so the description must compensate. It mentions 'status and severity' (referring to status and min_severity) and 'detail' for full records, but does not explicitly explain the 'limit' parameter. Partial compensation but not complete.
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 purpose: 'List findings' with optional filters for status and severity. It distinguishes itself from more specialized siblings like triage_findings or finding_detail, though not explicitly. The core function is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage tip about the detail parameter ('prefer the compact form while planning') but does not explicitly state when to use this tool versus other sibling tools that also list findings. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify the WAF vendor from response headers, body, and status code.
headers is a dict of response headers ({"server": "...", "cf-ray": ...}).
Pass the block page as body when you have one — the markers there are
often the only signal. Returns matches sorted by confidence; an empty list
means no signature reached threshold (no WAF, an unknown one, or a
transparent one that never modifies responses).
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | ||
| headers | Yes | ||
| status_code | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds valuable behavioral details: returns matches sorted by confidence, and an empty list means no signature reached threshold, explaining possible causes. This goes beyond annotations and helps the agent interpret results.
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 compact and well-structured: purpose first, then parameter clarifications, then return behavior. Every sentence adds value, and the most important information is front-loaded. No fluff 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?
For a relatively simple tool with an output schema, the description covers inputs, return behavior, and edge cases (empty list). It explains the significance of body and the meaning of an empty result. It could mention that it is read-only (but annotations cover that) and could clarify the status_code parameter, but overall it is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It clarifies 'headers' as a dict with an example and notes that 'body' should contain the block page. However, 'status_code' is only mentioned in the purpose line without any detail about its role or default behavior. Partial compensation.
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 identifies the WAF vendor from response headers, body, and status code. The verb and resource are specific, and the inputs are enumerated. However, it does not explicitly differentiate from sibling tools like waf_detect or waf_vendors, which may also deal with WAF detection or vendor lists.
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 guidance on when to pass the block page as body ('the markers there are often the only signal'), which is helpful. But it does not discuss when to prefer this tool over other WAF-related siblings or mention any exclusions. Usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Test a URL that returned 403 against twelve access-bypass techniques.
url must be a URL that actually returned 403 (run forbidden_candidates
or check the probe result first — unKover refuses anything else).
prefix optionally adds an API version prefix (/v2) that the server
may not protect. Returns the first working technique with a curl PoC, or a
clean report when nothing bypasses.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| prefix | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description labels the tool as AGGRESSIVE and requiring human approval, which signals active testing behavior. It does not enumerate all possible side effects, but it provides meaningful context beyond the annotations, which are enough to indicate it may send crafted requests.
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 compact and well-structured in two sentences. It front-loads the purpose and critical constraints, includes the return behavior, and contains no unnecessary detail.
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?
The description provides enough context for an agent to decide when and how to invoke the tool, including prerequisites, parameter usage, and expected output. The reference to forbidden_candidates helps integrate it with the surrounding workflow.
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 schema provides no parameter descriptions, but the tool description compensates by explaining that url must be a previously 403-returning URL and that prefix optionally adds an API version prefix such as /v2. This gives the agent the necessary context for both 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's purpose: test a URL that returned 403 against twelve access-bypass techniques. It also describes the output, the first working technique with a curl PoC or a clean report, 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?
The description explicitly says the URL must have returned 403 and tells the user to run forbidden_candidates or check the probe result first. It also explains the optional prefix parameter with an example and notes that the tool refuses invalid input.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pre-check a list of URLs and return the ones that actually return 403.
forbidden_bypass refuses anything that is not 403, so this is the
pre-filter: one cheap HEAD per URL, returns the 403s. Give it URLs from
http_probe or content discovery that looked interesting; it tells you
which are worth the bypass pass. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| urls | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Read-only.' and mentions 'one cheap HEAD per URL' which goes beyond the annotations (readOnlyHint: true, destructiveHint: false). It describes the network behavior (HEAD requests) and the filtering outcome (returns 403s), providing transparency about side effects. Minor gap: does not discuss error handling or rate limits, but sufficient for the tool's simplicity.
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 concise (two sentences) and front-loads the core purpose. It efficiently includes relevant sibling-tool references and the HEAD request detail without unnecessary wording. The structure is clear and focused.
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?
The description provides the essential context for a simple tool: what it does, how it fits with other tools, and the general output ('returns the 403s'). However, it lacks explicit details about the output structure (e.g., just a list of URLs, or with status codes) and does not mention edge cases or performance implications. Given the tool's simplicity and single parameter, this is adequate but not exhaustive.
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 zero description coverage for the 'urls' parameter. The description only says 'Give it URLs from http_probe or content discovery' which gives source context but does not specify URL format (e.g., absolute vs relative, scheme requirements), constraints, or examples. With 0% schema coverage, the description must compensate more thoroughly, but it does not.
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's purpose: 'Pre-check a list of URLs and return the ones that actually return 403.' It explicitly differentiates from sibling tools by mentioning that 'forbidden_bypass refuses anything that is not 403' and positioning this tool as the pre-filter, making its role distinct in the workflow.
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 explicit usage guidance: 'Give it URLs from http_probe or content discovery that looked interesting; it tells you which are worth the bypass pass.' It also clarifies the tool's relationship to forbidden_bypass and notes it uses 'one cheap HEAD per URL', indicating when and how to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Auto-chain 403 bypass across a list of URLs.
Pre-checks up to max_candidates URLs with one HEAD each, keeps the real
403s, then runs forbidden_bypass (unKover's 12 techniques) on up to
max_bypass of them. Every bypass files its own finding; a clean pass is
recorded as coverage evidence that the access decision held.
Give it the estate's live URLs (the pipeline passes the asset store, which arrives as a comma/newline-joined string). The chain is what makes a 403 a tested access decision instead of a dead end an operator has to revisit by hand.
| Name | Required | Description | Default |
|---|---|---|---|
| urls | Yes | ||
| max_bypass | No | ||
| max_candidates | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviours: it performs network requests (HEAD and bypass techniques), files findings per bypass, and records coverage evidence. It also flags the action as aggressive and requiring approval. However, it does not mention specific rate limits, permissions, or potential side effects on target systems, so transparency is good but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with a bracketed warning, then process, then input guidance, and ending with a rationale. It avoids unnecessary fluff, though the final rhetorical sentence could be trimmed without losing meaning. Overall, it is appropriately sized for the tool's complexity.
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?
The description provides enough to invoke the tool: input format, limits, and expected behavior. It does not describe the output schema or possible error conditions, but given that the tool likely returns findings and coverage data, the missing output details are a minor gap. The overall context is sufficient for a competent 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?
All three parameters are explained: 'urls' is described as 'the estate's live URLs' in a comma/newline-joined string or array, 'max_candidates' is the limit for pre-checked URLs, and 'max_bypass' limits how many URLs get the bypass treatment. The description gives functional meaning to each, exceeding the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's function: 'Auto-chain 403 bypass across a list of URLs.' It also details the process (pre-check with HEAD, keep real 403s, run bypass techniques) and the outcome (files findings or records coverage). This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes context like 'requires human approval' and 'AGGRESSIVE', which hints at when to use it cautiously, but it does not explicitly compare to sibling tools such as forbidden_bypass or forbidden_candidates. It also lacks guidance on when not to use it or alternative approaches, leaving the decision partly to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diff responses against a baseline to find what a payload actually changed.
baseline_url is the unmodified request; case_urls are the injected
variants. Each case is diffed against the baseline across status, mime,
body hash, length, duration and headers, and cases are clustered by body
hash so identical responses (the catch-all page) read as one cluster.
re_request adds a second fetch of every case — the cache-poisoning
probe. If the second response differs from the first and matches the
injected body while a fresh requester asked only for the baseline URL, the
cache served the poisoned copy; that is the only honest way to move web
cache poisoning from "manual" toward detectable.
Read-only: GET requests through the engagement's rate limiter, nothing is sent beyond the URLs you name.
| Name | Required | Description | Default |
|---|---|---|---|
| case_urls | Yes | ||
| re_request | No | ||
| baseline_url | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by explaining the read-only nature, the GET requests through the rate limiter, the clustering by body hash, and the cache-poisoning probe behavior. It discloses exactly what happens (diffing dimensions, re-fetch) and the safety constraints, aligning with readOnlyHint and destructiveHint. No contradictions.
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 well-structured: it opens with the core purpose, then explains parameters, then details the optional re_request and safety. Each sentence carries information, no filler. It is appropriately sized for a tool with this complexity.
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 (fuzzing, diffing, cache poisoning) and the presence of an output schema, the description covers all essential operational details: what is diffed, how clustering works, the cache-poisoning probe, and safety. Nothing an agent needs to invoke it correctly is missing.
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 0%, so the description must compensate. It does: it explains baseline_url as the unmodified request, case_urls as the injected variants, and re_request as a second fetch for cache poisoning. Every parameter is meaningfully described, adding value beyond the bare 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 states a specific verb (diff) and resource (responses against a baseline), clearly distinguishing it from sibling tools like authz_compare or web_injection_probe. It also names the exact inputs (baseline_url, case_urls) and the outcome (find what a payload changed).
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 explains the purpose and how to use the tool (provide baseline and case URLs), and clarifies the re_request option. It does not explicitly mention alternatives or when not to use it, but the context is clear enough that an agent can infer its niche. A bit more explicit routing would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit a GraphQL endpoint: introspection, suggestions, GraphiQL, CSRF, trace mode.
Passive. Every check that remains is a single well-formed query used to read
what the server discloses. graphql-cop's denial-of-service family (alias
overloading, batching, directive overloading, circular introspection) is
excluded unconditionally — those exist to make the server burn CPU, which is
out of bounds under scope.rules.no_dos.
If the URL has no path, graphql-cop tries /, /graphql, /graphiql,
/playground and /console; give it the exact path to keep the request
count down.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool is passive and every check is a single well-formed read query, aligning with the readOnlyHint and destructiveHint annotations. It further discloses that DoS-related checks are unconditionally excluded, providing transparent behavior beyond the annotation metadata.
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 organized into three focused paragraphs: purpose, safety/scope, and URL/path guidance. It is slightly verbose with the repeated graphql-cop references, but each sentence adds meaningful information and no filler is present.
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?
The description provides enough context about what the audit covers, its passive nature, and its path-finding behavior. Since an output schema exists, not detailing return values is acceptable. It lacks only a brief note on how results are delivered, but this does not impair 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?
The schema only says target is a required string, but the description gives useful semantic context: target is a URL and path behavior is explained, including what happens when no path is provided. It does not explicitly label target as 'the GraphQL endpoint URL', but the connection is strongly implied.
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 audits a GraphQL endpoint and enumerates concrete checks: introspection, suggestions, GraphiQL, CSRF, and trace mode. This distinctively separates it from sibling tools like code_audit or cloud_audit, and the verb-resource relationship is explicit.
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 gives explicit usage guidance: it is passive, uses only read-style queries, and excludes the denial-of-service family under scope.rules.no_dos. It also advises providing an exact path when the URL has none, which directly helps the agent use the tool efficiently and safely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What this engagement already knows about a host, URL, or asset, and how it connects to everything else. Ask this before re-running recon — the answer is free and a re-scan costs the target requests.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | ||
| limit | No | ||
| subject | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation is supported by the description's 'already knows' and 'free' language, implying no target interaction or state change. It does not fully elaborate on output behavior, but the annotation covers the primary safety concern.
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 and front-loaded, immediately conveying the tool's purpose and the recommended usage context. Every sentence adds value, with no filler 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?
The description provides enough context for an agent to understand the tool's role and when to invoke it, especially with the output schema present. However, the lack of parameter explanations slightly reduces the overall 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?
The input schema has zero descriptions for the three parameters. The description indirectly defines 'subject' as a host, URL, or asset, but 'depth' and 'limit' are unexplained, leaving their meaning and effect ambiguous.
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 the tool as a recall/query operation for existing engagement knowledge about a host, URL, or asset, including its connections. It is concise and distinguishes this from active recon by explicitly advising to ask before re-running a scan.
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 gives explicit guidance: use it before re-running recon because the answer is free, whereas a re-scan costs target requests. It does not name specific sibling alternatives, but the when/why is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Run the validators the research playbook names for a class, on an asset.
vuln_class (fuzzy names work) and asset (a URL in scope) are the
same inputs research_guidance takes; this tool goes one step further and
executes the validators the coverage matrix wires to the class, capped at
limit tools. Classes whose validation row is manual/none return
the evidence checklist instead of dispatching anything — the honest answer
is "no scanner owns this", and the checklist is what a report needs.
Every dispatched validator goes through the control plane again (scope, rate, budget, approval) — guidance never becomes an unapproved action. Returns the playbook plus a per-validator outcome summary; validators that prove something file their own findings.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | Yes | ||
| limit | No | ||
| stack | No | ||
| evidence | No | ||
| vuln_class | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important side effects: validators can be dispatched, are capped by limit, go through the control plane for scope/rate/budget/approval, and may file their own findings if they prove something. It also states that manual/none classes do not dispatch and instead return a checklist.
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 somewhat verbose and repeats the idea of returning a checklist versus dispatching, but it is organized and each sentence carries meaningful behavior. It is longer than necessary but not distractingly so.
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?
The description covers the main behavior, return type, and side effects, and mentions the control plane approval requirement. It does not describe the exact output schema, but the narrative summary plus the provided output-schema signal is likely sufficient for an agent to understand the 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?
The description explains vuln_class, asset, and limit, but stack and evidence are not described at all. Since the schema has zero description coverage, the description needed to clarify all parameters and only partially does so.
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 validators for a given vulnerability class against an asset, and differentiates it from research_guidance by going one step further to execution. It names the primary inputs and the action taken.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use this tool: when you want to execute the validators associated with a vulnerability class on an asset. It also notes that manual/none validation classes return an evidence checklist instead of dispatching, giving useful selection guidance, though it does not explicitly list 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.
Probe hosts for live HTTP services: status, title, tech, server, IP.
One request per host per scheme, at the engagement's rate limit. Rule-packs
are evaluated against each response, so native detections surface here.
Content-length and content-type are reported per host — the two scalars
that separate a real application from a parked page or an error shell —
and screenshots=True captures render-time evidence of the most
interesting hosts (requires a headless browser where httpx runs).
| Name | Required | Description | Default |
|---|---|---|---|
| ports | No | ||
| target | Yes | ||
| screenshots | No | ||
| max_screenshots | No | ||
| follow_redirects | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnly/openWorld/destructive annotations by detailing request volume, rate-limit adherence, rule-pack evaluation, and the need for a headless browser for screenshots. No contradictions with the annotations are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose and tightly packed behavior details. The 'two scalars' flourish adds slight stylistic bulk, but it does not obscure the meaning.
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?
Provides enough operational context to understand what the probe does, what is evaluated, and what output fields are reported. Since an output schema exists, not spelling out return values is acceptable.
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?
With 0% schema description coverage, the description needed to explain the parameters but only addresses screenshots=True. target, ports, max_screenshots, and follow_redirects are left to be inferred from types/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?
Clearly states the tool probes hosts for live HTTP services and enumerates the information returned (status, tech, IP, content-length/type). The verb and resource are specific enough to distinguish it from general port/service scanners.
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?
Describes operational behavior (one request per host per scheme, rate limiting, rule-pack evaluation) and hints at use for distinguishing real applications from parked pages. It does not explicitly contrast with sibling scanning tools such as service_scan or port_scan, so usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Propose concrete tests based on what recon actually observed.
Sends no traffic. Reads the engagement's asset store and returns testable propositions, each citing the observation behind it.
focus optionally narrows the request ("authentication", "idor",
"business logic"). Leave it unset for a general pass.
Returns proposals — things to try — and gaps, which is the more
valuable half: what the model would need in order to say anything sharper.
On a target where everything interesting sits behind a login, gaps will
say so, and that is the honest answer rather than five generic suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| focus | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. The description adds valuable transparency by stating 'Sends no traffic' and explicitly describing that it reads the asset store and returns proposals/gaps, including edge-case behavior ('On a target where everything interesting sits behind a login, gaps will say so'). This goes beyond the annotation hints.
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 well-organized, free of redundancy, and each sentence adds meaningful detail. It logically flows from purpose to behavior to parameters to output, making it easy to parse. No filler words or unnecessary technical jargon.
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 moderate complexity (parameters, output with proposals and gaps), the description provides sufficient context: it explains the output structure and the significance of 'gaps,' and the presence of an output schema reduces the need to detail return fields. It lacks explicit prerequisites or error conditions but these are not critical for basic invocation. Overall, it is nearly 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?
The schema provides no descriptions (coverage 0%), so the description must explain parameters. It adequately describes 'focus' with examples ('authentication', 'idor', 'business logic') and its default behavior. However, 'limit' is completely omitted, leaving its purpose ambiguous. The description only covers half of the parameters, failing to fully compensate for the schema gap.
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's purpose: 'Propose concrete tests based on what recon actually observed.' It specifies the resource read ('engagement's asset store') and the output type (testable propositions, proposals/gaps). This distinguishes it from execution or triage tools among siblings.
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 after recon by referencing observed data and mentions the optional 'focus' parameter to narrow scope. However, it does not explicitly contrast with alternative planning tools (e.g., taskgraph_next, research_guidance) or state concrete conditions for when to prefer this tool over others. The guidance is implicit but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Run Jaeles YAML signatures (plugin class C) against in-scope targets.
selector picks signatures by name or glob, e.g. 'cordon/' or 'cve/'. Signatures are loaded from rules/jaeles/ only.
Returns inline if it finishes within wait_seconds, otherwise a job_id.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| selector | No | cordon/* | |
| wait_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses that the tool is aggressive and requires human approval, which is not captured in annotations. It also explains the return behavior (inline vs job_id) and the source restriction ('rules/jaeles/ only'). This adds meaningful behavioral context beyond what the schema or annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with four sentences covering the core action, the approval warning, selector semantics, source path, and return behavior. The most critical information (aggressive, requires approval) is front-loaded. It is well-structured and avoids redundancy, though it could be slightly more organized by grouping related details.
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 (3 parameters, output schema, asynchronous behavior), the description covers key operational details: signature loading path, selector syntax, and inline vs. job_id return. It does not describe the output format, but an output schema exists, so that is acceptable. It also does not mention any potential side effects beyond being aggressive, which is covered by the approval requirement. Overall, it is sufficient for an agent to call 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?
With schema description coverage at 0%, the description compensates by explaining the selector parameter with examples ('cordon/*' or 'cve/*') and clarifying wait_seconds by describing the return condition. The target parameter is not explicitly described, but its meaning is obvious from the purpose statement ('against in-scope targets'). Overall, it adds value for two of three 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's purpose: 'Run Jaeles YAML signatures (plugin class C) against in-scope targets.' It specifies the action (run), the resource (Jaeles YAML signatures), and the context (in-scope targets). This distinguishes it from sibling scanners like nuclei_scan or nikto_scan by naming a specific tool and signature class.
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 explains what the tool does and mentions the selector and return behavior, but it does not provide explicit guidance on when to use this tool versus alternatives. There is no mention of conditions that favor jaeles_scan over other scanners, nor any 'when not to use' guidance. The aggressive/approval warning is a caution, not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a running scan. Kills the whole process tree.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a significant behavioral detail: it 'kills the whole process tree', which goes beyond a generic cancel and warns about cascading termination. This is valuable for understanding side effects. However, it does not mention irreversibility or return behavior, but the core destructive nature is clear.
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, consisting of two short sentences that get straight to the point. It front-loads the primary action and adds the critical side effect without fluff. This is an ideal example of minimal yet effective phrasing.
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 cancellation tool with one parameter, the description covers the core action and a key side effect. However, it omits any mention of preconditions, postconditions, or return values. Given the output schema exists, not detailing the response is acceptable, but the lack of any context about job state or usage edges makes it only moderately 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?
The description does not explain the 'job_id' parameter at all. It is only implied by the tool name and context, but the description adds no meaning about what the ID refers to or how it is used. Given the 0% schema coverage, the description should compensate, but it fails to do so.
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's function: stopping a running scan. The verbs 'Stop' and 'Kills' are unambiguous, and the target 'running scan' correctly identifies the resource. Although it doesn't explicitly differentiate from sibling tools, the name 'job_cancel' and action make the purpose obvious.
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 like job_list, job_fetch, or job_status. It does not mention prerequisites (e.g., job must be running) or when cancellation is appropriate. This leaves the decision to the caller without contextual help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a finished job's result. Prefer fetch_slice for large result sets — this returns everything and is capped.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| wait_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation covers the read-only nature, and the description mentions the capped all-encompassing return behavior. However, it does not explain what happens for unfinished jobs, how wait_seconds affects behavior, or what the cap is.
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 brief and direct, with no unnecessary words. The key guidance is front-loaded and easy to parse.
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?
The description covers the core purpose and a key alternative, but it omits important operational details such as wait_seconds behavior, the exact return cap, and error cases for non-finished jobs. This leaves meaningful gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for job_id or wait_seconds, and the description does not explain either parameter. The agent is left to infer job_id from context and has no information about wait_seconds semantics.
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 fetches a finished job's result with a specific verb and resource. It also distinguishes itself from fetch_slice, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises preferring fetch_slice for large result sets and notes that this tool returns everything and is capped, providing clear guidance on when to use this tool versus the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List background scans and their states.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates this is read-only, and the description aligns with that (listing does not modify state). However, no additional behavioral context is provided, such as how results are ordered, paginated, or what happens when status is omitted.
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 communicates the core purpose without unnecessary 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?
The description provides enough for a high-level understanding but lacks details about the optional status filter, the exact structure of the returned list (beyond 'states'), and any response size or pagination behavior. Given the low complexity and presence of a read-only annotation, it is minimally complete but not thorough.
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 only parameter, 'status', has no description in the schema or the tool description. Its meaning, possible values, and filtering behavior are entirely unexplained, leaving an agent to guess how it affects the result.
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 (list) and the resource (background scans) and mentions the output includes states. It is distinct from other siblings like job_fetch or job_status, though it does not explicitly name alternatives or specify whether it lists all or requires filtering.
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 use this tool over sibling list/fetch tools, nor does it mention any prerequisites or common scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check, wait on, or list long-running scans.
Tools that can outlast a single MCP call — nuclei_scan, bbot_scan,
osmedeus_flow — hand back {"completed": false, "job_id": ...} once their
internal wait (capped at 300s) elapses. This is how the result is collected
afterwards. Without it a scan longer than five minutes finishes into a job
nothing can read.
Omit job_id to list jobs. wait_seconds blocks for up to 300s, so a
nearly-finished scan can be collected in one call instead of polled.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | ||
| status | No | ||
| wait_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns by describing check/wait/list behavior with no side effects. It additionally discloses the blocking behavior of wait_seconds and the internal wait cap, providing transparency beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is mostly concise and front-loaded with the core purpose. The final sentence about a five-minute scan finishing into an unreadable job is somewhat redundant with the earlier explanation, but it reinforces the importance without excessive verbosity.
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?
The description gives a complete picture of when and how to use the tool, including the long-running job mechanism and wait behavior. The missing explanation of the status parameter is a notable gap, but overall the tool usage is sufficiently contextualized.
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 schema provides no parameter descriptions, and the description explains job_id (omit to list jobs) and wait_seconds (blocks up to 300s). However, the status parameter is never mentioned, leaving its meaning and filtering behavior ambiguous. Partial coverage of three optional 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's purpose: 'Check, wait on, or list long-running scans.' It explicitly identifies the relevant scan tools (nuclei_scan, bbot_scan, osmedeus_flow) and explains that this is the mechanism for collecting results from jobs that outlast a single call, distinguishing it effectively from sibling job-related tools.
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 concrete usage guidance: omitting job_id lists jobs, and wait_seconds blocks up to 300s. It also explains the critical scenario where this tool is needed ('Without it a scan longer than five minutes finishes into a job nothing can read'). It does not explicitly mention when to prefer job_list/job_fetch, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch JavaScript bundles and extract endpoints, secrets, and libraries.
Fetches each URL once (a normal browser request), then runs native pattern
matching, jsluice (grammar-based URL extraction), linkfinder (regex-based
endpoint recovery over the saved files) and retire.js (known-vulnerable
library detection). Either external tool being absent is reported per-tool in
tools; it never turns into a quiet zero. Credential candidates are masked
in the output and are never tested against a live service here.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| max_files | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that each URL is fetched once, credential candidates are masked, and never tested against a live service. It also discloses that missing external tools are reported per-tool rather than silently ignored. This aligns with the readOnlyHint and non-destructive annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise, with a clear one-sentence summary followed by supporting details. It avoids unnecessary fluff but includes important behavioral notes.
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?
The description mentions output characteristics (masked credentials, per-tool reporting) but does not describe the overall output structure. Given that an output schema exists (though not shown), the description could be more specific about what the agent will receive.
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 provides no descriptions for target or max_files, and the description does not explain their meaning. While target likely refers to a URL or list of URLs, and max_files to a limit, this is not explicitly stated, leaving ambiguity.
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 (fetch and extract) and the specific targets (JavaScript bundles) and outputs (endpoints, secrets, libraries). It also lists the specific tools used, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternative tools like content_discovery or secret_scan. It only describes its internal operations, leaving the agent to infer applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decode a JWT and report its algorithm, claims, and timestamps.
Fully offline: not one request leaves this machine, which is why it is
passive and costs zero requests. target is the in-scope asset the token
came from — it exists so the call is still scope-checked and the finding has
an owner, not because jwt_tool contacts it.
Every jwt_tool mode that forges a token (-T/-I/-S/-X), cracks
a key (-C), or replays one at a live host (-t/-M) is denied by the
argument policy. Proving a JWT flaw is an exploit-phase action with its own
approval gate, not something this tool can be talked into.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | ||
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description explains the tool is fully offline, makes zero network requests, and that the target parameter exists only for scoping and ownership, not for contact. It also discloses that the argument policy denies certain modes, providing additional behavioral detail that an agent would not infer from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and then provides safety and scoping details. It is slightly verbose due to the repetition of 'not because jwt_tool contacts it' and the extensive denial list, but the structure is logical and the content is relevant, so it does not feel bloated.
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 schema (two strings, no nested objects) and the presence of an output schema, the description covers the necessary context: what the tool does, its safety bounds, the role of each parameter, and its place in the workflow. An agent has enough information to decide when and how to invoke 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?
The schema has no descriptions, but the description explicitly explains the purpose of 'target' (the in-scope asset the token came from, used for scope checking and finding ownership) and clarifies that it is not contacted. The 'token' parameter is self-evident from the tool's purpose of decoding a JWT, so both parameters are well covered.
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 opens with a clear verb and resource: 'Decode a JWT and report its algorithm, claims, and timestamps.' It also distinguishes this tool from exploit-oriented actions by explicitly stating it does not forge, crack, or replay tokens, which differentiates it from sibling tools in the same domain.
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 implicit when-to-use guidance by focusing on decoding and inspection, and explicitly covers when-not-to-use by listing denied modes (forging, cracking, replaying) and stating that proving a JWT flaw is an exploit-phase action. It does not name specific alternative tools, but the boundaries are clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Assess Kubernetes posture with Kubescape.
Kubescape ships its own MCP server. If you are doing significant Kubernetes work, connect that directly alongside Cordon rather than routing everything through this wrapper — but vet it first, like any third-party MCP server.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | ||
| framework | No | nsa |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses that the tool is aggressive, requires human approval, and is a wrapper around Kubescape. It does not detail side effects or rate limits, but the annotations are sparse and the description adds meaningful behavioral context without contradiction.
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 compact and front-loaded: it starts with the risk warning, states the purpose, then provides alternative usage guidance. No unnecessary words or redundant detail.
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?
The description gives enough high-level context to know when to use the tool, but omits critical parameter meaning. Given the sparse schema, users would likely be uncertain about what 'context' and 'framework' should contain, making the description incomplete for actual 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?
Neither the description nor the schema explains the 'context' or 'framework' parameters. Schema coverage is 0%, and the description provides no hints about what values are expected or how they influence the assessment.
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 assesses Kubernetes posture using Kubescape, giving a specific verb and resource. It distinguishes itself from siblings by referencing Kubescape and the wrapper 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?
Explicitly says when to use the tool and directs users to connect Kubescape's own MCP server directly for significant Kubernetes work. Also advises vetting the third-party server, giving clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the LLM probe families, what each tests, and how findings are graded.
Read this before running llm_redteam. Choosing probes by impact rather than running everything is the difference between a report a program acts on and a list of jailbreak transcripts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds value by explaining that it catalogs probe families, what each tests, and grading methodology, which goes beyond the structured annotations. It also implies a non-execution role, complementing the read-only nature. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The first sentence front-loads the purpose, and the second provides critical usage guidance. Every word earns its place, and the structure is efficient.
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 no-parameter catalog tool with an output schema, the description fully covers what the tool does and when to use it. It explains the content (probe families, tests, grading) and even gives strategic advice. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is trivially 100%. The description does not need to elaborate on parameters, and the baseline for 0 params is 4. No additional parameter information is required or expected.
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's purpose: 'List the LLM probe families, what each tests, and how findings are graded.' It uses a specific verb ('List') and identifies the resource ('LLM probe families'), distinguishing it from execution tools like llm_redteam. No ambiguity or tautology.
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 explicitly instructs 'Read this before running llm_redteam,' providing a clear when-to-use directive. It also advises on selecting probes by impact, giving actionable context for how to use the information. This differentiates it from alternatives and leaves no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Probe the target's AI feature with garak, one probe family at a time.
family: indirect-injection (default), tool-abuse, context-leak, output-handling, or jailbreak. Run llm_probe_catalog first to choose.
Results are candidates. An LLM probe failing is a behaviour, not yet an impact — see the note in the result for what a report needs.
| Name | Required | Description | Default |
|---|---|---|---|
| family | No | indirect-injection | |
| target | Yes | ||
| model_type | No | rest | |
| generations | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is aggressive and requires human approval, and it explicitly warns that a probe failing is a behavior, not yet an impact. It does not enumerate every side effect, but the annotations already indicate it is not read-only and not destructive, so there is no contradiction.
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 compact and avoids unnecessary prose. The line breaks create a slightly fragmented feel, but the essential warnings and instructions are included without bloat.
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?
The description conveys the tool's purpose, approval requirement, and result interpretation, but it lacks parameter-level detail and does not explain the output schema despite being present. It is sufficient for a high-level understanding but not fully complete for confident 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?
The schema has 0% description coverage, and the description only partially explains the family parameter by listing valid values. The required target parameter and the model_type and generations parameters are not described, leaving the agent guessing at their meaning and format.
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: probe the target's AI feature with garak, one probe family at a time. It also distinguishes this from the sibling catalog tool by telling the agent to run llm_probe_catalog first to choose a family.
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 important usage guidance: requires human approval, should be preceded by llm_probe_catalog, and one family should be selected at a time. It also clarifies that results are candidates rather than confirmed impacts, which helps the agent interpret findings appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Run a promptfoo or deepteam suite from a config inside the workspace.
Use this when you have a target-specific test suite — application-aware probes almost always outperform generic ones, because they know what the feature is supposed to refuse.
| Name | Required | Description | Default |
|---|---|---|---|
| engine | No | promptfoo | |
| target | Yes | ||
| config_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits not present in annotations: '[AGGRESSIVE — requires human approval]' signals a high-impact action needing consent. This goes beyond the minimal readOnly/destructive flags and informs the agent of the approval requirement.
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 concise and front-loaded, starting with the critical approval warning followed by the core action and usage rationale. Every sentence adds value without redundancy, making it efficient for an agent to parse.
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?
The description gives enough context for an agent to understand when and why to use the tool, and the output schema exists so return values need not be detailed. However, the lack of parameter descriptions and precise engine/enum values leaves minor gaps in the overall call 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?
The schema provides zero descriptions for target, config_path, or engine. The description only implies that config_path refers to 'a config inside the workspace' and mentions engine values 'promptfoo or deepteam' implicitly, but target remains completely unexplained, leaving the agent to guess its meaning and format.
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's function: 'Run a promptfoo or deepteam suite from a config inside the workspace.' It also distinguishes itself from generic alternatives by emphasizing target-specific, application-aware probes, which sets it apart from sibling tools like llm_redteam.
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 explicitly provides when-to-use guidance: 'Use this when you have a target-specific test suite' and contrasts with generic probes. This gives clear selection criteria relative to other scanning tools, though it does not name specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve proof-of-concept techniques that worked on previous engagements for this vulnerability class. Check this before designing a PoC from scratch — the store holds methods only, never credentials or target data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| vuln_class | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already set readOnlyHint=true and openWorldHint=false. The description adds valuable behavioral context beyond the annotations: it explicitly states the store holds methods only, never credentials or target data, which informs expectations about what the tool will return and what it deliberately excludes. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and well-structured: it states the action, provides context, and adds a key constraint in just two sentences. Every word contributes to understanding the tool's purpose and scope, with no padding 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?
The description is complete for a simple retrieval tool with an output schema present. It covers the tool's purpose, when to use it, and a key limitation (no credentials or target data). The lack of parameter explanations is a minor gap, but since the output schema is defined, the description does not need to detail return values. Overall, it provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has three parameters (query, limit, vuln_class) with 0% description coverage. The description mentions 'vulnerability class' but does not explicitly map it to the vuln_class parameter, nor does it explain the purpose of query or limit. Since schema coverage is 0%, the description fails to compensate by explaining parameter meanings, leaving the agent to guess.
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's function: retrieving proof-of-concept techniques from previous engagements for a given vulnerability class. It also distinguishes it from related tools by emphasizing that the store holds methods only, never credentials or target data, and positions it as a preliminary step before designing a PoC from scratch.
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 a direct usage guideline: 'Check this before designing a PoC from scratch.' It also hints at scope by noting the store contains only methods, which implies using it when you need techniques without sensitive data. It does not explicitly name alternative sibling tools or contrast conditions, but the directive is clear enough for most use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Scan a web server with nikto for dangerous files and misconfiguration.
Aggressive, and gated: nikto walks a database of several thousand paths, so it is loud, obvious in logs, and will trip a WAF. That is a decision for a human, not a default.
Two bounds apply and neither is negotiable. -maxtime stops nikto from the
inside so its report still gets written, and the process timeout sits above
it as a backstop. max_minutes is clamped to MAX_SCAN_MINUTES (30).
Pacing comes from scope.rules.max_rps via -Pause; there is no rate
argument. The Denial of Service test group is excluded by a sanitizer pattern
that every -Tuning value must satisfy.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| max_minutes | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively details behavioral traits beyond annotations: it is aggressive, noisy, and gated, requires human approval, enforces time bounds (max_minutes clamped to 30), uses pacing from global rules, and explicitly excludes Denial of Service tests. These details align with and expand upon the annotations (destructiveHint false, openWorldHint true).
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 opens with a concise, front-loaded summary, then delves into details. While informative, the later sections use poetic wordplay ('aggressive, and gated', 'two bounds apply') that adds length without essential information. It is not overly long, but trimming would improve clarity and directness.
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?
The description covers key operational context: approval requirement, time limits, global pacing, and excluded tests. It does not explicitly explain target format (URL vs host) or output details, but the output schema is present and target is self-explanatory. Overall, it provides sufficient context for an agent to safely invoke the 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?
The description explains max_minutes as a time limit clamped to 30, which adds meaningful context to the schema (which only shows an integer default). It does not explain target, but the term 'web server' and the tool's name make its purpose obvious. Since one of two parameters is enriched, this compensates for the low schema coverage stated in signals.
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's purpose: 'Scan a web server with nikto for dangerous files and misconfiguration.' It uses a specific verb (scan), identifies the resource (web server), and specifies the scope (dangerous files and misconfiguration). This distinguishes it from other scanners by name (nikto) and intent.
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 contextual warnings (aggressive, requires human approval, loud, may trip WAF) but does not explicitly compare to sibling tools like nuclei_scan or wapiti_scan. It does imply this is a heavy scanner, but lacks explicit 'use this when...' guidance, leaving the agent to infer when nikto is preferred over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Detect NoSQL injection (MongoDB operator injection) with nosqli.
data supplies one name=value body parameter, and it should be a
valid value (username=alice): the tool mutates what you give it, and a
body rejected before it reaches the query tests nothing.
One pair, not a body, because & is hard-denied for every argument in this
project and nosqli's --data takes a single string. A login form needing
both a username and a password cannot be expressed here — test that by hand,
or with a proxy-driven request. Saying so is the point: the alternative is a
probe that silently tests half the form.
Authentication bypass is the usual impact: {"password": {"$ne": ""}}
matching every document. This probe stops at detection, and enumerating a
collection to show severity is exactly what "do not exfiltrate" means.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool mutates the provided data, which aligns with the destructiveHint annotation. It also clarifies that it only detects and does not exfiltrate data, providing transparency about its operational scope. No contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is unnecessarily verbose and repetitive. It includes multiple tangential statements about the limitations of the tool and ethical warnings, which could be condensed. For example, the same idea about a single data pair is expressed in multiple sentences. A more concise version would be more effective.
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?
Overall, the description includes enough context about usage constraints and behavior to guide an agent effectively, including security considerations and the distinction between detection and exploitation. However, the lack of explanation for the 'target' parameter and the excessive verbosity reduce completeness slightly.
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 description thoroughly explains the 'data' parameter, including its format and constraints, but does not mention the 'target' parameter at all. Since target is a required parameter, leaving it undefined reduces clarity. Schema coverage is incomplete for one of the two 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 detects NoSQL injection (MongoDB operator injection) using nosqli. This is a specific verb and resource, and it distinguishes itself from other injection-related sibling tools like sqli_validate and web_injection_probe.
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 detailed usage guidance, including that 'data' must be a single name=value pair, that the tool mutates input, that ampersands are hard-denied and only one pair is allowed, and that a login form with both username and password cannot be tested here. It also states the probe stops at detection and advises against exfiltration, giving clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Scan in-scope targets with Nuclei templates or a workflow.
templates: template files/dirs/ids to run. Custom rules under rules/nuclei/ are always included. workflow: a workflow file for conditional chaining. tags: comma-separated template tags (dos/fuzz/intrusive are refused).
Returns inline if it finishes within wait_seconds, otherwise a job_id.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| target | Yes | ||
| severity | No | low,medium,high,critical | |
| workflow | No | ||
| templates | No | ||
| concurrency | No | ||
| wait_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds several behavioral details beyond the annotations: it requires human approval (AGGRESSIVE), returns inline or as a job_id based on wait_seconds, includes custom rules automatically, and refuses certain tags. These are meaningful disclosures not present in the annotations. It does not detail the potential side effects of active scanning, but the 'AGGRESSIVE' warning and approval requirement cover the main risk. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, with a warning up front, then a brief main statement, followed by a bulleted list of key parameters. It front-loads the critical approval requirement and the core purpose. The parameter list is efficient, though it could be more organized. No wasted words, but it's a bit dense.
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 tool with 7 parameters, the description covers the essential operational details: approval requirement, inline vs job execution, tag restrictions, and template/workflow semantics. It has an output schema, so return values need not be described. It doesn't explain how 'in-scope' is defined or prerequisites, but those are domain concepts likely covered elsewhere. Overall, it provides enough context for an agent to call it correctly, with minor gaps around severity and concurrency.
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?
With 0% schema description coverage, the description carries the full burden for parameter explanation. It explains templates (files/dirs/ids), workflow (file for conditional chaining), tags (comma-separated, with refused ones), and implicitly wait_seconds (via inline vs job behavior). However, it omits severity and concurrency, which are self-explanatory but still undocumented. The description compensates well for the schema gap but not completely.
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 in-scope targets using Nuclei templates or a workflow. It names the specific engine (Nuclei) and the resource (in-scope targets), which distinguishes it from other scanning tools like nikto_scan or jaeles_scan. The main purpose is unambiguous, though it could be more explicit about what a 'scan' entails (e.g., vulnerability detection).
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 gives no guidance on when to choose this over alternative scanning tools. It implies usage for running Nuclei templates, but doesn't mention when to prefer it over jaeles_scan or others. The only conditional guidance is the restriction on dos/fuzz/intrusive tags, which is a prohibition rather than a usage scenario. No when-to-use or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Start an interactsh listener and return the callback URL for blind classes.
Inject the returned URL into the suspected sink, wait, then check the polled interactions. A DNS or HTTP hit from the target's infrastructure is the proof.
| Name | Required | Description | Default |
|---|---|---|---|
| duration_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by noting the aggressive nature and required human approval, and it describes the side effect of starting a listener and returning a URL. This provides useful behavioral context that annotations (readOnly=false, destructive=false) do not fully convey.
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 concise, with a clear first sentence stating the main action and a second sentence outlining the usage flow. It is well-structured and front-loaded, though it could be slightly more compact.
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?
The description lacks essential operational details: it does not explain what the output (callback URL) looks like, how 'polled interactions' are retrieved or formatted, or how duration_seconds affects behavior. This leaves significant gaps for an agent to correctly invoke and interpret results.
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 description does not mention the 'duration_seconds' parameter at all. Schema coverage for parameters is 0%, and the description fails to compensate by explaining any parameter behavior, leaving the agent without semantic understanding of how to set or use 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 clearly states the tool's primary function: starting an interactsh listener and returning a callback URL for blind classes. This is specific and distinguishes it from other tools in the sibling list that focus on scanning, probing, or validation.
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 a brief workflow ('Inject the returned URL into the suspected sink, wait, then check the polled interactions') but does not explicitly state when to choose this tool over others, nor does it contrast with alternative OOB or listener tools. It implies a use case but lacks explicit decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Run a named Osmedeus flow from the reviewed flows directory.
Only flows present in engines.osmedeus.flows_dir may be run — arbitrary flow paths are refused because an Osmedeus flow can execute shell commands.
| Name | Required | Description | Default |
|---|---|---|---|
| flow | No | general | |
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description warns that 'an Osmedeus flow can execute shell commands,' implying potential destructive capability. However, the annotations state destructiveHint: false, which contradicts this warning. Since the description contradicts the annotation, this dimension receives the lowest score.
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 concise, consisting of two sentences that are direct and to the point. It efficiently conveys the core action, the restriction, and the reason for the restriction without unnecessary detail.
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?
The description gives important context about the security restriction and the requirement for human approval, but it lacks details about what Osmedeus flows actually do, what the 'target' is used for, or what output to expect. This leaves some contextual gaps for an agent deciding when to use the 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?
The schema lists two parameters (flow and target) but provides no descriptions. The tool description does not explain what 'target' represents or what values 'flow' can take (beyond the default 'general'). With zero parameter coverage in the schema and no compensation in the description, this scores poorly.
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's purpose: 'Run a named Osmedeus flow from the reviewed directory.' This is a specific verb and resource, and the restriction to the reviewed directory distinguishes it from other flow-related tools. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance by explicitly forbidding arbitrary flow paths and explaining the security reason (flows can execute shell commands). This tells the agent when it is safe to use the tool and what constraints apply. However, it does not explicitly contrast with alternative tools, so it loses one point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Discover hidden request parameters on a URL with Arjun.
Guessing costs requests. Mine endpoint_discovery's archive results for parameter names first — they are free and already known to exist.
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | GET | |
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint:false, openWorldHint:true, destructiveHint:false), the description adds crucial behavioral context: it flags the tool as 'AGGRESSIVE — requires human approval' and states 'Guessing costs requests.' This informs the agent of the tool's active, high-cost nature, which is not captured in the annotations alone.
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 two sentences long and front-loaded with the most critical information (the aggressive nature and approval requirement). Every sentence earns its place, providing purpose and usage guidance without unnecessary verbosity.
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 (a live scanning tool with an output schema), the description covers the essential aspects: purpose, usage prerequisite, and behavioral warnings. The missing parameter explanations are a minor gap, especially since the output schema likely clarifies return values. Overall, the description is well-rounded and sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented parameters. It implicitly identifies 'target' as the URL ('Discover hidden request parameters on a URL'), but it does not explain the 'method' parameter (e.g., GET/POST) or provide any format hints. The description adds minimal value beyond what a user could guess from 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's function: 'Discover hidden request parameters on a URL with Arjun.' This includes a specific verb (discover), a resource (hidden request parameters on a URL), and the tool used (Arjun). It effectively distinguishes itself from siblings like content_discovery and endpoint_discovery, which have different objectives.
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 explicit usage guidance: it instructs the agent to 'Mine endpoint_discovery's archive results for parameter names first' and notes that guessing costs requests. This tells the agent when to use this tool (after exhausting free, known parameter names) and directly names the alternative (endpoint_discovery). The warning about aggressiveness and human approval further sets expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan URLs (and optionally their response bodies) with vetted gf patterns.
Classifies each URL by its query parameters and path segments, and — when
scan_bodies is true — fetches it once and scans the response for sink
shapes. Results are grouped by bug class, each candidate naming the
validator that would prove or kill it. Nothing here files a finding: a
pattern match is a lead, and the validators exist because leads are usually
wrong.
target names URLs, or "auto" to inherit the live URLs an earlier phase
recorded. The pattern library lives in rules/gf/; if it failed to load,
this returns UNTESTED rather than an empty scan.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| max_urls | No | ||
| scan_bodies | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint: true, destructiveHint: false) align with the description. The description explicitly states that fetching occurs only when scan_bodies is true, and emphasizes that no findings are filed—only leads. This provides clear transparency about no persistent side effects while acknowledging network requests.
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 concise but includes necessary details. It is organized into multiple sentences but each provides relevant information—no fluff. The structure is clear, though it could be slightly more compact by merging some clauses without losing meaning.
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?
The description gives a high-level overview of the output (results grouped by bug class, each candidate naming validator). While the context indicates an output schema exists, it is not provided in the tool definition, so the description offers enough context for an agent to understand the expected result shape. Slightly lacking in specifying output format details.
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 description explains the target parameter (URLs or 'auto') and scan_bodies (fetches and scans response when true). However, max_urls is not described, and the schema has no descriptions. Since most parameters are covered, it earns a 4, but the lack of explanation for max_urls prevents a perfect 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's purpose: scanning URLs (and optionally response bodies) with vetted gf patterns. It specifies the exact actions (classifies URLs by query parameters/path segments, scans response for sink shapes) and differentiates itself from other scanning tools by mentioning 'vetted gf patterns' and the fact that results are leads, not findings.
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 guidance on when to use the tool, explaining that results are grouped by bug class and each candidate names a validator, implying it is for reconnaissance rather than confirmation. It also mentions the 'auto' option for inheriting URLs from earlier phases. However, it does not explicitly compare to alternative scanning tools (e.g., nuclei_scan), so the when-to-use guidance is implicit rather than direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the payload wordlists available to content and parameter discovery.
Names returned here are what content_discovery expects for its
wordlist argument. Touches no target and costs no budget.
Only tier A discovery wordlists appear. Tier B injection payloads belong to the approval-gated exploitation tools, and tier C is quarantined and has no name bound to it at all — see docs/PAYLOADS.md.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'touches no target and costs no budget,' which goes beyond the readOnlyHint annotation by specifying no network or resource side effects, and also notes tier C has no name bound, adding transparency about 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 concise, well-structured, and avoids unnecessary verbiage, covering essential points in a few sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, use context (content_discovery), tier limitations, and points to documentation, providing enough context for an agent to decide when to call it; output schema exists, so return details are not required.
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 schema has one optional parameter 'tool' with no description of its purpose, and the description mentions no parameter at all, leaving agents without guidance on whether or how to use it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists payload wordlists for content and parameter discovery, explicitly notes it touches no target and costs no budget, and distinguishes it from other tools by referencing content_discovery's expected wordlist argument.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides direct guidance on when to use this tool (to obtain wordlist names for content_discovery) and when not to (tier B for approval-gated exploitation tools, tier C quarantined), with a pointer to docs for details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where the pipeline is right now: per-phase state, next pending phase.
Machine-readable version of the status.jsonl trail — branch on
state/next instead of tailing files.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and non-destructive annotations already cover side-effect safety. The description adds useful behavioral context: it is a machine-readable view of the status trail intended for branching, not a mutation or file-tail operation.
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 compact and front-loaded with the core purpose in the first clause. The second sentence clarifies the machine-readable intent without padding.
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 parameterless status tool, the description sufficiently conveys what is returned (per-phase state, next pending phase) and how to use it (branch on state/next). No additional context is necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is trivially complete. No parameter explanations are needed; the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly indicates this tool reports the current pipeline state and next pending phase. It does not explicitly name sibling alternatives, but the phrasing 'Where the pipeline is right now' is specific enough for a status getter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides implicit guidance ('branch on state/next instead of tailing files') that this is for programmatic consumption of pipeline status. It does not explicitly contrast with related tools like job_status or dashboard_state, leaving some ambiguity about when to prefer this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a proof-of-concept a human reproduced, and confirm the finding.
For the classes no tool should prove on its own — IDOR, auth bypass, RCE, blind SSRF — this is how a finding becomes confirmed: a person reproduced it and wrote down exactly what they did and what happened.
All three of reproduction, expected_result, and observed_result are required. A PoC missing the observed result is a hypothesis.
| Name | Required | Description | Default |
|---|---|---|---|
| finding_id | Yes | ||
| reproduction | Yes | ||
| expected_result | Yes | ||
| observed_result | Yes | ||
| evidence_excerpt | No | ||
| impact_limit_note | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint: true declares a read-only operation, yet the description describes recording a PoC and confirming a finding — both state-changing operations. 'Confirm the finding' implies transitioning a finding's status, and 'this is how a finding becomes confirmed' reinforces state modification. This is a serious inconsistency that misleads the agent about side effects, mirroring the create_record contradiction pattern.
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 well-structured with the core purpose front-loaded in the first sentence. Three short paragraphs cover purpose, usage context, and parameter requirements without excessive verbosity. Minor redundancy exists between paragraphs 1 and 2, both restating the human-reproduction concept, but the overall structure is clean and purposeful.
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?
The description provides strong contextual framing for the security workflow — explaining why human verification matters and when this tool fits in the assessment lifecycle. However, it leaves operational gaps: the source of finding_id, what 'confirm the finding' changes in practice, and how this integrates with the broader findings workflow are unspecified. For a 6-parameter tool with 4 required fields, the operational mechanics are incomplete.
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 schema has 0% description coverage. The description partially compensates by naming reproduction, expected_result, and observed_result and explaining their significance via the 'hypothesis vs. PoC' distinction. However, finding_id, evidence_excerpt, and impact_limit_note are entirely unexplained — the agent receives no guidance on where finding_id originates or what the optional fields should contain.
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's purpose: recording a human-reproduced proof-of-concept and confirming a finding. It distinguishes this from automated validation by naming the vulnerability classes (IDOR, auth bypass, RCE, blind SSRF) where tool-only proof is insufficient. However, the read/write contradiction with the readOnlyHint annotation slightly muddies the operational purpose.
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 explicitly identifies when this tool should be used: for vulnerability classes where no tool should confirm findings on its own, requiring human reproduction and written documentation. It also implies when not to use it — when automated validation suffices or when observed_result is absent (making it a hypothesis rather than a PoC). It does not explicitly name alternative sibling tools, but the scope boundary is clearly drawn.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Discover open TCP ports with naabu.
ports: "top-100", "top-1000", or an explicit list like "80,443,8080-8090". CDN ranges are excluded automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| ports | No | top-100 | |
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations by labeling the action as 'AGGRESSIVE — requires human approval' and stating that CDN ranges are excluded automatically. It does not elaborate on potential side effects or network impact, but the aggressive warning sufficiently covers the main concern.
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 compact and well-organized, leading with a cautionary note, then the primary action, and followed by parameter-specific guidance. Every sentence contributes useful information without 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?
For a simple scanning tool, the description provides enough information to invoke it correctly: required target, optional ports with format, and the CDN exclusion behavior. The output schema is indicated as present, so the description does not need to explain return values, though a brief note on result format would make it fully 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?
The schema provides no descriptions for either parameter, but the tool description significantly compensates by detailing the allowed values for 'ports' (including a default behavior). 'target' is not described, though its purpose is fairly obvious in the context of a port scanner, leaving only a minor gap.
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 ('Discover open TCP ports') and the tool ('naabu'), making the primary purpose unambiguous. It also distinguishes itself from sibling scanning tools by explicitly focusing on TCP port discovery and excluding CDN ranges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides concrete usage context by explaining the 'ports' parameter options ('top-100', 'top-1000', or an explicit list) and the automatic CDN exclusion. However, it does not explicitly compare against alternatives like service_scan or when to prefer this tool over them, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a bug bounty program's published scope into a scope.yaml scaffold.
program is a HackerOne handle or policy URL (e.g. acme or
https://hackerone.com/acme). The tool fetches the policy page, extracts
the in-scope and out-of-scope domains/wildcards the page declares, and
writes out (default scope.yaml) as a transcription scaffold.
The file is NOT a finished authorization: cordon scope validate keeps
warning until you review it, rename the engagement, and confirm the
entries against the policy page. Never run the pipeline on a scaffold you
have not reviewed.
| Name | Required | Description | Default |
|---|---|---|---|
| out | No | scope.yaml | |
| program | Yes | ||
| researcher_handle | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says it writes to an output file, which is a side effect, yet the annotation `readOnlyHint: true` indicates the tool is read-only. This is a direct contradiction, and the description does not reconcile it or disclose other potential side effects like network access or file creation.
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 concise, using only a few sentences, and each sentence adds meaningful information: what it does, how it does it, and a critical warning. No unnecessary repetition or verbosity.
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 fetch-and-write tool it covers the core action and the caution about validation, but it leaves `researcher_handle` unexplained and does not address the contradictory read-only annotation. It also does not mention return values or error conditions, though an output schema may partially cover that.
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?
It clarifies that `program` is a HackerOne handle or policy URL, and notes the default for `out`. However, `researcher_handle` is not explained at all, and the schema itself has no descriptions, so coverage is partial.
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 fetches a bug bounty program's published scope and writes it to a scaffold file, with explicit mention of extracting in-scope and out-of-scope domains. The verb 'fetch' and resource 'scope' are 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?
It provides a caution that the output is not a finished authorization and references `cordon scope validate`, but it does not explicitly compare against sibling tools or state when to use this tool versus alternatives. The guidance is implicit rather than direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the vulnerability classes that have an exploit/validation prompt pack.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already include readOnlyHint=true and destructiveHint=false, and the description does not contradict these. The description adds no extra behavioral details beyond what the annotations provide, so it meets the baseline for tools with annotations but does not exceed it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's purpose without any unnecessary words or repetition. It is front-loaded with the action 'List' and the resource, making it highly efficient.
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 listing tool, the description provides sufficient context about what is being listed (vulnerability classes with exploit/validation prompt packs). It does not detail the output format or further nuance, but that is not critical for a list operation, and the description is complete enough for an agent to know when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the schema reflects this with an empty properties object (100% coverage). The description does not need to explain parameters, so the baseline score of 3 applies here—it is neither enhanced nor degraded by 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 clearly states the tool lists vulnerability classes that have an exploit/validation prompt pack, using the specific verb 'List' and a precise resource. It distinguishes itself from sibling tools like 'exploit_prompt' or 'validate_findings' by focusing on enumeration of classes rather than execution or validation.
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 when you need to know which vulnerability classes have available prompt packs, but it does not explicitly mention alternatives or conditions for when not to use this tool. Given the large number of sibling tools, more guidance on when to choose this over others would be beneficial, but it is adequate for a simple listing operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank live hosts by how worth they are of manual testing.
Reads the asset store (probe results + scope focus URLs) and returns the
top limit hosts with scores and the reasons behind each. Zero traffic.
The top of the list is the hand-off for auth_surface (find the login)
and auth_crawl/authz_compare (test behind it).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/not-destructive annotations, the description adds 'Zero traffic', which is a valuable behavioral detail. It also states that it reads the asset store, making side effects clear and minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two crisp, focused sentences. It uses backticks for code identifiers and provides all essential information without any 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 simple input and output, the description fully covers what it does, what it reads, what it returns, and how to chain it with subsequent tools. No missing information that would prevent correct 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?
The only parameter, limit, is explained in the description as the number of top hosts to return. The schema itself lacks a description (0% coverage), but the prose compensates. It is enough for an agent to correctly use it, though no bounds or edge cases are mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Rank live hosts by how worth they are of manual testing.' It clearly defines the input (asset store) and output (top hosts with scores and reasons), and distinguishes itself from sibling tools by positioning itself as the hand-off for auth testing.
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?
Provides explicit when-to-use guidance by naming the follow-up tools (auth_surface, auth_crawl/authz_compare) and the intended flow. It does not explicitly state when not to use it, but the context is strong enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write Report.md, Report.csv, findings.json, and the task graph to reports/.
Confirmed findings (those with a reproducible PoC) are reported separately from unproven leads. Pass partial_reason when a run stopped early so the report says so on its first page.
| Name | Required | Description | Default |
|---|---|---|---|
| formats | No | ||
| partial_reason | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly says the tool writes files to the reports directory, which directly contradicts the annotation readOnlyHint: true. This contradiction makes the tool's behavior ambiguous and undermines transparency. Other behavioral details (separating confirmed findings, partial reason placement) are provided, but the core write action conflicts with the stated read-only nature.
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 two sentences, concise, and front-loaded with the primary action. It avoids unnecessary details and includes relevant nuances without verbosity.
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?
The description covers the main output files and the key behavioral nuance of separating confirmed findings from unproven leads, plus the partial_reason use case. It lacks an explanation of the formats parameter and does not describe the output schema, but the core purpose and major behaviors are clear enough for typical 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?
The schema provides no descriptions for the parameters (0% coverage). The description explains partial_reason (used to indicate an early stop and affect the first page) but does not explain the formats parameter. This partially compensates for the missing schema information, but leaves one parameter undocumented.
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 writes Report.md, Report.csv, findings.json, and the task graph to reports/, and further clarifies that confirmed findings are separated from unproven leads. This gives a specific verb (write), resource (reports), and scope.
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 a specific usage instruction: pass partial_reason when a run stopped early so the report says so on its first page. It does not discuss alternatives or when not to use the tool, but the guidance given is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Research a vulnerability class and produce an actionable testing playbook.
vuln_class is a bug class ("sql-injection", "xss", "ssrf", "idor",
"request-smuggling", … — fuzzy names work). asset is the URL under
test, evidence any observation so far (a 403, a parameter, a scanner
hit), stack the observed technologies (comma-separated) to scope the
brain's memory recall. Read-only: assembles knowledge, sends no traffic.
To execute the validators it names, call guided_validate instead.
| Name | Required | Description | Default |
|---|---|---|---|
| asset | No | ||
| stack | No | ||
| evidence | No | ||
| vuln_class | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: 'Read-only: assembles knowledge, sends no traffic.' This goes beyond the annotations by explicitly stating no traffic is sent and clarifying the internal memory-recall scoping via the stack parameter. This adds value without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The primary purpose is stated in the first sentence, parameter definitions follow with backtick formatting, and the alternative is given at the end. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the presence of an output schema, and the annotations, the description covers all essential aspects: purpose, parameter semantics, read-only behavior, and routing to guided_validate for execution. Nothing an agent needs to decide whether and how to invoke this tool is missing.
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 0%, so the description fully compensates. It explains each parameter: vuln_class (bug class with examples and fuzzy-name tolerance), asset (URL under test), evidence (observations like 403 or scanner hits), and stack (comma-separated technologies to scope memory recall). This adds substantial meaning beyond the bare 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's purpose: 'Research a vulnerability class and produce an actionable testing playbook.' It uses a specific verb (research), a specific resource (vulnerability class), and a clear deliverable (playbook). It also explicitly differentiates from guided_validate by stating that executing validators should be done there, providing sibling differentiation.
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 clear usage context: it assembles knowledge and produces a playbook, and explicitly says 'To *execute* the validators it names, call guided_validate instead.' This gives an explicit alternative for a distinct action. However, it does not compare against other research-oriented siblings like technique_lookup or wstg_lookup, so guidance on when to choose this over those is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List loaded detection rules and plugins, plus anything rejected at load time. A rejected rule is a detection you do not have — check this when a scan finds less than expected.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| phase | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint already marks it read-only; the description reinforces this with 'list' and adds useful context about surfacing load rejections, with no hidden side effects indicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences with the action and resource front-loaded; no unnecessary words or repetition.
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?
Adequately explains what the tool returns conceptually (loaded and rejected rules) and when to use it, but the parameter meanings are left unexplained and the output schema is not shown, so full context relies on external schema details.
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 schema has two optional parameters (kind, phase) with no descriptions, and the tool description never mentions them, providing zero guidance on their meaning or allowed values.
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 verb 'list' and the resources 'loaded detection rules and plugins', and explicitly includes rejected rules. Distinguished from rules_reload/rule_test by focusing on enumeration of loaded state.
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?
Provides a concrete triggering scenario ('check this when a scan finds less than expected') but does not mention alternatives or when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-scan the rule directories. Use after editing or adding a rule file.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read-like operation ('re-scan') but the annotation readOnlyHint=false signals a write operation. The description does not elaborate on side effects (e.g., reloading rule state, potential impact on active scans). It is consistent but not fully transparent.
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, using two short sentences that front-load the key action and then provide a usage note. Every word adds value; no fluff 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 tool's simplicity and the presence of an output schema (not shown but indicated), the description is adequately complete. It covers the action and usage context, though it could mention the intended effect of the reload more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, and the schema coverage is complete (100%). There are no parameter semantics to explain, 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 the action (re-scan rule directories) and its purpose (update rules after editing/adding). The verb 're-scan' and resource 'rule directories' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear when-to-use condition: 'Use after editing or adding a rule file.' It does not explicitly exclude alternatives, but the guidance is sufficient for the tool's simple purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dry-run the loaded rule-packs against a sample observation (url/status/headers/body) without touching any host. Use this to check a rule before trusting it, and to understand why one did or did not fire.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| body | No | ||
| phase | No | ||
| status | No | ||
| headers | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and the description adds the 'dry-run' and 'without touching any host' details, reinforcing the safety profile. It also hints at explanatory output ('understand why'), which is useful context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action and input, and the use case follows. Zero waste, 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?
With an output schema present, the description need not detail return values. It covers purpose, input composition, and usage scenario. It doesn't mention any prerequisites or edge cases, but given the tool's simplicity and annotations, it is adequately 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 description coverage is 0%, so the description must compensate. It lists url, status, headers, body but omits 'phase' entirely and does not explain the format or purpose of any parameter beyond their names. This is minimal semantics that leaves the agent to infer meaning from names alone.
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 'dry-run' against 'loaded rule-packs' with a specific input (url/status/headers/body). It distinguishes from siblings like rules_list (listing) and rules_reload (reloading) by focusing on testing without host impact.
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 states when to use: 'before trusting it' and 'to understand why one did or did not fire.' Also includes the key exclusion 'without touching any host,' which tells the agent this is a safe, non-intrusive testing tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Run a single phase against a target and record its state.
phase is one of the pipeline phases (probe, scan, exploit, …).
target defaults to the engagement's first seed. extra_json is an
optional JSON object of extra kwargs for the phase's tool (e.g.
{"include_heavy": true} for the exploit phase).
The phase result is persisted to pipeline-state.json and the audit log,
so run_pipeline/pipeline_status and later sessions see it.
| Name | Required | Description | Default |
|---|---|---|---|
| phase | Yes | ||
| target | No | ||
| extra_json | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the main side effects: it records state and persists to pipeline-state.json and the audit log. This is sufficient given readOnlyHint=false and destructiveHint=false. It does not mention potential external network impact on the target, but openWorldHint=true suggests external actions are possible; the description is somewhat vague on that point.
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 concise, with no redundant words. It uses backticks for inline code, making it readable. Each sentence adds value: purpose, parameter clarifications, and persistence behavior. The structure is logical and easy to scan.
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?
The description covers essential context: what the tool does, how parameters behave, and what side effects occur. Since an output schema exists (per context signals), not describing return values is acceptable. The description also mentions the relationship to other tools (run_pipeline, pipeline_status), providing complete operational 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?
The description provides meaningful explanations for all three parameters: phase is defined as one of the pipeline phases, target defaults to the engagement's first seed, and extra_json is an optional JSON object of extra kwargs. This goes far beyond the schema's type-only definitions, achieving high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run a single phase against a target and record its state.' It distinguishes itself from run_pipeline by specifying it runs a single phase, and from specific scanner tools (e.g., jaeles_scan) by being a generic phase runner. The verb 'run' and resource 'phase' are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a single pipeline phase is needed, and explicitly notes the persistence so that run_pipeline and pipeline_status reflect the result, signaling how it fits into the ecosystem. However, it does not directly contrast with run_pipeline or other phase-specific tools, leaving some inference needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Run the engagement pipeline, gated, resumable, in-process.
phases restricts to a comma list ("probe,scan"); from_phase starts
at a named phase; exploit adds the exploit phase (still refused unless
the scope authorizes exploitation).
Each phase runs through its registered MCP tool — the full control-plane
chain applies per phase — and results land in pipeline-state.json +
the audit log. Finished phases are skipped on re-entry, so a dropped
session resumes where it stopped.
| Name | Required | Description | Default |
|---|---|---|---|
| phases | No | ||
| target | No | ||
| exploit | No | ||
| from_phase | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits: it requires human approval, is resumable, and may include an exploit phase (explicitly gated by scope). It also mentions that finished phases are skipped, which is a useful side effect. It does not fully enumerate all pipeline actions, but the provided information aligns well with the annotations and adds detail beyond them.
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 concise, containing a brief summary line followed by a short technical paragraph. It is well-structured with clear line breaks. No redundant or filler content is present, making it easy to parse quickly.
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?
The description covers the core functionality and parameter usage, but it does not mention any output schema or return behavior. Given the pipeline's complexity and the presence of an output schema, this omission leaves a significant gap in understanding what the tool returns or how to interpret results. It is functional but incomplete.
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?
With zero schema description coverage, the description compensates by explaining three of the four parameters: 'phases', 'from_phase', and 'exploit'. However, the 'target' parameter is left entirely unexplained, which is a notable gap. The partial explanation is valuable but not complete.
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's primary function: running the engagement pipeline. It adds key qualifiers like 'gated, resumable, in-process' which help differentiate it from a single-phase runner. However, it does not explicitly contrast with sibling tools like run_phase, leaving a slight ambiguity in tool selection.
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 explains how to control phases and exploitation, giving partial usage guidance. It illustrates parameter usage (e.g., 'phases restricts to a comma list') but does not explicitly state when to prefer this tool over run_phase or any other alternative. The guidance is present but not comparative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask whether targets are in scope WITHOUT touching them. Use this before planning work against a newly discovered host.
| Name | Required | Description | Default |
|---|---|---|---|
| targets | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that the tool does not touch targets, which is consistent with the readOnlyHint annotation. This fully discloses the side-effect-free nature of the 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 two concise sentences with no redundant information. It is tightly structured and focused on the essential purpose and usage.
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?
The description omits details about the input format and the output of the tool. While the purpose is clear, the missing parameter specification and output format leave the agent without complete context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about the 'targets' parameter, such as expected format (hostnames, IPs, URLs) or any constraints. Schema coverage is 0%, and the description adds no value to the parameter definition.
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's purpose: to ask whether targets are in scope, with an explicit emphasis on not touching them. It also provides a specific use case: before planning work against a newly discovered host.
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 explicitly instructs when to use the tool ('Use this before planning work against a newly discovered host') and provides a caution about not touching targets, which serves as a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan files in the engagement workspace for credentials. No validation.
Runs Kingfisher (primary), Nosey Parker (git history + ML denoising), and gitleaks where installed. Sends no traffic anywhere — every hit is a candidate until secret_validate says otherwise.
path is workspace-relative; paths outside the workspace are refused.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . | |
| git_history | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses that no traffic is sent, no validation is performed, and paths outside the workspace are refused. These are important behavioral details that help avoid unintended actions.
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 concise, front-loaded with the core purpose, and contains no redundant content. Each sentence adds meaningful information about behavior, tooling, or parameter constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return-value details are not necessary. The description covers purpose, behavior, and path constraints, but the git_history parameter remains under-specified, leaving a small gap in 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?
The description explicitly explains the path parameter (workspace-relative, outside paths refused), but git_history is only indirectly implied through the Nosey Parker mention. Schema coverage is 0%, so more direct parameter explanation would improve clarity.
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 scans files in the engagement workspace for credentials and explicitly distinguishes itself from validation by noting every hit is a candidate until secret_validate is used. The verb-resource pairing is specific and 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?
Provides explicit guidance on when to use the tool (scanning for credentials) and directs the user to secret_validate for follow-up validation. Also mentions the safety property of sending no traffic, which helps the agent decide appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Validate candidate credentials with Kingfisher and map their blast radius.
This is what makes a secrets report actionable: a live credential is critical, an unvalidated match is noise. It is gated because validation is use — the request goes to AWS/GitHub/Stripe authenticated as whoever owns the key.
Validation traffic is paced at the engagement's max_rps. That ceiling was
written for the target, and these requests go to third parties instead — but
it is the only rate this engagement has consented to, and issuing hundreds of
authenticated requests per second at anyone is not something a scan should
decide on its own.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond annotations by disclosing that validation sends authenticated requests to AWS/GitHub/Stripe as the key owner, explains the risk ('validation is *use*'), and details rate pacing constraints. Annotations only say readOnlyHint=false and openWorldHint=true, which are consistent but less informative. The description adds crucial behavioral details about side effects and consent, which is excellent transparency.
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 lengthy, with a bold warning and a detailed explanation of the gating rationale and pacing. While every sentence earns its place for risk communication, it's not concise. The structure is front-loaded with the warning, which is good, but the overall length is higher than necessary for a tool with one parameter.
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 there's an output schema (so return values are covered), the description covers purpose, risk, and behavior. However, it fails to explain the input parameter 'path', which is essential for correct invocation. It also assumes the agent knows what 'candidate credentials' are and where they come from. The completeness is moderate: behavior is well covered, but input semantics are missing.
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 only parameter 'path' has a default of '.' and no schema description (coverage 0%). The description does not explain what 'path' refers to, whether it's a file path to a secrets list, a directory, or something else. With zero schema coverage, the description must compensate, but it doesn't mention the parameter at all. This is a significant gap.
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 ('validate') and resource ('candidate credentials'), and explains the purpose ('map their blast radius'). It also differentiates from siblings like secret_scan by emphasizing that validation makes a secrets report actionable, implying a post-scan step. The 'AGGRESSIVE — requires human approval' warning adds distinctive context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives context on when to use: after scanning, for live credential validation, and explains why it's gated. It doesn't explicitly name alternative tools or conditions for not using it, but the purpose is clear enough that an agent can infer it's for validating secrets rather than scanning or general validation. The warning about pacing and third-party requests further clarifies its usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch /.well-known/security.txt and report the declared security contact.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately reflects the read-only, non-destructive nature (consistent with annotations) and mentions 'fetch' and 'report' which are safe operations. However, it does not explain what happens if the file does not exist, whether it returns the entire file or just the contact, or any potential edge cases. The core behavior is clear but not deeply detailed.
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, consisting of a single sentence that conveys the essential action and output. It avoids unnecessary detail and is well-structured, making it easy to parse. No redundancy or verbosity.
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, the description still lacks key contextual information. It does not explain how 'target' should be formatted, what the output schema looks like, or how to handle cases where the security.txt file is missing or malformed. This would hinder an agent's ability to use the tool effectively without additional external knowledge.
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 only parameter, 'target', is completely undocumented. There is no description of what it represents (e.g., a URL, domain, or IP) or the expected format. With 0% schema coverage, the description adds no meaning, leaving the parameter ambiguous and hard to use correctly.
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 that the tool fetches the security.txt file and reports the declared security contact. This is a specific, unambiguous purpose. However, it doesn't differentiate itself from sibling tools that might perform similar fetches, which keeps it from a perfect score.
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 lacks any mention of prerequisites, typical scenarios, or conditions under which this tool should be preferred. There is no distinction from other fetch-related tools, leaving the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run Semgrep (plugin class D) over source in the engagement workspace.
Passive: reads files already fetched into the workspace and sends nothing to the target. Rules in rules/semgrep/ always participate; config may add a registry pack ('p/security-audit') or another workspace path.
Use source_fetch first to bring a repository into the workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | source | |
| config | No | ||
| severity | No | ||
| wait_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, and the description adds that it reads files already fetched and sends nothing to the target, reinforcing passivity. It also explains config behavior (always includes rules/semgrep/ and can add registry pack). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose, then behavior, then prerequisite. No redundant phrasing or wasted words.
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?
While output schema exists, the description omits semantics for three of four parameters and doesn't explain how results are returned or stored. It also doesn't clarify severity filtering or wait_seconds behavior, making it incomplete for an agent to use 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 0%, so the description must compensate. It only partially explains config (can add registry pack or workspace path), but leaves path, severity, and wait_seconds unexplained. This is insufficient given zero schema documentation.
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 Semgrep over source in the workspace, with a specific verb and resource. It also notes passivity, which distinguishes it from active scanning siblings, but does not explicitly differentiate from other static scanners like secret_scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a prerequisite (use source_fetch first) and mentions passive behavior, but does not state when to prefer this over alternative scanning tools or give exclusion criteria. It lacks explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Fingerprint services on specific ports with nmap -sV plus safe NSE scripts.
scripts is restricted to default/discovery/version/banner. Exploit, dos,
brute, malware, intrusive, and safe-as-a-category are refused: the safe
category pulls broadcast-* scripts (which crash nmap with the
nse_nsock.cc:342 assertion and probe the LAN instead of the target) and
http-slowloris-check (which holds connections open and stalls the whole
scan at the engagement's rate limit). default is the curated category
that fingerprints without either failure mode.
ports defaults to what port_scan already discovered for the
requested hosts (the open_port assets in the store) and falls back to the
web ports 80,443 only when nothing was discovered. target may name
several hosts — the service phase feeds it every host that has an
open_port asset, so one nmap pass fingerprints the whole estate instead of
the single focus host. The old design scanned one host's 80,443 and
silently reported "no services" on every estate that runs on 3000/8080/
8443 — exactly the ports port_scan exists to find. The chain is
ports -> services; services must consume what ports produced.
| Name | Required | Description | Default |
|---|---|---|---|
| ports | No | ||
| target | Yes | ||
| scripts | No | default |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is transparent about the aggressive nature (requires human approval) and the network-scanning behavior (nmap -sV). It also details specific failure modes of certain script categories. However, it does not explicitly state what the tool returns or whether it writes results back to the store, leaving some behavioral ambiguity.
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 detailed and dense with essential information, but it is somewhat lengthy and could have been trimmed without losing critical content. Nonetheless, every sentence serves a purpose, explaining defaults, restrictions, and rationale.
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?
The description provides complete context for an agent: it explains the dependency on port_scan, the multi-host feed from the service phase, the historical pitfalls of the old design, and the chain relationship. This is sufficient for an agent to correctly integrate the tool into a larger workflow.
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?
Although the input schema provides no per-parameter descriptions, the tool description fully explains all three parameters: target (may be multiple hosts), ports (defaults to discovered open ports, else 80/443), and scripts (defaults to 'default', with allowed categories specified). This adds significant meaning beyond the schema's basic type information.
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 explicitly states that the tool fingerprints services on specific ports using nmap -sV and safe NSE scripts. It clearly delineates the tool's function from siblings like port_scan and provides a concrete use case, 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?
The description gives thorough usage instructions: it explains the default ports (from port_scan results, falling back to 80/443), the multiple-host target behavior, and the chain 'ports -> services'. It also warns against certain script categories (safe, exploit, etc.) and explains why, so an agent knows exactly how and when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List registered sessions. Values are masked.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the important behavioral detail that values are masked, which is beyond the annotations and informs the agent that output will not contain raw sensitive data. This adds value without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, each earning its place. The primary purpose is stated first, and the masking behavior follows immediately. No filler or redundancy; the description is optimally concise for the tool's simplicity.
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 parameters and an output schema is present, the description covers everything an agent needs to invoke it correctly: what it does and the masking caveat. No additional details such as pagination or filtering are necessary for this basic list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to explain. The baseline of 4 applies since the schema is empty and the description need not compensate for missing parameter docs. The description correctly focuses on behavior rather than 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 lists registered sessions, providing a specific verb and resource. It is distinct from the sibling session_register, which implies creation, so the purpose is clear. However, it does not explicitly differentiate itself from other session-related tools, missing a chance to name the sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. There is no mention of conditions for use, exclusions, or comparison with sibling tools like session_register. The agent must infer the appropriate context from the name and purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register an authenticated session for later phases to use.
cookies takes sid=abc; csrf=def. headers takes
Authorization: Bearer xyz (semicolon or newline separated).
host is mandatory and is enforced: a session is only ever attached to
that host or its subdomains. Sending an operator's cookie to a host it was
not issued for is a credential leak, and guessing is how that happens.
role is free text — "admin", "user-a", "user-b". Register two
accounts of differing privilege and authz_compare can test authorization
properly; one account only tests that the application works.
Nothing here creates an account. Self-registration is a policy question: some programs invite it, others are silent, and silence is not permission. Read the program's rules, register by hand, then bring the session here.
Values are masked in every result, log and audit entry. The store lives in the engagement workspace, which is gitignored, mode 0600.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| name | Yes | ||
| note | No | ||
| role | No | user | |
| cookies | No | ||
| headers | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description directly contradicts the annotation 'readOnlyHint: true' by stating 'Register an authenticated session,' which implies a state-changing (write) operation. Registering a session involves creating or modifying session state, not a read-only operation. This is a clear annotation contradiction.
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 verbose and repetitive. It includes lengthy security warnings and redundant statements (e.g., 'host is mandatory' is stated twice in different ways). The main purpose is buried under extra prose, making it less concise and harder to scan quickly.
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?
The description does not mention the output schema or any return value. It does not specify success/failure behavior, side effects beyond registration, or how the session might be used later. Given that an output schema exists, the description is incomplete for an agent to fully understand the tool's behavior and expected results.
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 description provides some parameter explanations: it describes the format for cookies and headers, notes that host is mandatory and enforced, and clarifies that role is free text. However, it does not explain the purpose of 'name' or 'note,' and the schema itself has no property descriptions (coverage 0%). The description partially compensates but is not comprehensive.
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's purpose: 'Register an authenticated session for later phases to use.' The verb 'register' and resource 'session' are specific, and the phrasing distinguishes it from other session-related tools like session_list (which lists sessions).
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 explicit guidance on when to use this tool versus alternatives. It implies usage for later phases ('for later phases to use') but does not mention sibling tools like session_list or any conditions that would favor this tool over another. No when-not or alternative comparisons are included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Test for HTTP request smuggling, proving hits by canary reflection.
repeat is how many times each payload is retried; the framework scores
confidence statistically ("17/20 poisoned"), which is the right model for a
bug class that is inherently probabilistic. Capped at 10 by the argument
policy — every increment multiplies the whole payload set.
Returns coverage alongside findings: payloads sent, detectors run, and detectors skipped. A smuggling scan that could not find an echo gadget, or could not confirm queue poisoning, has not tested those things — and this result says so rather than letting zero findings imply a clean front-end.
| Name | Required | Description | Default |
|---|---|---|---|
| http2 | No | ||
| repeat | No | ||
| target | Yes | ||
| timeout | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the annotations: it explains that the tool scores confidence statistically, returns coverage data (payloads sent, detectors run/skipped), and clarifies that zero findings do not necessarily imply a clean target. It does not, however, elaborate on potential side effects or network impact, though the 'repeat' parameter and cap are mentioned.
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 moderately concise, using three sentences to convey purpose, methodology, and output interpretation. It avoids fluff but includes some redundancy (e.g., repeating the cap and the meaning of zero findings) that could be tightened.
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?
The description provides good output context, explaining that results include coverage metrics and that zero findings should not be over-interpreted. It covers the key aspects of what the tool does and what the result means, but omits details like error handling or edge cases, which are less critical for a probe 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 description coverage is 0%. The description explains only the 'repeat' parameter (retry count, capped at 10) but leaves 'http2', 'target', and 'timeout' undescribed. While some may be self-explanatory, the lack of explicit guidance for three of four parameters is a significant gap.
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 clear verb and object: 'Test for HTTP request smuggling' with a specific technique (canary reflection). It distinguishes this tool from generic smuggling probes by emphasizing canary-based proof and statistical repetition.
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 explains the internal methodology (repeat count, statistical scoring) but does not explicitly instruct when to use this tool over alternatives like 'smuggling_probe' or other probing tools. It implies use for confirmation via canaries, but lacks direct comparison or condition-based guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Detect HTTP request smuggling (CL.TE / TE.CL desync) with smuggler.
Unlike everything else in this module, a hit here has collateral: a desync
poisons the connection for whoever uses it next. --exit_early is always
passed so the scan stops on the first finding instead of confirming it a
dozen more times, and the timeout is held low.
The probe is timing-based — smuggler measures whether the back-end waits for a body the front-end already terminated. Treat a hit as a strong lead and re-test manually against a target you control, or with the program's explicit agreement, before writing it up.
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | POST | |
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the destructiveHint and openWorldHint annotations by explicitly stating that the tool requires human approval, can poison connections for subsequent users, uses --exit_early to stop after first finding, keeps timeout low, and is timing-based. This provides full transparency about the tool's actions and risks.
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 slightly verbose but every sentence adds important context—collateral risk, exit_early behavior, timing method, and follow-up advice. It is well-structured, starting with purpose, then risks, then technical details, then recommended post-processing. No unnecessary 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 moderately complex destructive nature and the presence of an output schema, the description covers all essential operational aspects: purpose, risk, execution behavior, and appropriate follow-up. The output schema exists, so not detailing return values is acceptable. The description is complete enough for an agent to decide when and how to use it safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only two parameters (target and method), with target required and method defaulting to POST. The description does not explain these parameters, and schema coverage is 0%. While the meaning of 'target' is obvious and 'method' is likely the HTTP method, the lack of any parameter description means the agent must infer details, especially for the optional method 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 that the tool detects HTTP request smuggling (CL.TE / TE.CL desync) using smuggler, and explains the timing-based technique. It distinguishes this tool from others in the module by warning that it has collateral impact, which is a unique characteristic among the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong usage guidance by stating that unlike everything else in the module, a hit here has collateral, and advises re-testing manually against a controlled target or with explicit program approval. It does not explicitly name alternative tools (e.g., smuggling_canary_probe) but the contrast with other tools is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clone a public repository into the workspace so it can be scanned.
Cloning is separated from scanning so the audit log always answers "what code did Cordon read". Only github/gitlab/bitbucket HTTPS URLs are accepted.
Confirm the repository actually belongs to the program before scanning it — an organization name matching the target is not proof of ownership.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | ||
| repo_url | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds useful context about the separation from scanning and audit logging. It does not explicitly mention that cloning writes files to the local workspace, but this is inherent to the action and not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two tight paragraphs. It front-loads the core purpose, then adds constraints and a caution, with no redundant or filler content.
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?
Provides necessary constraints and a safety caution, but omits an explanation of the depth parameter and does not describe the output or return value (despite an output schema being present). This leaves some ambiguity for a user unfamiliar with the 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?
The schema shows two parameters (depth and repo_url) with no descriptions. The description clarifies repo_url implicitly by mentioning repository URLs, but depth is left completely unexplained, leaving a significant gap for users.
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's purpose with the verb 'Clone', specifies the target (public repository), and the outcome (into workspace for scanning). It also explicitly differentiates cloning from scanning, making the role 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?
Provides concrete usage constraints (only github/gitlab/bitbucket HTTPS URLs) and a caution to verify repository ownership before scanning. However, it does not explicitly state when to prefer this tool over related sibling tools, relying on implicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Detect SQL injection with sqlmap. Detection only, never data extraction.
There is no payload_list here on purpose: sqlmap takes no payload file,
and --tamper — the flag that comes closest — loads executable Python and
is denied for this tool. Its own boolean/time inference is what proves SQLi.
bypass_vendor names a WAF vendor whose sqli bypass set is looked up from
the knowledge base; its first payload is split into a boundary that sqlmap
applies via --prefix/--suffix. A WAF that flags the raw OR 1=1
keyword often lets the same condition through wrapped in the vendor's
evasive boundary. The exploit chain uses it to re-test a point whose base
pass came back clean.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| bypass_vendor | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: it states 'Detection only, never data extraction' while annotations mark destructiveHint: true and readOnlyHint: false. The description itself also labels the tool as 'EXPLOIT', suggesting potentially harmful actions, but does not clearly disclose that it will send requests or could disrupt the target. This lack of clarity and the apparent contradiction reduce transparency.
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 verbose and contains redundant passages—notably, the 'bypass_vendor' explanation appears twice with similar wording. The inclusion of a paragraph about 'payload_list' and '--tamper' adds unnecessary detail that distracts from the core purpose. A more streamlined description would be clearer.
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 and the large list of sibling tools, the description is insufficient. It lacks clear differentiation from similar tools, does not specify operational effects (beyond vague 'detection' vs. 'exploit'), and omits details about target format and error handling. The contradiction between 'detection only' and 'destructive' further undermines 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?
The description explains the 'bypass_vendor' parameter in detail (a WAF vendor name used for bypass), but it does not explain the required 'target' parameter at all. Since target is a required string and likely represents a URL or endpoint, the lack of any semantic guidance for this critical parameter is a significant gap.
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's primary purpose: 'Detect SQL injection with sqlmap. Detection only, never data extraction.' This is specific and distinguishes it from data extraction tools, though the word 'EXPLOIT' at the beginning introduces some ambiguity about whether it is purely for detection.
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 implicitly indicates usage for SQL injection detection and clarifies that it does not perform data extraction, but it does not explicitly compare with sibling tools like web_injection_probe or exploit_chain. The mention of 'requires human approval' is a guideline, but there is no direct statement of when to prefer this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Test one URL parameter for server-side request forgery with SSRFmap.
parameter names the query parameter suspected of taking a URL. The probe
asks the target to connect back to its own loopback interface across a port
list; a port that answers differently from the baseline means the target
performed the fetch, which is the SSRF.
This is deliberately the narrowest of SSRFmap's 24 modules. The ones that
make SSRF interesting — reading IMDS credentials, writing a Redis key,
proxying through the victim — are the ones a bug bounty program means when it
says do not exfiltrate and do not pivot, and they are not on the allowlist.
Confirm reachability here, then prove impact by hand with poc_record().
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| parameter | No | url |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructive, open world), the description discloses that it requires human approval, asks the target to connect to loopback across a port list, and compares responses to a baseline. These details explain the mechanism and potential impact, exceeding the annotation 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 well-structured and appropriately sized. The first sentence states the tool's purpose immediately, followed by concise operational details and a clear scope limitation. No unnecessary verbosity, and the key information 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?
The tool has a simple schema with two parameters, and the description provides sufficient context on behavior, authorization (human approval), and limitations. An output schema is indicated, so the lack of output description is acceptable. The description covers all necessary aspects for correct 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?
The description explains the 'parameter' field as the query parameter suspected of taking a URL, but does not explain 'target', which is a required string. While 'target' is implied to be the URL to test, it is not explicitly described. Schema coverage is 0%, and the description covers only one of two parameters, leaving partial ambiguity.
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 tests one URL parameter for server-side request forgery using SSRFmap, and explicitly narrows it to the reachability module, distinguishing it from more dangerous SSRFmap modules. The verb 'test' and resource 'URL parameter' are specific, and the scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance by contrasting this tool with SSRFmap modules that exfiltrate or pivot, noting they are not on the allowlist. It advises 'Confirm reachability here, then prove impact by hand with poc_record()', thereby telling when to use this tool (for reachability only) and what to do after.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Detect server-side template injection with SSTImap.
injection_points selects where to inject: Q(uery), B(ody), H(eaders),
C(ookies) — query only by default, because headers and cookies multiply the
request count and are usually not the reported sink. engine optionally
narrows to one template engine once http_probe has told you the stack
(jinja2, twig, freemarker, velocity, smarty, …).
A hit here is arithmetic evaluated in a template — {{7*7}} returning
49 — and nothing else. SSTImap's shell, eval and file-transfer flags are
denied, so the tool cannot be talked into demonstrating RCE. Establishing
that a template engine evaluates attacker input is the finding; proving code
execution beyond that is a decision a human makes, in writing.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ||
| engine | No | ||
| target | Yes | ||
| injection_points | No | Q |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations (destructiveHint: true, readOnlyHint: false) by disclosing that it requires human approval, that it cannot be tricked into RCE, and that its scope is limited to detection, not exploitation. It explicitly defines the finding criteria and leaves proof of RCE to a human decision. This is exemplary transparency that exceeds what the annotations alone convey.
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 structured effectively: it opens with the exploit/human-approval warning, then covers parameters, then defines the finding and limitations. Every sentence adds value, and the length is justified by the tool's complexity. It is front-loaded with the most important safety constraint. Slightly more brevity could be achieved, but the organization is strong.
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 exploit tool, the description covers purpose, parameters, limitations, and expected behavior. It implicitly suggests a sequence (use http_probe first to identify the stack) but does not explicitly state that prerequisite. The output schema exists, so not describing return values is acceptable. The description is largely complete, but the explicit prerequisite of http_probe could be stated to make it fully self-contained.
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 0%, so the description must compensate. It explains injection_points (Q,B,H,C) and engine (optional, narrows to a specific engine) in detail, and target is self-evident. However, the 'level' parameter is not explained at all; its meaning (likely probe intensity) is left to inference. While the most critical parameters are covered, the omission of level prevents a higher 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's purpose: 'Detect server-side template injection with SSTImap.' It uses a specific verb (Detect) and resource (server-side template injection), and distinguishes itself from siblings like cmdi_probe and nosqli_probe by naming the specific vulnerability class. It also defines what constitutes a hit (arithmetic evaluated in a template, e.g., {{7*7}} returning 49), removing ambiguity.
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 clear guidance on when to use the tool: it explains injection_points selection (Q,B,H,C) and defaults, notes that engine narrowing should follow http_probe results, and explicitly states that headers and cookies are usually not the reported sink. It also clarifies what the tool cannot do (denied shell, eval, file-transfer flags), setting boundaries. However, it does not explicitly compare to sibling tools or state 'use this instead of X', so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Delegate deep application exploitation to Strix, then ingest its results.
Disabled by default. Requires exploitation to be permitted by the engagement and explicit human approval per call.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| instruction | No | Find and validate exploitable vulnerabilities. Prove each with a minimal PoC. | |
| max_iterations | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveness; description adds approval requirements and states it performs exploitation, but does not detail side effects or outcome storage beyond 'ingest results.'
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?
Brief, focused, and well-structured with a clear warning prefix and concise description.
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?
While output schema exists, the description lacks information about execution flow (async/sync), approval interaction, or result format, making it incomplete for complex 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 has no descriptions; the description does not explain target, max_iterations, or how instruction is used, leaving the semantics unclear.
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's function (delegate deep exploitation to Strix and ingest results) and explicitly flags it as an exploit requiring approval, distinguishing it from read-only scanning tools.
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?
Provides a condition for use (requires permitted exploitation and human approval) but does not explicitly compare with similar exploit tools (e.g., exploit_chain) or indicate when to prefer this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enumerate subdomains from every installed passive source and merge them.
Runs whichever of subfinder / assetfinder / findomain / amass / theHarvester are present, in parallel, and returns the deduplicated union filtered through the engagement scope. Installing more sources widens coverage with no code change — the tool set is discovered, not hardcoded.
include_amass defaults off. On a real engagement amass ran the full 15
minutes and returned zero subdomains — its productive sources want API
keys — while subfinder and assetfinder found 322 and 301. It also spawns an
amass engine child that calls setsid itself, so it escapes the
process-group kill on timeout and keeps running, unthrottled, after the
engagement believes the tool stopped. Turn it on when amass is configured
with datasource credentials; leave it off otherwise.
thorough adds slower sources (theHarvester, amass with more providers). Prefer bbot_scan when BBOT is available: it covers more sources than all of these combined.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| thorough | No | ||
| include_amass | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint annotation by disclosing critical runtime behaviors: amass can run 15 minutes with zero results without API keys, it spawns an amass engine child that escapes the process-group kill and keeps running after timeout, and the tool set is discovered dynamically. These are important operational traits the agent must know.
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?
Though slightly long, every sentence earns its place. The core purpose is front-loaded, then the source-discovery mechanism, the amass caveat, and the alternative recommendation. It is dense but not verbose, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers tool behavior, performance characteristics (amass runtime), alternatives (bbot_scan), and parameter rationale. Since an output schema exists, the absence of return-format details is acceptable. The description is complete for an enumeration tool of this complexity.
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?
With 0% schema description coverage, the description must explain parameters. It fully explains include_amass (default off, why, when to enable) and thorough (adds slower sources like theHarvester and amass with more providers). target is self-evident from the tool name and description. This compensates well for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the exact operation: 'Enumerate subdomains from every installed passive source and merge them.' It names specific tools (subfinder, assetfinder, findomain, amass, theHarvester) and clearly distinguishes itself from bbot_scan, which is called out as a more comprehensive alternative. The purpose is unambiguous and differentiated.
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 recommends using bbot_scan when available ('Prefer bbot_scan when BBOT is available'). It also provides conditions for enabling include_amass (only when amass has datasource credentials) and thorough (adds slower sources). This is clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Verify a human-executed takeover PoC is live and attach it to the finding.
Fetches the proof URL, checks the proof content is actually served from the target host, and only then promotes the finding to confirmed. This is the single place a takeover can become 'confirmed'.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| target | Yes | ||
| proof_url | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Clearly discloses side effects: fetches the proof URL, checks the target host, and promotes the finding to confirmed. Matches annotations readOnlyHint=false and destructiveHint=true by indicating a state-changing action.
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?
Concise and front-loaded with the exploit/approval flag, followed by a clear action and condition. No unnecessary detail.
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 the precondition (human approval), the action, and the conditional side effect. Does not describe return values, but that is not critical for tool 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?
Description clarifies proof_url and target host in prose, but the notes parameter is not explained and there are no formal parameter descriptions 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?
States the specific action: verify a live takeover PoC and promote the finding to confirmed. Clearly distinguishes from sibling tools by noting this is the single place a takeover can become 'confirmed'.
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?
Indicates it requires human approval and is the sole path to confirmed status, but does not explicitly contrast with sibling tools like takeover_verify or takeover_detect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Screen hosts for takeover candidates with subzy and dnsReaper.
Output is a candidate list, never findings. Run takeover_verify on each hit before treating any of them as real.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses that the tool is aggressive, requires human approval, uses specific tools (subzy and dnsReaper), and outputs only candidates, never findings. This adds meaningful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the critical aggressive/human-approval warning, followed by a clear purpose statement and output clarification. Every word earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action, the output nature (candidate list), and the necessary next step (takeover_verify), along with the approval requirement. The output schema presumably documents the return format. However, the target parameter is left undefined, which is a notable gap for a one-parameter 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?
The schema has a single parameter 'target' with no description (0% schema description coverage). The description does not mention 'target' at all, leaving the agent without any guidance on what format or value to provide (host, domain, IP, file path). The description fails to compensate for the missing schema information.
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 a specific verb and resource: 'Screen hosts for takeover candidates with subzy and dnsReaper.' It distinguishes itself from sibling tools like takeover_verify and takeover_confirm by explicitly noting that output is a candidate list, never findings, and by directing verification to a specific sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: as an aggressive screening step that requires human approval. It explicitly instructs to run takeover_verify on each hit before treating results as real, giving a concrete follow-up action. It does not list alternative screening tools but the workflow is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Produce the minimal, responsible PoC steps for a verified takeover.
Cordon does not register resources at third-party providers on your behalf. This returns the exact steps, including a unique proof path tied to your researcher handle, so the proof is unambiguous and the impact stops at 'I could have'.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits beyond annotations: it does not register third-party resources, returns exact steps tied to a researcher handle, and limits impact to 'I could have' — all beyond the readOnly/openWorld hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences. The first states the primary purpose, the second clarifies safety and output behavior. No redundant words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description omits any explanation of the 'target' parameter and does not explicitly connect it to sibling verification tools. It covers the output shape but leaves the input semantics unclear.
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 schema has 0% description coverage for the single 'target' parameter, and the description does not mention it at all. Since coverage is below 50%, the description must compensate, but it provides no meaning for 'target'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Produce'), a clear resource ('PoC steps'), and the condition ('for a verified takeover'). It also contrasts with sibling takeover tools by focusing on generating steps rather than detecting, verifying, or confirming a takeover.
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?
Implicitly indicates when to use (after verification, for responsible minimal proof) and mentions a safety guideline ('does not register resources'), but does not explicitly name alternatives like takeover_verify or takeover_confirm.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a takeover candidate: CNAME chain + live response + fingerprint.
All three must agree before the host is recorded as a verified candidate. A verified candidate is filed as 'needs manual review' — confirming it requires actually claiming the resource, which is takeover_poc_plan followed by takeover_confirm.
NS and MX delegations are graded higher: those hand over the zone or the mail.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains what happens after verification: the host is filed as 'needs manual review' and requires a separate confirmation process. It does not enumerate edge cases or failure modes, but the readOnlyHint and destructiveHint annotations cover the safety profile.
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 concise and well-structured, using short lines to convey the verification criteria, follow-up actions, and delegation grading. Every sentence adds meaningful information without fluff 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?
The description covers the verification criteria, the resulting status, and the next steps in the takeover workflow. Since an output schema exists, omitting return-value details is acceptable; still, it does not mention possible verification failures or non-agreement outcomes explicitly.
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 only parameter is 'target' with no schema description, and the description provides limited direct explanation of acceptable formats. However, the context of CNAME chains and live responses implies target is a hostname or domain, which is some compensation for the lack of schema details.
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's purpose: to verify a takeover candidate by checking CNAME chain, live response, and fingerprint. It also differentiates verification from actual confirmation, explicitly pointing to takeover_poc_plan and takeover_confirm as subsequent steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit criteria for use: all three checks must agree before recording the host as verified, and NS/MX delegations are prioritized. It does not explicitly say 'use this after takeover_detect' but the workflow context is clear from the sibling tools and the confirmation flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What to do next: pending tasks whose dependencies are met, highest priority first. Each carries the discovery that created it. Call this after every phase rather than re-deriving the plan from scratch.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes no side effects, and the description reinforces a read-only query of pending tasks. It adds useful context about ordering and dependency filtering, though it does not detail any response shape or limits.
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 concise, front-loaded with the main purpose, and contains no filler. Three short sentences convey the behavior and usage guidance efficiently.
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 parameter set and the presence of an output schema, the description provides enough context to understand the tool's role and invocation timing. It does not need to describe return values because an output schema is available, but a brief note on limit behavior would make it fully 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?
The only parameter, 'limit', is not described in the tool description and schema coverage is 0%. While the parameter name is intuitive, the description does not compensate by explaining how the limit affects the returned task list.
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 describes what the tool does: returns pending tasks with satisfied dependencies, ordered by priority, each carrying the discovery that created it. It is distinct from taskgraph_update and taskgraph_view by focusing on 'next' actionable items.
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 instructs to call it after every phase rather than re-deriving the plan from scratch, giving a clear condition for when to use it. This effectively differentiates it from a full plan-rebuilding workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a task done, failed, blocked, or skipped after acting on it.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| state | Yes | ||
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=false already marks this as a write operation. The description adds value by specifying the allowed state values and implying a precondition ('after acting on it'), which clarifies the behavioral contract beyond the simple write flag.
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, compact sentence with no filler or redundant information. It efficiently communicates the purpose and key constraint without verbosity.
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 state-update tool, the description covers its main purpose, the acceptable state transitions, and a usage hint. It does not mention output or side effects, but these are not critical for such a basic operation. Overall, it is sufficiently complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions for its three parameters. The description indirectly hints that 'state' accepts the listed values, but task_id and note are not explained at all. The description only partially compensates for the lack of schema-level parameter documentation.
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 a specific action: marking a task with one of four explicit states (done, failed, blocked, skipped). This verb+resource+outcome combination distinguishes it from sibling tools like taskgraph_view and taskgraph_next.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'after acting on it' provides a clear timing/usage guideline, indicating the tool should be called after the corresponding action has been performed. It does not explicitly list alternatives or when not to use, but the primary trigger is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render the task graph as Mermaid, showing how discoveries drove the work.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description is consistent. It adds value by specifying the output format (Mermaid) and the graph's semantic content (discoveries driving work), which are not in the annotations. This is helpful context for a read-only rendering 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?
A single sentence that is direct and front-loaded with the primary action ('Render the task graph as Mermaid') and immediately provides the key content ('showing how discoveries drove the work'). No wasted words.
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 (no parameters, read-only, output schema present), the description is fully adequate. It states what it does, the output format, and the semantic content. An agent has enough information to call it correctly without additional guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers parameter documentation (100% coverage). The description does not need to add parameter semantics. Baseline of 4 applies for no-parameter tools.
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 'Render' with a clear resource 'task graph' and specifies the output format 'Mermaid'. It also adds context about content ('how discoveries drove the work'), which differentiates it from siblings like taskgraph_next (likely next steps) and taskgraph_update (modifying the graph).
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. It does not mention scenarios where it is appropriate, nor does it reference any sibling tools for comparison. An agent would have to infer usage from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query the PayloadsAllTheThings technique index for how to test a bug class.
The counterpart to wstg_lookup: WSTG says what to check, this says how.
Each record names the Cordon tools that test the class, the vetted payload
lists, and the gf pattern packs that correspond to it. Retrieval, not
automation — nothing here fires anything, and it costs no budget.
Five ways in, most specific first:
class_name — one technique in full ("sql-injection", "open-redirect")
tool — every technique a given Cordon tool covers ("sqli_validate")
technologies— comma-separated stack from http_probe ("Rails,MongoDB,GraphQL")
query — free text ("jwt forgery", "deserialization")
phase — everything in a phase (input_validation, authentication …)
| Name | Required | Description | Default |
|---|---|---|---|
| tool | No | ||
| phase | No | ||
| query | No | ||
| class_name | No | ||
| technologies | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only and non-destructive; description reinforces this by stating 'Retrieval, not automation' and 'nothing here fires anything'. It adds value by explaining the tool has no side effects and no cost.
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 compact and well-structured: a one-sentence purpose, a useful comparison, and a scannable bullet list of parameters. No filler or redundant explanation.
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?
Provides enough context about what records contain (tool names, payload lists, gf pattern packs) and how to query, though it does not describe the output shape beyond that; the output schema is not shown in the description.
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 schema provides only nullable strings, but the description fully maps each parameter to a lookup mode and gives example values, effectively compensating for the schema's lack of descriptions.
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 it queries the PayloadsAllTheThings technique index to learn how to test a bug class, and distinguishes itself as the 'how' counterpart to wstg_lookup. Specific verbs and resource identify the tool's role among many sibling scanners.
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 frames usage via 'WSTG says what to check, this says how' and enumerates five lookup modes with concrete examples. This gives an agent clear conditions for when to prefer technique_lookup over related lookup tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit a host's TLS configuration: protocols, ciphers, certificate, headers.
Passive. Every check run here is a standard TLS handshake plus one HTTP GET —
the same traffic any browser produces. testssl's vulnerability battery
(-U: Heartbleed, CCS injection, Ticketbleed, ROBOT, DROWN) is not run
and is denied at the sanitizer: those send malformed or exploit-shaped
handshakes, and Heartbleed in particular reads server memory. Reaching them
would make the "passive" label a lie. Use the exploit-phase validators, with
approval, if a TLS vulnerability needs proving.
| Name | Required | Description | Default |
|---|---|---|---|
| port | No | ||
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint=true, destructiveHint=false) indicate safety, but the description enriches this by detailing the exact network traffic produced (standard TLS handshake + one HTTP GET) and explicitly stating that vulnerability tests are not run due to sanitizer denial. This adds context beyond the annotations, making the tool's behavior transparent.
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 concise and well-structured: it opens with the primary purpose, then provides a brief 'Passive.' note, and follows with a clear explanation of what is not run and why, plus a pointer to alternatives. No redundant or irrelevant information is present. It is front-loaded with the key use case.
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 and the existence of an output schema (noted in context signals), the description is complete for an agent to decide when to use it. It covers the primary action, safety profile, exclusions, and points to alternatives. It does not need to detail return values or internal mechanics, as those are handled by the schema or are not necessary for 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 has two parameters (target, port) but zero description coverage. The description does not explain these parameters directly. While the parameter names and tool context imply target is a host and port is the TLS port (with default 443), the lack of explicit explanation means the agent must infer semantics. Since schema coverage is 0%, the description should compensate, but it does not, leaving a gap.
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's function: 'Audit a host's TLS configuration: protocols, ciphers, certificate, headers.' It specifies the resource (host's TLS configuration) and the verb (audit), and lists the specific aspects covered. It also distinguishes itself from siblings by emphasizing its passive nature, which separates it from active vulnerability scanners in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Passive. Every check run here is a standard TLS handshake plus one HTTP GET — the same traffic any browser produces.' It also explains what it does not do: testssl's vulnerability battery is not run and is denied, and it directs to 'exploit-phase validators' for vulnerability proving. This provides clear usage boundaries and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read TLS certificates and pull subject-alternative names.
SANs frequently reveal internal hostnames and sibling domains. They are scope-filtered before being stored, since one certificate often covers hosts belonging to several organizations.
tlsx opens TLS connections to the target, so its concurrency and inter- connection delay are pinned to the engagement. Its default concurrency is 300.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool opens TLS connections, has a default concurrency of 300, and scope-filters results before storage. This goes beyond the basic readOnly annotation, though it does not fully clarify whether storing results conflicts with readOnlyHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences convey purpose, behavior, and operational constraints without redundancy. The structure is straightforward and easy to scan.
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?
Provides sufficient context for a simple one-parameter tool: what it returns (SANs), that results are scope-filtered, and that network connections are used. The absence of output format details is acceptable given the output schema is noted as present.
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 only parameter 'target' is a plain string with no schema description. The description mentions 'target' but does not specify expected format (e.g., hostname, IP, URL) or any constraints.
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 action ('Read TLS certificates and pull subject-alternative names') and the resource (TLS certificates). It distinguishes the tool from related siblings like tls_audit by focusing on SAN extraction.
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 such as tls_audit, http_probe, or port_scan. The description mentions concurrency and scope-filtering but does not explain situations that favor this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the fabricated canary findings triage would mix into a batch.
Useful for confirming the decoys look plausible enough to be a real test. They
always live on a .invalid host, which by RFC 2606 can never resolve.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly and destructive hints. The description adds meaningful context: findings always live on a .invalid host (RFC 2606) and are fabricated, which explains their nature. This goes beyond annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core action and add a valuable detail about .invalid hosts. No wasted words.
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?
The tool is simple with one optional parameter and an output schema, but the missing parameter explanation leaves a gap. Since the output schema covers return values, the description should at least explain the count parameter; it does not.
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 only parameter 'count' has no description in the schema (0% coverage) and the description does not mention it at all. An agent cannot infer what count controls without external knowledge. The description fails to compensate for the schema gap.
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 shows fabricated canary findings that triage would mix into a batch, distinguishing it from sibling tools like triage_findings which presumably show real findings. The purpose of confirming decoy plausibility is explicit.
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 gives a use case ('confirming the decoys look plausible') but does not explicitly state when to prefer this over alternatives, nor does it mention exclusions. The usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run AI triage over candidate findings to cut false positives.
Fabricated canary findings are mixed into the batch; a pass that "confirms" one has its verdicts weighted down, and the measurement is reported.
Triage never confirms anything. Escalated findings go to validate_findings.
| Name | Required | Description | Default |
|---|---|---|---|
| taskflow | No | ||
| max_findings | No | ||
| min_severity | No | info |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description adds critical behavioral context: 'Triage never confirms anything' and explains how canary findings affect verdicts (weighted down). This exceeds what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose and then adds relevant behavioral details. It is somewhat verbose with the canary explanation but remains focused and avoids unrelated information. Structure is clear, though minor redundancy exists.
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?
The description covers the core behavior and output expectations (e.g., 'the measurement is reported'), and the existing output schema (though not shown) likely provides structural details. It does not address edge cases or error handling, but for a triage tool, the description is sufficiently 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 description coverage is 0%, and the description does not mention max_findings or min_severity at all. The description completely fails to compensate for the lack of parameter explanations, leaving the agent to guess their 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?
The description clearly states the tool's function: 'Run AI triage over candidate findings to cut false positives.' It also distinguishes itself from sibling tools by mentioning escalation to validate_findings, making its role specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage guidance by stating that escalated findings go to validate_findings, implying triage is a precursor to validation. It also notes the intentional inclusion of canary findings, which informs expected behavior. However, it does not explicitly list when to use vs. not use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available triage taskflows and their steps.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe, read-only operation, and the description's 'List' wording is consistent with that. The description adds that the tool returns taskflows and their steps, but does not disclose any additional behavioral details such as output format or potential size of results.
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, focused sentence with no redundant words. It front-loads the action and clearly states the object of the listing.
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 parameterless listing tool, the description is sufficient to understand what the tool does. It could optionally mention whether the output is a list of taskflow names with nested step details, but this is a minor omission given the straightforward nature of the 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?
The tool has zero parameters and an empty schema, so the baseline is high. The description provides enough context that no parameters are needed; with no inputs to document, there is little room for parameter-level explanation.
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 clear verb ('List') and identifies the specific resource ('available triage taskflows and their steps'), which unambiguously states the tool's purpose. It is also distinct enough from sibling triage tools such as triage_findings and triage_canary_preview.
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 does not explicitly say when to use this tool versus alternatives like triage_findings or validate_findings. While the purpose is clear, there is no guidance on when to choose this taskflow-listing tool over other triage-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect file-upload surfaces (multipart forms, file inputs, upload paths).
Fetches the discovered pages read-only and reports which URLs carry a file input, a multipart form, or an upload-shaped action/parameter. Nothing is uploaded — this is detection only, and every entry is a lead for a human or an approved validator, not a finding.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| max_urls | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description explicitly states that no uploads are performed and clarifies the output nature as leads, not findings. This provides transparency about the tool's side effects and result interpretation.
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 concise and front-loaded with the core action, but it includes some redundancy (e.g., repeating the detection-only message). Still, it is well-structured and avoids unnecessary detail.
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?
The description provides context about the output (leads for human/approved validator) and indicates the tool is passive, which helps the agent understand its role. However, it lacks details about the output schema and parameter semantics, which would enhance 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?
The input schema defines target (required string) and max_urls (integer with default), but the description does not explain their meaning or format. The description references 'discovered pages' but does not clarify what target should contain, leaving ambiguity for the agent.
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 detects file-upload surfaces and specifies the method (fetch pages read-only) and the output (URLs with upload indicators). It distinguishes its scope by noting that nothing is uploaded, making it a passive detection tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (for reconnaissance to find upload points) and provides guidance on how to treat results (as leads for human or approved validator, not findings). It also clarifies that it is detection-only, so it shouldn't be used for active exploitation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Prove candidate findings with minimal PoCs. Validators run in parallel.
Only a finding whose validator produced a reproducible PoC becomes 'confirmed'. Everything else is downgraded to 'needs manual review' with the reason recorded. This is the only automatic route to a confirmed finding.
| Name | Required | Description | Default |
|---|---|---|---|
| finding_ids | No | ||
| max_findings | No | ||
| min_severity | No | medium |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals important behavior: validator runs in parallel, only reproducible PoCs lead to confirmation, and non-confirmed findings are downgraded with reasons recorded. It also signals approval requirements and state changes, which aligns with the destructiveHint annotation.
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 relatively concise, fitting in two sentences, and front-loads the core action. The bracketed 'EXPLOIT — requires human approval' is slightly redundant with the later mention, but it doesn't bloat the text. Overall it is well-structured and scannable.
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?
While the outcome behavior is described, key context is missing: the meaning and use of the input parameters, how findings are selected, what constitutes a 'minimal PoC', and any preconditions. The description covers the core process but leaves out essential operational details, making it insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description provides no information about the three parameters (finding_ids, max_findings, min_severity). An agent has no guidance on how to set these or what values are expected. This is a severe gap.
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's function: 'Prove candidate findings with minimal PoCs' and specifies the exact outcome ('confirmed' or 'downgraded to needs manual review'). It also distinguishes itself from siblings by noting it is the only automatic route to a confirmed finding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly mentions the tool is the only automatic route to confirmed findings, giving a strong usage signal. It also notes human approval is required, which sets expectations for when it should be invoked. However, it doesn't contrast with alternatives like triage_findings beyond that single statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ordered WAF-bypass payloads for (vendor, vuln_class), basic → advanced.
vendor is a wafw00f display name ("Cloudflare", "Amazon Web Services
(AWS) WAF") or a canonical key ("cloudflare", "aws_waf", "modsecurity").
vuln_class is one of xss, sqli, cmdi, ssti, ssrf,
path_traversal. level filters to basic / intermediate /
advanced / all.
Read-only: returns text payloads tagged with technique + level, nothing is sent. Payloads are the data the exploit chain feeds its validators when a base pass was clean; calling this tool does not fire anything at a target.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | all | |
| vendor | Yes | ||
| vuln_class | No | xss | |
| max_payloads | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the read-only behavior: 'Read-only: returns text payloads tagged with technique + level, nothing is sent.' and reinforces 'calling this tool does not fire anything at a target.' This goes beyond the annotations by detailing exactly what the tool does and does not do, ensuring users understand its non-intrusive nature.
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 compact and well-organized: it starts with the core purpose, then explains parameters, and ends with behavioral clarification. Each sentence adds value without redundancy, making it easy to scan and understand.
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?
The description gives enough context for typical use: it explains the tool's role in the exploit chain, the input parameters, and the non-sending behavior. It does not detail the output structure (despite an output schema being present) or mention any potential errors or pagination, but for a payload-returning tool this is likely sufficient. The context is adequate but not exhaustive.
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 description explains three of the four parameters: vendor (with examples of display names and canonical keys), vuln_class (listing valid values), and level (describing the filter options). However, max_payloads is not mentioned, so its semantics are only inferred from its name and default value in the schema. Overall, most parameters are well explained.
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's purpose: 'Ordered WAF-bypass payloads for (vendor, vuln_class), basic → advanced.' This is specific and unambiguous, and it also explains the ordering logic and the parameters involved.
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 usage context by explaining when this tool is appropriate: 'Payloads are the *data* the exploit chain feeds its validators when a base pass was clean.' It also clarifies that calling this tool does not fire anything at a target, which helps distinguish it from active scanning tools. However, it does not explicitly compare with sibling tools like waf_detect or fingerprint_waf, so guidance is slightly indirect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify the WAF or protection layer in front of a host.
Knowing the WAF changes what is worth trying and what will simply be blocked.
The vendor names this reports are what the exploit chain's bypass pass
consumes: waf_bypass looks up the vendor's payload set and the validators
re-fire with it only when a base pass came back clean — still behind the
exploit gate. Identifying the vendor stays passive; sending bypass payloads
is exploitation and goes through the same approvals as any other.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reinforces the readOnly and destructive false annotations by stating that identifying the vendor stays passive and that sending bypass payloads requires separate approvals. This adds useful context beyond the annotations alone.
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 first sentence is clear and front-loaded, but the second paragraph is verbose and contains awkward phrasing such as 'The vendor names this reports are what the exploit chain's bypass pass consumes.' The core message could be stated more concisely.
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?
The description mentions that the report contains vendor names and that bypass behavior is separate, but it does not fully describe the output schema beyond that. Given the output schema exists but is not detailed here, the description provides only partial context for what the agent should expect.
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 only parameter, target, has no schema description and the description merely implies it is a host. It does not clarify whether target should be a domain, IP, URL, or include a scheme/port, leaving the agent to guess the expected format.
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 first sentence clearly states the tool's purpose: identify the WAF or protection layer in front of a host. However, a sibling tool named fingerprint_waf exists, and the description does not explicitly differentiate waf_detect from it, which creates some ambiguity.
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 explains why knowing the WAF matters and notes that bypass payloads are a separate, approval-gated activity. It does not, however, give explicit guidance on when to choose waf_detect over fingerprint_waf or other reconnaissance tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supported WAF vendors with the classes each has bypass payloads for.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint and non-destructive behavior. The description adds a slight context by indicating it lists supported vendors and payload classes, but it does not elaborate on any potential side effects (though none exist). It is consistent with annotations, but adds minimal extra transparency.
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 with no unnecessary words. It efficiently communicates the tool's purpose without any fluff 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 tool's simplicity (no parameters, no complex behavior), the description is complete for an agent to understand what it does. An output schema exists, so the description need not explain return values. No additional context is required for this straightforward listing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters and the schema coverage is 100% (empty schema fully covers the tool). Per the rubric, with high schema coverage, the baseline score is 3. The description does not need to explain parameters since there are none, and it does not add any parameter-related information.
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's function: 'List supported WAF vendors with the classes each has bypass payloads for.' It uses the specific verb 'List', identifies the resource (WAF vendors), and specifies the detail about bypass payload classes, distinguishing it from sibling tools like waf_bypass or fingerprint_waf.
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 gives no explicit guidance on when to use this tool versus alternatives. It does not mention, for example, that this is for reconnaissance/inventory and not for actual bypassing, which is covered by waf_bypass. No usage context is provided beyond the basic function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[AGGRESSIVE — requires human approval] Crawl and attack a web application with wapiti.
Aggressive, and gated. Even profile='safe' crawls the whole application;
profile='injection' submits SQLi, XSS, command-injection, SSRF, CRLF and
XXE payloads to every parameter found. Nothing about that is observational.
Bounds, all enforced server-side: --max-scan-time caps the run,
--max-attack-time caps each module, crawl depth and links-per-page are
capped, and the process timeout sits above all of them. max_minutes is
clamped to MAX_SCAN_MINUTES (30).
wapiti exposes no requests-per-second control — the closest it offers is
--scan-force, which is set from scope.rules.max_rps here. That is an
approximation and it is reported as one: a program with a strict published
rate limit is a reason to prefer nuclei with -rl.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | ||
| target | Yes | ||
| profile | No | safe | |
| max_minutes | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by explicitly warning that the tool is aggressive, gated, and not observational. It details payload types, crawling behavior, and enforced limits, making side effects and operational constraints transparent.
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 information-dense and each paragraph adds useful details, but the formatting is slightly repetitive and awkward with repeated 'Aggressive' and 'Bounds' emphasis. Still, it remains focused and purposeful.
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?
The description includes required approval context, operational bounds, rate-limit caveats, and alternative-tool guidance. Since an output schema exists, return-value details are not necessary, and the input calling context is fully covered.
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 schema has no field descriptions, but the tool description compensates by explaining target, profile values, max_minutes clamping, and crawl depth caps. Target and depth are somewhat implicit, but still sufficiently covered.
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's function: 'Crawl and attack a web application with wapiti.' This distinguishes it from sibling scanning tools by naming the specific engine (wapiti) and its active attack behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use this tool versus alternatives, such as preferring nuclei with -rl for strict rate limits. It also explains profile options and server-side bounds, giving clear context for safe usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Detect open redirect, CRLF, LFI, XXE or HPP in one parameter.
target is the full URL carrying the parameter to test (one parameter —
& is refused project-wide). parameter names it. bug_class is one
of open-redirect, crlf, lfi, xxe, hpp.
regex_bypass expands the class's payload set with generated WAF-regex
bypass variants (every mode x every encoding, bounded at 500): a WAF regex
that blocks the textbook ../ or <script> often lets the same byte
through when written as %2e%2e/ or split by a metachar replacement. It
multiplies the request count and is strictly a second pass — run the plain
probe first and reach for this only when a parameter reflects but nothing
fires.
Every result is a CANDIDATE: the class signature must appear in the injected response and not in the baseline request. Nothing is confirmed here.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| bug_class | No | open-redirect | |
| parameter | Yes | ||
| regex_bypass | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the original annotations by explaining that it sends injected payloads, compares responses to baseline, and returns only candidates (not confirmations). It also discloses that regex_bypass multiplies request count and is strictly a second pass. The destructiveHint annotation is reinforced by the 'requires human approval' note, providing a coherent picture of the tool's behavior without contradiction.
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 moderately long but well-structured: the purpose is front-loaded, followed by parameter clarifications, then regex_bypass guidance, then result interpretation. Each sentence serves a distinct function, and there is no redundant or filler content. The formatting with line breaks improves readability.
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 (4 parameters, enums, no output schema provided), the description covers the essential context: what it detects, how the detection works (signature in response vs baseline), when to use regex_bypass, and the candidate-only nature. It does not mention authentication, rate limits, or side effects beyond injection, but the 'requires human approval' and destructiveHint annotation already cover safety. The absence of explicit output schema is acceptable as the description explains result semantics.
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 schema provides only types and an enum, with no per-parameter descriptions. The description fills this gap completely: it explains target as the full URL carrying the parameter, parameter as the name, bug_class as one of five enumerated values, and regex_bypass as a boolean that expands payloads with WAF bypass variants (bounded at 500). This gives the agent all necessary semantic understanding.
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's action (detect) and resource (injection types in one parameter), listing specific bug classes: open redirect, CRLF, LFI, XXE, HPP. This distinguishes it from sibling probes like cmdi_probe, sqli_validate, or xss_validate, which target other vulnerability classes. The 'requires human approval' note adds important context without obscuring the purpose.
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 actionable usage guidance: 'run the plain probe first and reach for this only when a parameter reflects but nothing fires' for the regex_bypass option. It also defines when the tool is appropriate (detecting the listed injection types) and notes the candidate-only nature of results. However, it does not explicitly compare to sibling injection probes or state when not to use this tool in favor of others, though the purpose listing implicitly covers this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a WebSocket handshake and report whether the server validates Origin.
Pass the https:// (or bare host) form of the endpoint, not wss://:
the scope engine cannot parse a ws/wss URL and fails closed on one,
so a wss:// target is refused before this ever runs. The upgrade to
wss:// happens here, after the scope check has had its say.
Passive: one upgrade request, no frames sent, connection closed immediately.
-u inhibits the send direction and -1 stops after a single message,
so nothing this tool does can be mistaken for traffic.
A handshake that succeeds with a foreign Origin is a candidate for
cross-site WebSocket hijacking. It only becomes a finding when the socket
also carries authentication that the browser would attach automatically —
which this tool cannot and does not test.
| Name | Required | Description | Default |
|---|---|---|---|
| origin | No | ||
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by stating it sends no frames and closes the connection immediately. It adds the limitation about not testing authentication, which is beyond annotations. No contradiction.
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 moderately long but well-structured: purpose first, then usage constraints, then behavior, then interpretation. Each sentence adds value, and the critical usage note about URL format is front-loaded. Slightly verbose but not padded.
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 output schema exists, return format is covered. The description explains the tool's purpose, usage constraints, passivity, and how to interpret results. It does not mention potential error cases or rate limits, but for a simple probe it is reasonably 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 0%, so the description must compensate. It explains the target format (https://) and implies the origin parameter is the Origin header to send, but does not explicitly define the origin parameter's semantics or default behavior. It adds some value but could be more explicit about the origin parameter's role and acceptable values.
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 (open, report) and resource (WebSocket handshake, Origin validation) in the first sentence. It is specific and distinct from the many sibling tools, which focus on other scan types. No ambiguity.
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?
Provides explicit guidance on URL format (https:// not wss://), explains the scope engine's behavior, and notes the passive nature. It also clarifies that the tool does not test authentication, so it cannot confirm a finding alone. However, it does not name alternative tools for similar checks, so it lacks explicit 'use X instead' guidance, though the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WHOIS registration data for a domain: registrar, org, dates, nameservers.
Useful for confirming an asset actually belongs to the program before you spend requests on it.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate read-only, open-world, and non-destructive behavior. The description adds that it 'spends requests' (network usage) and is useful for ownership confirmation, but doesn't reveal additional traits like rate limits or failure modes. Slight extra context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first describes what the tool does, the second explains its practical use. Information is succinct, focused, and well-ordered, 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?
For a simple read-only lookup with a single parameter, the description provides enough context for an agent to understand the purpose and when to use it. It doesn't describe output format, but that's not necessary for a tool with no output schema and a clear function.
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 description mentions 'for a domain,' giving a strong hint that the 'target' parameter expects a domain name. However, it doesn't explicitly clarify whether IPs or URLs are accepted, and there is no schema-level description. The hint is useful but not fully unambiguous.
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's function: retrieving WHOIS registration data for a domain, listing specific fields (registrar, org, dates, nameservers). This is distinct from sibling tools like DNS resolution or subdomain 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?
It provides a concrete use case: confirming asset ownership before spending requests, which guides the agent on when to invoke this tool. It doesn't explicitly mention when not to use it, but the guidance is actionable and relevant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query the OWASP Web Security Testing Guide for what to test next.
Four ways in, most specific first:
test_id — one test in full ("WSTG-INPV-05")
technologies — comma-separated stack from http_probe ("Java,Tomcat,OAuth")
query — free text ("session fixation", "file upload")
phase — everything in a phase (recon, authentication, input_validation …)
Retrieval, not automation. A WSTG test says what to check and why; whether it applies to this target is a judgement no detector makes for you. Touches nothing and costs no budget.
| Name | Required | Description | Default |
|---|---|---|---|
| phase | No | ||
| query | No | ||
| test_id | No | ||
| technologies | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, but the description adds meaningful context: 'Retrieval, not automation' and 'Touches nothing and costs no budget' clarify side effects and budget implications. It also states the tool does not judge applicability, which goes beyond annotations and helps set agent expectations.
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 well-structured with a clear opening sentence, four bullet points, and a closing behavioral note. It is not overly verbose, though the examples and extra behavioral sentences add length. It front-loads the purpose and keeps the most important info early. A tight, efficient text.
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 moderate complexity (4 optional params, no required) and the presence of an output schema, the description is complete: it explains all inputs, the retrieval-only nature, and the lack of side effects. It does not describe the exact return structure, but the output schema exists and the description hints at what a test contains ('what to check and why'). Enough for an agent to call 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 0%, so the description must compensate for all parameters. It does this exceptionally: each of the four parameters is explained with a clear purpose, example values, and a precedence order ('most specific first'). This is far beyond what the schema provides and fully disambiguates parameter usage.
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 the exact action ('Query the OWASP Web Security Testing Guide') and the purpose ('what to test next'), with four explicit query modes and examples. It is specific and distinct from siblings like 'technique_lookup' or 'research_guidance' by naming the exact resource (WSTG) and its retrieval-only 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?
The description gives clear 'how to use' guidance (four ways, most specific first) but never mentions alternatives or when not to use it. There is no explicit comparison to siblings like 'technique_lookup' or 'research_guidance', leaving the choice to the agent's inference. It clearly implies the use case (WSTG lookup) but lacks exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[EXPLOIT — requires human approval] Confirm reflected XSS on a URL with dalfox.
payload_list optionally names a tier B list from the vetted payload store
to hand dalfox via --custom-payload. Leave it unset first: dalfox's
built-in payloads are context-aware and prove most reflected XSS on their own.
Reach for a list when a parameter reflects but nothing fires —
xss-waf-bypass against a filtering target, xss-polyglots when the
injection context is unclear, xss-js-frameworks for a Vue/Angular front
end. Tier B is injection payloads, not discovery wordlists, and this is the
only tool that can request one.
bypass_vendor names a WAF vendor whose ordered XSS bypass set is looked
up from the knowledge base and handed to dalfox via --custom-payload the
same way a tier B list would be. The exploit chain uses it to re-test a
point whose base pass came back clean: the WAF may have eaten the textbook
payloads while the vendor-specific set gets through.
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | ||
| payload_list | No | ||
| bypass_vendor | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description openly states this is an 'EXPLOIT' requiring human approval, which aligns with and extends the annotations (destructiveHint=true). It explains that it runs dalfox and how it uses custom payloads and WAF bypasses. This provides behavioral detail beyond the annotations without contradiction.
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 well-structured with three clear paragraphs, but it is somewhat repetitive. The second and third paragraphs follow the same template ('Leave it unset first...', 'Reach for a list when...'), which adds length without much additional insight. Still, it remains focused and readable.
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?
The description covers the tool's purpose, parameters, approval requirement, and exploit nature. It does not describe the output or return value, but given the tool's role as a validator, the output is likely a result set of confirmed vulnerabilities. The absence of explicit output details is a minor gap, but the overall context is sufficient 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?
The schema has no descriptions for any parameters, so the tool description must compensate. It explains payload_list and bypass_vendor thoroughly, including when to set them and what they do. The 'target' parameter is not explicitly described, but its meaning is easily inferred from the phrase 'on a URL'. Coverage is high for two of three parameters, with the third being self-evident.
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's purpose: 'Confirm reflected XSS on a URL with dalfox.' This is specific, uses a verb, and distinguishes it from sibling tools like sqli_validate or cmdi_probe. The exploit context is immediately clear.
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 gives excellent guidance on when to use the optional payload_list and bypass_vendor parameters ('Leave it unset first', 'Reach for a list when a parameter reflects but nothing fires'). It also mentions the human approval requirement. However, it does not explicitly compare this tool to alternatives like waf_bypass or guided_validate, though the name and purpose make the choice obvious in most contexts.
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.
v2.1.0account_registerapproval_pendingapproval_respondasn_lookupaudit_tailauth_crawlauth_surfaceauthz_comparebbot_scanbbot_scan_activebrain_historybrain_learnbrain_recallbrain_statebrowser_verifyburp_sendcdn_checkcloud_asset_discoverycloud_attack_pathscloud_auditcloud_permissionscmdi_probecode_auditcontent_discoverycontract_static_scancontract_toolchaincordon_capabilitiescordon_finishcordon_load_scopecordon_statuscors_auditcoverage_reportdashboard_statedns_permutedns_resolveendpoint_discoveryengagement_attachengagement_newexploit_chainexploit_promptfetch_slicefinding_detailfinding_notefindings_listfingerprint_wafforbidden_bypassforbidden_candidatesforbidden_chainfuzz_comparegraph_recallgraphql_auditguided_validatehttp_probehunt_planjaeles_scanjob_canceljob_fetchjob_listjob_statusjs_analyzejwt_inspectk8s_posturellm_probe_catalogllm_redteamllm_scan_configmemory_recallnikto_scannosqli_probenuclei_scanoob_listenerosmedeus_flowparam_discoverypattern_scanpayload_catalogpipeline_statuspoc_recordport_scanprogram_scope_fetchprompt_classesrecon_reviewreport_generateresearch_guidancerule_testrules_listrules_reloadrun_phaserun_pipelinescope_checksecret_scansecret_validatesecurity_txtsemgrep_scanservice_scansession_listsession_registersmuggling_canary_probesmuggling_probesource_fetchsqli_validatessrf_probessti_probestrix_deepsubdomain_enumtakeover_confirmtakeover_detecttakeover_poc_plantakeover_verifytaskgraph_nexttaskgraph_updatetaskgraph_viewtechnique_lookuptls_audittls_infotriage_canary_previewtriage_findingstriage_taskflowsupload_surfacevalidate_findingswaf_bypasswaf_detectwaf_vendorswapiti_scanweb_injection_probewebsocket_probewhois_lookupwstg_lookupxss_validateScored across 127 tools
Most tools are crisply differentiated, but several pairs genuinely overlap: code_audit and semgrep_scan both run Semgrep over workspace source, brain_recall / memory_recall / graph_recall are three near-synonymous 'recall knowledge' tools, and cordon_status vs dashboard_state both report engagement state. An agent would plausibly misselect among these. The pipeline families (takeover_detect/verify/confirm/poc_plan, forbidden_candidates/bypass, secret_scan/validate) are otherwise well-structured.
The dominant convention is snake_case verb_noun (subdomain_enum, whois_lookup, content_discovery, secret_scan) with a consistent toolname_scan sub-family (nikto_scan, nuclei_scan, wapiti_scan, semgrep_scan). Deviations exist — the cordon_* brand prefix, cmdi_probe's abbreviation, security_txt's nominal form, and fuzz_compare's verb_verb — but they are minor against the overall pattern.
With roughly 70 tools listed (127 claimed), this is an extreme count — an order of magnitude beyond the 3-15 well-scoped range and far past the 25+ threshold. Even granting the platform's broad domain (web, cloud, k8s, smart contracts, memory, reporting), no agent can navigate this surface efficiently, and the presentation overwhelms rather than assists.
The surface covers the entire offensive-security lifecycle: scope loading and checking, passive and active recon, web/cloud/k8s/smart-contract scanning, approval-gated exploitation, secrets, SAST, findings management, reporting, job control, rules management, knowledge lookup, memory, task-graph planning, audit, triage, and approvals. References to port_scan/http_probe/job_status suggest tools outside this list, but within the provided set there are no obvious dead ends.
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Security firewall for AI agents — scans MCP calls for injection, secrets, and risks.