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., "@yeswehack-mcp List my private programs on YesWeHack."
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.
A Model Context Protocol (MCP) server for the YesWeHack bug bounty platform. Lets Claude query your private and public programs, reports, and the hacktivity feed directly from a conversation.
Flexible authentication — browser login, email/password API login, copied bearer tokens, and official Personal Access Tokens.
Private programs — returns invite-only programs you have been accepted into, not just public ones.
Full program details — scope, reward ranges, status.
Report access — list and read reports with severity, CVSS, description, and bounty.
Report comments — list report discussion/messages when your account has access.
Email aliases — list your YesWeHack email aliases.
Program credentials — list credential pools/assigned credentials and request credentials for programs that expose pools.
Hacktivity feed — browse publicly disclosed reports.
Token caching — the JWT is stored locally and reused until it expires.
Related MCP server: MCP Hacker News
Python 3.10+
uv (installed automatically by the setup script if missing)
A YesWeHack account
WSL2 users: WSLg must be enabled so Chromium can open a window (echo $DISPLAY should return a value)
git clone https://github.com/youruser/yeswehack-mcp
cd yeswehack-mcp
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv sync
# Download the Chromium browser used for login
uv run playwright install chromiumclaude mcp add yeswehack -- uv --directory /path/to/yeswehack-mcp run server.pyReplace /path/to/yeswehack-mcp with the actual path where you cloned the repo.
Verify it connected:
claude mcp list
# yeswehack: ... ✓ ConnectedAdd the following to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"yeswehack": {
"command": "uv",
"args": [
"--directory",
"/path/to/yeswehack-mcp",
"run",
"server.py"
]
}
}
}If uv is not on PATH when Claude Desktop launches, use the absolute path (e.g. /home/youruser/.local/bin/uv).
Once registered, start every session by authenticating:
You: Call the authenticate tool
With no arguments, a Chromium window opens. Log in to YesWeHack as normal (email + password + 2FA if enabled). The window closes automatically once your session is detected. The token is saved to ~/.config/yeswehack-mcp/token.json and reused for all subsequent calls until it expires.
You can also authenticate without a browser:
authenticate(email="you@example.com", password="...", totp="123456")
authenticate(access_token="eyJ...") # browser/API bearer token
authenticate(access_token="ywh_pat_...") # Personal Access TokenEnvironment variables are supported too:
export YWH_TOKEN="eyJ..." # browser/API bearer token
export YWH_PAT="ywh_pat_..." # Personal Access TokenTool | Description |
| Browser login, API login, or store a copied bearer token/PAT |
| Show your YesWeHack profile (username, rank, reputation) |
| List all programs you have access to, including private invite-only ones |
| Full details for a program: scope, reward ranges, status |
| List reports for a program, with optional status filter |
| Full details of a specific report (title, severity, CVSS, description, bounty) |
| List comments/messages for a report when your token has access |
| List your YesWeHack email aliases |
| List credential pools and assigned credentials for a program |
| Request credentials from a program credential pool |
| Read-only escape hatch for authenticated API endpoints not wrapped yet |
| Browse the public hacktivity (disclosed reports) feed |
List all my private programs on YesWeHack.
Show me the scope for the program with slug "acme-corp".
List my YesWeHack email aliases.
Get credentials for program "acme-corp".
List all accepted reports for program "acme-corp".
Get the full details of report 12345.
Show me the latest hacktivity, page 2.The token is saved to ~/.config/yeswehack-mcp/token.json. It contains only the token and its expiry timestamp — no account password is ever stored. Browser/API session JWTs use their embedded expiry. Opaque Personal Access Tokens are cached locally until the YesWeHack API rejects them. The browser profile (cookies, localStorage) is kept at ~/.config/yeswehack-mcp/browser-profile so you do not have to fill in your email every time you re-authenticate.
To log out, delete the token file:
rm ~/.config/yeswehack-mcp/token.jsonyeswehack-mcp/
├── server.py # FastMCP entry point — all tool definitions
├── auth.py # Playwright browser login + token storage
├── client.py # httpx async API wrapper with pagination
└── pyproject.toml # Dependencies and build configPlaywright needs a display to open the browser window. On WSL2 with WSLg this works out of the box. If you see an error about DISPLAY not being set:
# Check if WSLg is running
echo $DISPLAY # should print something like :0
ls /mnt/wslg # should exist
# If not, ensure you are on a recent WSL2 version with WSLg support
wsl --update # run from Windows PowerShellMIT
Authenticate with YesWeHack and store the session token locally. Call this first before using any other tool, or when a tool reports that authentication is required.
Option 1 — Direct token: provide access_token to skip credential login entirely. Option 2 — API login: provide email + password for a fast, browser-free login. If your account has 2FA enabled, the first call will ask for a TOTP code; call again with the same email/password and add the totp argument. Option 3 — Browser: call with no arguments to open a browser window instead.
You can also set the YWH_TOKEN environment variable to avoid calling this tool at all; it takes precedence over stored credentials.
Args: access_token: A pre-obtained YesWeHack JWT/bearer token (highest priority). email: Your YesWeHack account email. password: Your YesWeHack account password. totp: 6-digit TOTP code (only needed when 2FA is enabled).
| Name | Required | Description | Default |
|---|---|---|---|
| totp | No | ||
| No | |||
| password | No | ||
| access_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that a session token is stored locally, that 2FA requires a second call with a TOTP code, and that environment variables take precedence. This is strong behavioral disclosure, though it does not detail the exact shape of the stored session or any security 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?
Well-structured with numbered options and brief parameter explanations. The critical 'call this first' guidance is front-loaded, and every sentence adds operational 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?
Given the tool's role as a prerequisite for all siblings, the description fully covers authentication flows, retry behavior for 2FA, and alternative auth via environment variable. The output schema exists, so return-value details are not required 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?
Schema description coverage is 0%, so the description must compensate for the bare parameter list. It does so thoroughly: access_token is described as highest priority, email/password are for API login, and totp is explicitly tied to 2FA-only use. This gives the agent everything needed to choose among the options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: authenticates with YesWeHack and stores the session token locally. It clearly differentiates itself from the sibling tools, which are all API operations that presuppose authentication.
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 this first before any other tool, or when a tool reports authentication is required. It also lays out three concrete usage options and mentions the YWH_TOKEN environment variable as an alternative that avoids calling the tool entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the profile of the currently authenticated YesWeHack user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full responsibility for behavioral disclosure. 'Return' implies a read-only operation, and 'currently authenticated' signals auth requirements. For a zero-parameter getter, these disclosures are sufficient; there is no side-effect or destructive behavior hiding behind the description.
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 one clear sentence with no extraneous content. It front-loads the action and resource and wastes no words, making it easy for an agent 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?
For a zero-parameter, current-user profile retrieval with an output schema present, the description is complete. It states what the tool returns and the context (authenticated user), and nothing else is needed 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 input schema has zero parameters and 100% schema coverage, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because nothing is missing; the description does not need to explain parameters that do not 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 states a specific verb ('Return') and a specific resource ('the profile of the currently authenticated YesWeHack user'). This clearly distinguishes the tool from siblings like authenticate or list_programs, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'currently authenticated' clearly indicates the tool should be used only after authentication, and that it targets the caller's own identity. It provides clear context, though it does not explicitly list exclusions or alternative tools for similar user-related queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the public YesWeHack hacktivity feed (publicly disclosed reports). No authentication required.
Args: page: Page number (default 1).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the authentication requirement, the data scope (publicly disclosed reports), and implicitly that it is a read-only feed. It does not mention rate limits or pagination details beyond the page parameter, but these are less critical for a simple public feed.
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 plus a single args line, with the core purpose front-loaded and zero filler. Every sentence contributes meaningful 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?
For a one-parameter public feed tool with an output schema present, the description covers purpose, auth, and the page argument. No major gaps remain; it could optionally mention that the result is a list, but the output schema covers 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?
Schema description coverage is 0%, so the description must add meaning. It only restates 'Page number (default 1)', which duplicates the schema's own title and default. It does not clarify 1-based indexing, page size, or upper bounds, adding negligible value over 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 a specific verb ('Get') and resource ('public YesWeHack hacktivity feed') and clarifies it contains publicly disclosed reports. This distinguishes it from sibling report tools like list_reports or get_report.
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 'No authentication required', implying use for public data without credentials. However, it does not explicitly contrast this with alternatives such as list_reports or get_report, leaving when-not-to-use to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details for a specific program, including scope, reward ranges, guidelines, requirements, out-of-scope rules, and disabled vulnerability types.
Args: slug: The program slug/identifier (e.g. 'acme-corp'). Use list_programs to find slugs.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. 'Get' and the enumerated return-content categories signal a read-only lookup, but the description does not mention authentication requirements, rate limits, or any behavioral side effects. It is adequate for a safe read tool but not deeply 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?
Two short, purposeful sections: one sentence defines the operation and its return content, and an Args block explains the single parameter. No filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read lookup with an output schema available, the description is complete: it tells the agent what the tool returns, what the parameter means, and how to obtain the parameter value. Nothing needed 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?
The schema provides only the parameter name 'slug', but the description adds a plain-language definition, an example ('acme-corp'), and a pointer to list_programs for discovering valid slugs. This fully 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 opens with a specific verb ('Get') and resource ('full details for a specific program'), then enumerates the exact content categories (scope, reward ranges, guidelines, requirements, out-of-scope rules, disabled vulnerability types). This makes it easy to distinguish from sibling tools like get_program_credentials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly establishes that the tool is for retrieving details for one known program and includes a practical instruction: 'Use list_programs to find slugs.' It does not explicitly state when not to use it in favor of credentials-oriented siblings, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get credential pools and any assigned credentials for a specific program.
Some programs expose credential pools only after you are invited/accepted and KYC-verified. If credentials require a request first, use request_program_credentials with the pool id shown by this tool.
Args: program_slug: Program slug/identifier. include_secrets: Include passwords/secrets when the API returns them. raw: Return raw JSON instead of a readable summary.
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | ||
| program_slug | Yes | ||
| include_secrets | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose access gating (invited/accepted and KYC-verified) and conditional secret availability ('when the API returns them'), but it does not explicitly state the read-only/side-effect profile or authentication requirements. The 'Get' verb partially covers this, but not fully.
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: purpose first, then access caveat and sibling routing, then an Args block. Every sentence adds action-relevant information 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?
An output schema is present, so return-value details are covered elsewhere. The description provides everything needed for invocation: all parameters, the main access constraints, and the appropriate alternative tool when credentials require a request.
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%, but the description documents all three parameters with meaningful plain-language explanations: program_slug as identifier, include_secrets as toggling passwords/secrets, and raw as returning raw JSON instead of a summary. This fully compensates 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 a specific verb ('Get') and resource ('credential pools and any assigned credentials for a specific program'), which is unambiguous. It distinguishes itself from request_program_credentials by describing the request path, so an agent can tell them 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?
Explicitly says to use request_program_credentials when credentials require a request first, and warns that some programs only expose credential pools after invite/acceptance and KYC verification. This provides 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.
Get full details of a specific vulnerability report.
Args: report_id: The numeric report ID (from list_reports output).
| Name | Required | Description | Default |
|---|---|---|---|
| report_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. The description only says it gets details; it does not mention authentication requirements, whether the tool performs a read-only GET, potential error conditions, rate limits, or what fields 'full details' includes. Since an output schema exists, some return structure is available, but the tool's behavior beyond fetching is opaque.
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 front-loads the purpose in the first sentence. The Args section is a standard, useful formatting choice. No wasted words, though the two-sentence structure could arguably be merged 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 tool is simple with a single required parameter, and the output schema supplies return-value structure. The description covers the essential 'what' and 'where the ID comes from'. It lacks context on when to call it relative to list_reports and what 'full details' includes, but for a simple lookup tool this 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 description coverage is 0%, so the description must compensate for the sparse schema. It explains that report_id is 'the numeric report ID (from list_reports output)', which adds meaningful provenance and type context beyond the schema's bare integer type. However, it does not elaborate on how to obtain the ID if not from list_reports, or special format constraints, so it only partially bridges the 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 a specific verb and resource: 'Get full details of a specific vulnerability report.' The description is clear and differentiates from sibling tools like list_reports, though it doesn't explicitly name the sibling it complements. It is unambiguous enough for an agent to understand the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage by mentioning the report_id comes 'from list_reports output', which gives a hint about the workflow. It does not explicitly state when to use this tool versus alternatives like list_reports or list_report_comments, but the 'full details' wording suggests a single-record retrieval use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your YesWeHack email aliases.
YesWeHack requires KYC verification for alias usage. The exact UI endpoint is not publicly documented, so this tool tries the known API shapes and reports the attempted endpoints if none work.
Args: raw: Return raw JSON instead of a readable summary.
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It transparently states that the tool tries known API shapes and reports attempted endpoints if none work, which is valuable unexpected behavior to disclose. It does not detail auth requirements or failure handling beyond endpoint reporting, but the core behavioral trait is 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?
The description is compact and well-structured: a one-line purpose, a brief note on KYC and endpoint discovery, and a clear parameter explanation. Every sentence contributes meaningful information without waste.
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, has one optional boolean parameter, an output schema, and no annotations. The description covers purpose, KYC prerequisites, unusual API-shape discovery behavior, and the raw output flag. It is complete for practical invocation, though it does not explicitly mention authentication state or the exact shape of the readable summary.
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 schema only provides a boolean named 'raw' with a default. The description adds the essential semantic: raw returns raw JSON instead of a readable summary. This fully explains the single optional parameter, compensating for the absent schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('your YesWeHack email aliases'), clearly identifying the tool's function. It is easily distinguishable from the sibling tools, which concern credentials, programs, reports, and user info rather than aliases.
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: KYC verification is required for alias usage, and the tool compensates for an undocumented UI endpoint by trying known API shapes. It does not explicitly name alternative tools, but none of the siblings serve the same purpose, so this omission is not significant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List bug bounty programs you have access to, including private invite-only programs.
Args: all_pages: If True (default), fetch all pages and return the complete list. page: Specific page to fetch when all_pages is False. private_only: If True, return only private (invite-only) programs.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| all_pages | No | ||
| private_only | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral transparency burden. It discloses meaningful pagination behavior (all_pages vs. page), the default of all_pages, and the private_only filtering behavior. It does not mention authentication requirements or rate limits, but as a straightforward read operation with an output schema, the disclosed behavior is reasonably complete.
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 tool's core purpose, followed by a clean, minimal Args section. Every sentence adds value; there is no filler or redundant schema 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?
For a simple list tool with no required parameters, no nested objects, and an existing output schema, the description covers everything an agent needs to invoke it correctly. It specifies fetch-all behavior, page selection, and private-only filtering in a self-contained way.
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 is the only source of parameter meaning. It compensates well by explaining all three parameters beyond their types and defaults, especially the conditional relationship between all_pages and page. It stops short of detailing page size or response pagination metadata, but the core semantics are clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and a specific resource ('bug bounty programs you have access to'), including the key differentiator of private invite-only programs. This clearly distinguishes it from siblings like get_program, which retrieves a single program, and list_reports, which lists reports.
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 argument-level behavior but provides no guidance on when to choose list_programs over get_program or list_reports, and mentions no alternatives or exclusions. An agent is left to infer the appropriate use case from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List comments/messages for a vulnerability report when your token has access.
Args: report_id: The numeric report ID. raw: Return raw JSON instead of a readable summary.
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | ||
| report_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It communicates the access requirement ('when your token has access'), implies a read-only list operation, and explains the raw parameter's effect of returning raw JSON instead of a readable summary. This is solid for a simple read-only tool, though it does not detail error behavior or pagination.
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, front-loaded with the core purpose, and uses a clean Args block for parameter explanations. 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 two-parameter read-only list tool with an existing output schema, the description covers the essential behavior, access condition, and parameter semantics. Nothing needed for correct invocation 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 description meaningfully explains both parameters beyond the schema: report_id is 'the numeric report ID' and raw controls whether output is raw JSON versus a readable summary. Since schema description coverage is 0%, this parameter documentation fully compensates.
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 specific verb and resource: 'List comments/messages for a vulnerability report.' This clearly identifies what the tool does and makes it easy to distinguish from siblings like list_reports or get_report, which cover different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this tool to retrieve comments/messages attached to a specific vulnerability report, identified by report_id. It does not explicitly name alternatives or exclusions, but there is no sibling tool with a similar comment-listing purpose, so the usage context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List vulnerability reports submitted to a program.
Args: program_slug: The program slug identifier. status: Optional status filter (e.g. 'accepted', 'informative', 'duplicate', 'wont_fix', 'new', 'triaged', 'not_applicable').
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| program_slug | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral burden. It implies a read-only listing operation but does not disclose pagination, sorting, authentication requirements, or response size limits, leaving important behavioral details undocumented.
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 clear one-line purpose followed by brief parameter explanations. There is no filler or redundant content, and the most important 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?
For a simple two-parameter listing tool with an output schema, this is minimally viable: it states what the tool does and what arguments to pass. It is not fully complete because pagination and authentication prerequisites are not mentioned, but the low parameter complexity and presence of an output schema reduce the burden.
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 compensates by explaining both parameters. It clarifies that program_slug is the program identifier and provides concrete example values for status, which is especially valuable because the schema defines no enum for valid statuses.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (list), resource (vulnerability reports), and scope (submitted to a program), so the operation is unambiguous. It does not explicitly contrast itself with sibling tools like get_report or list_report_comments, but the verb and resource are clear enough to distinguish the main 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 intended use is implied: call this when you need the reports submitted to a program, optionally filtered by status. There is no explicit mention of when to use get_report for a single report or any exclusions, so the guidance is present but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request credentials from a program credential pool.
This performs a state-changing YesWeHack action. Use get_program_credentials first to find an available pool id. Some email-credential pools require an email address; pass either a YesWeHack alias or another allowed address.
Args: program_slug: Program slug/identifier. pool_id: Optional credential pool id. If omitted, the generic program credential request endpoint is attempted. email: Optional email address for email-based credential pools. raw: Return raw JSON instead of a readable summary.
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | ||
| No | |||
| pool_id | No | ||
| program_slug | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It clearly discloses that this is a state-changing action and describes conditional behavior around pool_id, email, and raw output. It does not mention authentication requirements or potential effects on the credential pool, so it is not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and a state-changing warning, then provides prerequisite and conditional usage, followed by a compact Args list. Every sentence adds value and there is 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 prerequisites, conditional email requirements, fallback behavior, and raw output, while the output schema handles return shape. It lacks explicit authentication/permission context, and since no annotations are provided, that small gap prevents 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%, but the description's Args section explains all four parameters with meaningful detail: program_slug, pool_id, email, and raw. This adds behavior and context well beyond the bare schema field names.
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?
Clear verb and object: 'Request credentials from a program credential pool.' It also flags the action as state-changing and references get_program_credentials, which distinguishes this write/request tool from the read-oriented 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?
Explicitly tells the agent to call get_program_credentials first, explains when an email is required, and states the fallback behavior when pool_id is omitted. This is strong when-to-use guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read an authenticated YesWeHack API endpoint that is not wrapped yet.
This is a read-only escape hatch for API coverage gaps. Path must be a relative API path such as /programs/example or /reports/123.
Args: path: Relative API path beginning with /. params_json: Optional JSON object of query parameters.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| params_json | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description itself establishes read-only behavior and authentication requirements. It could add details about error behavior or rate limits, but the core safety-relevant disclosure (read-only GET escape hatch) is 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?
The information is front-loaded with purpose, then usage context, then a compact Args section. Every sentence contributes either purpose, selection criteria, or parameter meaning; 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 tool is simple, has an output schema, and the description covers purpose, usage, and parameters. Minor gaps like URL construction, pagination, and error handling are not addressed, but they are secondary for a raw read-only API escape hatch. Slightly stronger than baseline due to the explicit auth and relative-path constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are 0% covered, but the description compensates fully: path is described as a relative API path starting with '/', and params_json as an optional JSON object of query parameters. This is exactly the additional meaning an agent needs beyond the raw 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?
Description states a specific verb ('Read'), a resource ('authenticated YesWeHack API endpoint'), and the tool's role as an escape hatch for unwrapped endpoints. This clearly separates it from the sibling wrapped tools like list_programs/get_program.
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 to use it for API coverage gaps and endpoints that are not wrapped yet, which tells an agent when to choose it over the sibling wrappers. It also constrains the path to a relative API path beginning with '/', with examples.
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.
v0.1.0authenticateget_current_userget_hacktivityget_programget_program_credentialsget_reportlist_email_aliaseslist_programslist_report_commentslist_reportsrequest_program_credentialsyeswehack_api_getScored across 12 tools
Most tools pair a distinct resource with a clear verb (list_programs vs get_program, list_reports vs get_report, get_program_credentials vs request_program_credentials). The main ambiguity is yeswehack_api_get, a generic read-only escape hatch that conceptually overlaps with all dedicated getters, though its 'unwrapped endpoints only' framing reduces confusion.
The dominant verb_noun pattern is consistent (list_programs, get_report, request_program_credentials), but yeswehack_api_get reverses the order with a service prefix, and authenticate is a lone verb without a noun. These deviations are noticeable but not chaotic.
12 tools is well-scoped for a bug bounty platform client: authentication, programs, reports, comments, credentials, user profile, hacktivity, and one escape hatch. Each tool earns its place and the count is neither bloated nor thin.
The read surface is solid (programs, reports, comments, credentials, hacktivity), but state-changing operations central to the bug bounty workflow are missing: there is no way to submit a vulnerability report or post a comment on a report. The read-only escape hatch cannot fill these gaps, so researchers cannot complete a full workflow.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
