Provides read-only tools for interacting with HackerOne, including searching and retrieving reports, managing programs and scope, accessing earnings and payouts, viewing disclosed reports, and performing owner-only operations like balance, bounty table, audit log, and program members.
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., "@Targets MCP find disclosed reports about XSS in bug bounty programs"
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.
Custom HackerOne MCP server: 25 tools, all hackerone_*. No database, no cache
files, no write actions. Future home of Bugcrowd + other platforms (same tool shape).
My reports: search_reports, get_report, get_report_with_conversation,
get_report_activities, analyze_report_patterns
Programs: list_programs, search_programs, get_program_details (categorized +
sections subset), get_program_scope, search_scopes, list_scope_exclusions,
get_program_weaknesses, list_hacker_invitations
Money: get_earnings, list_payouts, get_balance, get_hacker_profile
Public: search_disclosed_reports, hack_brief, download_attachment
Owner reads (need program-owner token): program_balance, program_bounty_table,
program_audit_log, list_program_members
Hatch: api_get (GET-only)
Related MCP server: h1-brain
npm install
bash build.shmcp_servers:
hackerone:
command: "node"
args: ["/home/youssef/tools/hackerone/dist/index.js"]
env:
H1_USERNAME: "<api-identifier>"
H1_API_TOKEN: "<token>"HackerOne token: https://hackerone.com/settings/api_token/edit
Edit src/ → run build.sh (clients execute dist/, edits alone never load).
After rebuild, restart the MCP client session (old sessions keep the old server process).
Test: H1_USERNAME=... H1_API_TOKEN=... node tests/verify-mcp.mjs (expect SUITE_PASS).
See docs/ for full details and reference notes.
Analyze your recent reports: severity/state distribution, top programs and weakness types.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Reports to analyze (default 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. 'Analyze' implies a read-only operation, and 'your recent reports' scopes the data, but the description does not explicitly state that nothing is modified, how 'recent' is defined, or whether authentication or specific report ownership is required. It provides some behavioral context but leaves important details implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately communicates the tool's purpose and lists the key output categories with no filler. Every word 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 simple tool with one optional parameter, the description communicates the main purpose and output dimensions effectively. It does not describe the exact response shape or define 'recent', but the absent output schema is partially compensated by the precise list of analytics provided. Slightly more detail on the scope of 'recent reports' 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, page_size, is fully described in the schema with its range and default behavior. The description does not add any meaning beyond what the schema already provides. Given 100% schema description coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Analyze') applied to a specific resource ('your recent reports') and lists concrete output dimensions: severity/state distribution, top programs, and weakness types. It is easily distinguished from sibling reporting tools like hackerone_search_reports, though it does not explicitly name or contrast 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 implies the tool is for high-level aggregation and pattern analysis rather than retrieving individual reports, but it provides no explicit when-to-use guidance, exclusions, or mention of alternative tools. The intended use case is reasonably inferable but not directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Raw GET to any HackerOne API path (e.g. /hackers/programs). Read-only by design; use only when no purpose-built tool exists.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | API path starting with / | |
| params | No | Query params |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It does state 'Read-only by design,' which is important safety-relevant context, and 'Raw GET' clarifies the operation. However, it does not mention potential rate limits, authentication requirements, error behavior, or response variability, which would matter for a raw API access 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 well-structured sentence that front-loads the core behavior, gives an example, and then states the usage restriction. Every part earns its place, 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?
For a generic raw-access tool with no output schema and no annotations, the description covers the essential context: what it does, its safety profile, and when to use it instead of siblings. It is slightly thin on operational details like how errors are surfaced or whether the full HackerOne base URL is assumed, but it is sufficiently complete for an agent to select and invoke it correctly in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents both parameters adequately. The description adds a useful example of the path format but does not meaningfully elaborate beyond what the schema provides for 'params'.
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 (raw GET), the resource (any HackerOne API path), and provides an illustrative example (/hackers/programs). It also distinguishes itself from purpose-built sibling tools by explicitly framing itself as a generic fallback.
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 'use only when no purpose-built tool exists' is an explicit when-not-to-use instruction, directly guiding an agent away from the many sibling tools. This is ideal guidance for a generic fallback tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a report attachment to tools/hackerone/downloads/ (25MB cap). Returns the file path.
| Name | Required | Description | Default |
|---|---|---|---|
| report_id | Yes | The HackerOne report ID | |
| attachment_id | No | Attachment id (lists choices if omitted and several exist) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses the download destination, the file size cap, and the return value (file path). It does not cover failure modes or overwrite behavior, but the disclosed behavioral details are meaningful and non-obvious.
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 no filler. The primary action and destination come first, and the size cap and return type are stated 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?
For a simple two-parameter download tool with full schema coverage, the description is largely complete: it specifies where the file goes, the size limit, and what is returned. It omits failure handling and attachment selection behavior, but the schema covers the optional attachment_id behavior, keeping the gap minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both report_id and attachment_id sufficiently. The description adds context about the download destination and cap but does not elaborate on parameter formatting, which is acceptable given the high schema coverage baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'Download' with a clear resource 'report attachment', a destination directory, and an explicit 25MB cap. It is immediately distinguishable from all sibling tools, none of which handle attachment downloads.
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 tool's purpose makes its use case fairly obvious, and no sibling tool competes for the same action. However, the description does not explicitly state when to choose this tool versus alternatives or mention any preconditions, such as needing a valid report_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Your current unpaid bounty balance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It conveys that the balance is 'unpaid' and 'current', but it does not explicitly state that this is a read-only operation, whether authentication is required, or how the balance is calculated. The noun phrase provides minimal behavioral insight.
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 only five words with no unnecessary detail. It lacks a verb or full sentence structure, but it is appropriately sized for a simple query tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description provides the essential information: it returns the current unpaid bounty balance for the user. It is sufficient to distinguish it from related tools and to invoke it without additional input, though output format and authentication specifics are not mentioned.
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 explain parameters, and the baseline for a zero-parameter tool is 4.
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 'Your current unpaid bounty balance' clearly identifies the resource being accessed (the hacker's own unpaid bounty balance) and distinguishes it from siblings like hackerone_program_balance or hackerone_get_earnings. It lacks an explicit verb, but the meaning 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 gives no guidance on when to use this tool versus alternatives such as hackerone_get_earnings or hackerone_program_balance. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Your bounty earnings history: amounts, currency, dates, programs.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Results per page (default 25) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read-only history operation but does not explicitly state that it is a retrieval, whether results are paginated, or any authentication requirements. 'Earnings history' hints at non-destructive behavior, but the description does not add meaningful behavioral detail beyond the tool name and the listed fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, stating the core value proposition in a single phrase. No words are wasted, though it could be improved by using an explicit verb and a complete sentence to make the action unmistakable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description provides enough information about the return content to allow basic invocation. However, it lacks guidance on pagination behavior and fails to distinguish itself from closely related financial siblings, leaving some ambiguity for an agent choosing among tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single optional parameter, page_size, is fully documented in the input schema with 'Results per page (default 25)', so schema coverage is 100%. The description does not add any additional parameter semantics, which is acceptable given the schema already provides the necessary context.
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 resource as the user's own bounty earnings history and names the key returned fields: amounts, currency, dates, and programs. It does not use an explicit verb like 'Retrieve' and does not explicitly contrast with sibling tools, but the 'Your' and 'earnings history' framing is specific enough to differentiate it from balance and payout 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 offers no guidance on when to use this tool versus similar siblings such as hackerone_list_payouts, hackerone_get_balance, or hackerone_program_bounty_table. There are no exclusions, alternatives, or context clues beyond the word 'Your', so an agent must infer the right choice from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Your profile: username, reputation/signal/impact plus stats computed from your own reports.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It usefully clarifies the scope (your own profile) and the dependency on your own reports, but it does not explicitly state that the operation is read-only, require authentication, or describe any rate-limit or side-effect behavior. These are implied by 'get' but not 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?
A single sentence with no filler, front-loaded with the subject ('Your profile') and followed by the returned fields. 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?
The description names key output fields, but no output schema exists and 'plus stats computed from your own reports' is vague about which stats. It also doesn't clarify that earnings are handled elsewhere, though the simple zero-parameter read makes the gap minor.
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 empty schema covers 100% of them, so there is no parameter ambiguity. The 0-parameter baseline of 4 applies; there is nothing for the description to add.
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 identifies the resource precisely: the caller's own HackerOne profile, and enumerates the contents (username, reputation/signal/impact, and report-derived stats). This is enough to distinguish it from sibling report, program, and earnings tools, though it doesn't use an explicit verb like 'retrieves'.
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 about when to choose this tool over hackerone_get_earnings, hackerone_search_reports, or other siblings. The description implies 'use when you want your profile,' but it never states prerequisites, exclusions, or alternative conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full program data in categories: identity, timeline (open date), bounty, metrics (response times), trust, my_stats, policy, scope_summary. Pass sections for only what you need.
| Name | Required | Description | Default |
|---|---|---|---|
| sections | No | Subset to return, e.g. ['metrics','policy'] or 'metrics,policy'. Omit for everything. | |
| program_handle | Yes | Program handle (e.g. 'uber') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It discloses the output categories (identity, timeline, bounty, metrics, trust, my_stats, policy, scope_summary) and the section-filtering behavior, but it does not describe the default full-response shape, authentication needs, or any rate/visibility caveats. This is useful but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tight sentence that front-loads the main purpose and category list, then appends the optimization hint. 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?
For a two-parameter retrieval tool, the description plus schema provides enough to invoke it correctly: the required program handle, the optional section filter, and the set of available data categories. Since there is no output schema, a little more detail about the structure within each category would make it fully complete, but it is not 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?
Schema description coverage is 100%, so the baseline is 3; the description mainly reiterates the sections-filter concept already in the schema ('Omit for everything'). It adds little new parameter meaning beyond reinforcing that sections restrict the response.
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 a resource (program) and action (get full details) and enumerates the data categories returned, so an agent knows what it will receive. It does not explicitly contrast with sibling tools like get_program_scope or get_program_weaknesses, so it stops short of full 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?
'Pass sections for only what you need' gives a practical usage hint for filtering output and implies the tool is the right choice when you want comprehensive program data. There is no explicit when-to-use versus alternatives such as get_program_scope or list_programs, so usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
In-scope assets of a program. Auto-paginates. Shows types, bounty eligibility, severity caps.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Max items (default: all) | |
| program_handle | Yes | Program handle (e.g. 'uber') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses auto-pagination and the key output dimensions (types, bounty eligibility, severity caps). It does not mention access requirements or side effects, but this is a read-oriented getter, and the disclosed behaviors are relevant.
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 short sentences with no filler. The core purpose is front-loaded, and each additional sentence adds a distinct useful detail. Very economical and well 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?
For a simple scope-listing tool with only one required parameter and no nested objects, the description provides enough context to call it correctly: what it returns, which program it targets, and pagination behavior. The lack of an output schema is partially mitigated by listing the key output categories.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented. The description's 'Auto-paginates' adds behavioral context to page_size, but it doesn't add significant semantic detail beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (a program's in-scope assets) and the information returned (types, bounty eligibility, severity caps). It does not explicitly differentiate from the sibling hackerone_search_scopes, so it falls short of full sibling distinction.
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 'In-scope assets of a program' implies when to use this tool, and the required program_handle makes the target clear. However, there is no explicit guidance about when to choose this over hackerone_search_scopes or hackerone_list_scope_exclusions, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Accepted weakness/CWE types of a program. Auto-paginates.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Max items (default: all) | |
| program_handle | Yes | Program handle (e.g. 'uber') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses one useful behavioral trait: auto-pagination, which is not obvious from the schema. However, with no annotations provided, the description carries the full burden and does not mention the read-only nature, return 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 two short sentences with no redundant wording. The core purpose is front-loaded, and the auto-pagination note is a meaningful second sentence that earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool, the description covers the essential purpose and the main non-obvious behavior. It could say more about what exactly is returned, but the phrase 'weakness/CWE types' plus a fully documented schema gives the agent enough context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters fully, including the meaning of page_size and an example for program_handle. The description adds no further parameter-level detail, so the baseline of 3 is appropriate given 100% 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 clearly states the resource: accepted weakness/CWE types of a program, which matches the tool name and is distinct from report, scope, and profile tools. It lacks an explicit verb and does not differentiate itself from sibling tools like hackerone_get_program_scope, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as hackerone_get_program_scope or hackerone_get_program_details. It does not mention preconditions, typical use cases, or exclusions, so the agent must infer applicability from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details of one of your reports: title, vuln info, impact, severity, CVSS, bounty, attachments, program.
| Name | Required | Description | Default |
|---|---|---|---|
| report_id | Yes | The HackerOne report ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the behavioral burden. It does disclose the read-only return contents and ownership scope, but it does not mention authentication, error behavior, or that conversation/activity threads are excluded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with a useful field list; no filler. The core subject is front-loaded and every listed item adds 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 single-parameter read tool, the description adequately conveys the return scope (title through program) and ownership limitation. It could be more complete by naming the conversation/activity sibling or clarifying ID format, but the low complexity keeps this from being a serious 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?
Schema coverage is 100% and the lone parameter is already described as 'The HackerOne report ID'. The description reinforces the report context but adds no format or usage detail 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?
Describes a specific action ('get') on a specific resource ('your reports') and enumerates the returned fields. It is clearly distinct from search tools, though it does not explicitly distinguish itself from the closely named sibling hackerone_get_report_with_conversation.
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 over alternatives such as hackerone_get_report_with_conversation or hackerone_get_report_activities. The phrase 'your reports' implies access scope, but there is no stated workflow for locating a report_id or when to choose another sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Activity timeline of a report: comments, state changes, bounty awards, triage responses.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Results per page (default 25) | |
| report_id | Yes | The HackerOne report ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It indicates the tool returns a timeline of activities and enumerates categories, but it does not describe ordering, pagination behavior, response structure, or auth requirements. It is adequate for a straightforward read operation, but not richly 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 a single, focused sentence that front-loads the core concept and uses a concise colon-delimited list to convey scope. Every word adds value and there is 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?
For a tool with only two parameters, both fully described in the schema, the description covers the essential return-value concept and activity categories. There is no output schema, but the tool is simple enough that the timeline description plus schema documentation 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?
Schema description coverage is 100%, so both report_id and page_size are already documented in the input schema. The description does not add parameter-level meaning beyond the schema, which aligns with the baseline score for high 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 identifies the tool's purpose: retrieving an activity timeline for a HackerOne report, and it lists the specific kinds of activities included. This differentiates it from siblings like hackerone_get_report and hackerone_get_report_with_conversation by emphasizing the full activity stream rather than just report details or conversation messages.
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 context for when to use the tool: when a report's activity history is needed, including comments, state changes, bounty awards, and triage responses. It does not explicitly name alternatives or exclusion cases, but the scope is evident enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A report with its full triage conversation. Shows what triage asked and what led to resolution.
| Name | Required | Description | Default |
|---|---|---|---|
| report_id | Yes | The HackerOne report ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It does disclose the core return content—the full conversation and resolution—and 'Shows' implies a read operation, but it does not describe response structure, pagination, depth of report details, or any access constraints. This is adequate but leaves material behavior implicit.
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 short sentences with no filler. The core resource is front-loaded, and the second sentence adds useful context about what the conversation contains. Both sentences earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one fully documented parameter) and the description conveys the key differentiator, the conversation. However, with no output schema and no explicit boundary against sibling tools like hackerone_get_report_activities, the description is not fully complete for an agent that must decide between several similar report-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter report_id ('The HackerOne report ID'), so the schema fully documents the parameter. The description adds no additional meaning about the parameter, matching the baseline of 3.
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 identifies a specific resource—a report with its full triage conversation—and clarifies what it shows (questions asked, path to resolution). It is distinguishable from siblings like hackerone_get_report_activities even though it lacks an explicit verb; the tool name supplies the get 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 that this tool is for retrieving the triage conversation and its resolution, but it does not explicitly state when to choose it over hackerone_get_report or hackerone_get_report_activities. No exclusions or alternative routing are provided, leaving the choice mostly to name inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attack briefing for a program, all live: bounty scope, your past findings, untouched assets, suggested vectors, public disclosures sample.
| Name | Required | Description | Default |
|---|---|---|---|
| program_handle | Yes | Program handle (e.g. 'uber') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. It communicates that data is 'all live' and discloses the sections returned, which gives some transparency. It does not explicitly state that this is a read-only operation, what authentication is assumed, or what 'your past findings' means in relation to the caller.
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 ('Attack briefing for a program'), followed by a precise list of contents. Every element adds value; there is no filler 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?
For a tool with one simple parameter and no output schema, the description gives a useful inventory of what the briefing contains. It is slightly incomplete in not defining whose past findings are included or how fresh 'live' data is, but an agent can reasonably decide when and how 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 schema describes the only parameter, program_handle, with an example ('uber') and 100% coverage. The description adds no additional meaning beyond the schema, but with full schema coverage and one parameter, it does not need to compensate. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific deliverable ('Attack briefing for a program') and enumerates its contents: bounty scope, past findings, untouched assets, suggested vectors, and a public disclosures sample. This is more specific than a tautology and distinguishes the tool from granular sibling tools, though it uses a noun rather than a clear verb and does not explicitly contrast with any 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 implies usage: call this when you want an aggregated attack briefing for a program. It does not, however, provide explicit when-to-use or when-not-to-use guidance, nor does it name alternatives such as hackerone_get_program_details or hackerone_get_program_scope for narrower data needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Private-invite programs for an account (program-owner API; 403 on plain hacker token).
| Name | Required | Description | Default |
|---|---|---|---|
| program | Yes | Program handle or numeric id |
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 an important failure mode (403 on plain hacker token), which is genuinely useful. It does not describe the response format or whether the list is paginated or filtered.
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 compact and front-loads the core purpose before the auth caveat. No words are wasted, though adding a verb would improve clarity slightly.
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 list endpoint, the auth caveat is the most important missing context and it is provided. However, with no output schema, the description does not indicate what the returned invitations look like or what fields are included.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents the only parameter ('program'). The description adds no additional meaning or constraints beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific resource—private-invite programs for an account—and a specific scope, distinguishing it from general program listing. However, it lacks an explicit verb like 'list', relying on the tool name to convey the 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?
It provides useful auth context ('program-owner API; 403 on plain hacker token'), which implies when it can be used successfully. It does not explicitly compare with sibling tools such as hackerone_list_programs or state 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.
Your payout transactions (provider, status, amounts).
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Results per page (default 25) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only gives a noun phrase and a parenthetical list of fields; it does not mention pagination behavior, authentication requirements, sorting, or whether the response includes pending and completed payouts.
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 resource, with the returned fields in a compact parenthetical. It is efficiently written, though slightly too terse to fully stand alone.
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, one-optional-parameter list tool, the description covers the core resource and returned fields. However, with no output schema and no annotations, it should also clarify pagination defaults and the scope of 'your' payouts to be fully complete. This is a minimum-viable description with notable 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?
There is a single optional parameter, page_size, and the schema already documents its range, minimum, maximum, and default (100% coverage). The description adds no parameter semantics beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource ('payout transactions') and the fields returned (provider, status, amounts), so an agent can infer the tool is about payouts. However, it lacks an explicit verb (e.g., 'list'), relying on the tool name, and it does not distinguish itself from related siblings like get_earnings or get_balance.
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 instead of sibling tools such as hackerone_get_earnings, hackerone_get_balance, or hackerone_program_balance. The agent must guess the appropriate context from the resource name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Program team members (program-owner API).
| Name | Required | Description | Default |
|---|---|---|---|
| program | Yes | Program handle or numeric id | |
| page_size | No | Results per page (default 25) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose an authorization trait (program-owner API) and the resource being returned, but it does not mention pagination, response shape, or side effects. For a list operation these are partially implicit, so partial credit 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 very short and free of filler, but it is a sentence fragment that lacks a verb, and the useful qualifier is tucked into a parenthesis. It is concise but structurally under-built.
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 list tool, the schema covers invocation arguments and the description conveys the resource and auth class. However, with no output schema and no annotations, an agent still lacks detail about the member object shape and pagination semantics, so completeness is only partial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters at 100% coverage: program handle or numeric id, and page_size with a default of 25. The description adds no parameter-level meaning, so it earns the baseline without extra credit.
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 identifies the resource ('program team members') and an API context ('program-owner API'), but it is a noun phrase with no explicit verb such as 'list' or 'return.' The action must be inferred from the tool name, so it is clearer than a tautology but not a specific verb+resource statement.
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 instead of siblings like get_program_details, list_programs, or get_program_scope. The parenthetical 'program-owner API' hints at an access context, but it never states conditions, exclusions, or alternatives.
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 can access. Auto-paginates.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Max programs (default: all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. 'List' implies read-only and 'Auto-paginates' is a useful disclosure, but return format, default behavior beyond page_size, and limits are not described.
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 clauses front-load the core action and scope, with no filler or repetition. Every word adds 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 single-optional-parameter list operation, the description and schema together cover invocation and pagination behavior. Its only real gap is not routing the agent to search_programs for broader discoverability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: page_size already has a description ('Max programs (default: all)'). The description's 'Auto-paginates' reinforces the schema but adds no new parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific resource ('bug bounty programs') with a clear action ('List') and an access constraint ('you can access'). It does not explicitly contrast with sibling hackerone_search_programs, so differentiation is left to naming.
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 access constraint implies a use case, but the description gives no guidance on when to choose this over hackerone_search_programs or when not to use it. No alternatives 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.
What a program explicitly excludes from scope.
| Name | Required | Description | Default |
|---|---|---|---|
| program_handle | Yes | Program handle (e.g. 'uber') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not explicitly state that this is a read-only list operation, what the response shape is, or whether empty results are possible. The nominal phrase 'what a program explicitly excludes' provides content semantics but not behavioral 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 filler or redundancy. It is front-loaded and easy to parse, though it is slightly under-specified as a noun phrase rather than a full imperative statement.
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 one-parameter list tool with full schema coverage, the description minimally conveys what the tool returns. However, it does not explicitly describe the return type, whether it returns a structured list, or how it relates to the program scope tools, leaving moderate gaps for 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?
The single parameter program_handle is fully documented in the schema with a clear type and example ('uber'), and schema description coverage is 100%. The description adds no parameter-specific meaning, so it does not need to compensate; 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 clearly identifies the resource as a program's explicit scope exclusions, and the word 'excludes' distinguishes it from scope-related siblings like hackerone_get_program_scope. It lacks an explicit verb such as 'list' or 'retrieve,' but the tool name and context make the action clear enough.
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 about when to use this tool versus alternatives such as hackerone_get_program_scope or hackerone_search_scopes. The description only implies a use case for retrieving exclusions, but provides no prerequisites, exclusions, or comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Program audit log (program-owner API).
| Name | Required | Description | Default |
|---|---|---|---|
| program | Yes | Program handle or numeric id | |
| page_size | No | Results per page (default 25) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full behavioral burden, but it only reveals that the tool is a program-owner API. It does not state whether the operation is read-only, what response format to expect, how pagination works, or what errors may occur.
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 very short and contains no filler words, but it is under-specified to the point of being more a label than a helpful definition. The parenthetical structure provides minimal extra value beyond repeating the tool name.
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 lack of annotations and no output schema, the description is insufficient on its own. It omits return values, pagination behavior, and auth prerequisites beyond the vague 'program-owner API' tag, so an agent would struggle to invoke the tool correctly without additional 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 input schema fully describes both parameters, including the default page_size and constraints, so the description does not need to add much parameter detail. Still, the description adds no semantic meaning beyond what the schema already provides, keeping this at the baseline for high 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 identifies the resource as a program audit log and notes it is a program-owner API, but it lacks an explicit action verb such as 'get' or 'list'. It mostly restates the tool name, so while the general purpose is inferable, it is not clearly articulated.
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 any of the many sibling tools. The parenthetical 'program-owner API' hints at an access restriction but does not explain when this tool should be selected over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Program bounty wallet (program-owner API).
| Name | Required | Description | Default |
|---|---|---|---|
| program | Yes | Program handle or numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavioral traits. It only mentions 'program-owner API' suggesting authorization requirements, but it does not clarify whether the operation is read-only, what the return format is, or any rate limits or side effects. This is minimal disclosure for a tool that likely performs a secure read 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 extremely short (a single phrase), which is concise, but it is under-specified to the point of being unhelpful. It is not a tautology as it adds a contextual hint ('program-owner API'), but it fails to provide even the core action. The brevity is not a virtue when critical information is missing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description should at least state what the tool returns or how the balance is represented. It does neither. The description is incomplete for an agent to know what to expect after invoking the tool, even considering the minimal input 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?
The input schema covers the single parameter 'program' with a clear description ('Program handle or numeric id'), achieving 100% schema coverage. The tool description adds no additional meaning to the parameter, so the baseline score of 3 applies as the schema already does the heavy lifting.
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 'Program bounty wallet (program-owner API)' does not state a clear verb or action. It suggests the tool relates to a program's bounty wallet but never explicitly says it retrieves, queries, or checks the balance. It also does not distinguish it from sibling tools like 'hackerone_get_balance' or 'hackerone_program_bounty_table', leaving the agent to infer the operation.
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 hints at 'program-owner API' which implies it is intended for users with program ownership, but it gives no explicit guidance on when to use this tool versus alternatives such as 'hackerone_get_balance' (likely for the user's own balance). No exclusions or conditions are provided, leaving usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Program bounty table (program-owner API).
| Name | Required | Description | Default |
|---|---|---|---|
| program | Yes | Program handle or numeric id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only hints at an access restriction. It does not state whether the operation is read-only, what data is returned, whether pagination or filtering applies, or what happens if the caller is not a program owner.
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 short and front-loaded, with no wasted words. It is appropriately compact for a one-parameter tool, though the brevity sacrifices behavioral 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?
Despite having only one parameter and full schema coverage, the description lacks return-value context, permission implications, and any relationship to sibling program tools. An agent would know what to pass but not what to expect back or how this differs from other program-related endpoints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents 'program' as 'Program handle or numeric id'. The tool description adds no parameter-specific meaning beyond naming the resource, so the baseline of 3 is appropriate; the schema does the necessary work.
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 noun phrase 'Program bounty table' names a specific resource, and the parenthetical 'program-owner API' narrows its audience. It is not a tautology and it is distinguishable in topic from siblings like program_balance or program_audit_log. However, there is no explicit verb like 'get' or 'list', so the exact operation is inferred rather than stated.
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 only a role-based context ('program-owner API') and does not say when to prefer this tool over alternatives such as hackerone_get_program_details, hackerone_program_balance, or hackerone_list_programs. There is no when-to-use guidance, no exclusions, and no comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search public hacktivity. Program filter is exact match. Keyword matches title/weakness/program/reporter, but most items are undisclosed (no titles) so keyword is often empty — browse or filter by program instead.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Keyword matched on title/weakness | |
| program | No | Program handle to filter by (e.g. 'uber') | |
| page_size | No | Results per page (default 25) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It discloses that program matching is exact, keyword matches several fields, and most hacktivity items are undisclosed with empty titles — a key caveat that materially shapes how an agent should use the tool. It does not mention pagination or output shape, but for a simple search tool this is acceptable.
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 tight sentences with no filler. It front-loads the core purpose, states the exact-match constraint, and immediately follows with the most important practical caveat. Every clause 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 three-parameter search tool with full schema coverageaine, the description is largely complete: it explains what the tool searches, how filters behave, and why keyword search is often unproductive. The main gap is that it does not describe the result format or pagination, but this is not critical for basic 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 already covers all three parameters at 100% coverage, so the baseline is 3. The description adds extra value by explaining that the program filter is exact match and that keyword matches title/weakness/program/reporter, going beyond the schema's narrower 'title/weakness' 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 action ('Search') and a distinct resource ('public hacktivity'), making it clear this is a read-only search over disclosed/public report activity. It also clarifies the program filter is an exact match, which helps distinguish it from broader report-search 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 gives practical search guidance: use the program filter for exact matching, and note that keyword searches are often ineffective because most items lack titles. It does not explicitly name sibling alternatives or state when to prefer this over hackerone_search_reports, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search programs by handle/name, optionally bounty-only. Live, no cache.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | Substring of handle or name | |
| bounty_only | No | Only programs offering bounties |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. 'Live, no cache' communicates data freshness, but it does not disclose read-only safety, rate limits, result-size behavior, or any other operational traits that would help an agent understand 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?
Two short sentences with no filler. The core search criteria are front-loaded, and the 'Live, no cache' note adds a useful behavioral fact 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?
With no output schema and no annotations, the description omits return-value shape, pagination/limit behavior, and any pointer to sibling tools. It is enough for a basic invocation but leaves an agent uncertain about how results are presented and when to prefer related program tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes query as a substring and bounty_only as a bounty filter, and the description restates these without adding new meaning. The limit parameter is documented only by its min/max constraints, with no semantic explanation in either the schema or 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 action, 'Search programs', with explicit criteria: 'by handle/name' and optional 'bounty-only'. This clearly distinguishes it from siblings like hackerone_list_programs (listing programs) and hackerone_search_scopes (searching scopes).
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 explicit when-to-use or when-not-to-use guidance. The description implies searching by handle/name but never mentions alternatives such as hackerone_list_programs or hackerone_get_program_details, so an agent gets no routing help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and list your HackerOne reports. Filter by keyword, program, severity, or state.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort field (prefix - for desc) | |
| query | No | Keyword search (e.g. 'SSRF') | |
| state | No | ||
| program | No | Program handle to filter by (e.g. 'uber') | |
| severity | No | ||
| page_size | No | Results per page (default 25) | |
| page_number | No | Page number for pagination |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the burden of explaining behavior. It only says the tool searches and lists reports with filters, but does not disclose pagination behavior, default sort, whether full report contents are returned, or any ownership/authorization expectations. The scope 'your' adds some context, but significant behavioral traits are 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 front-loaded sentence with no filler. Every clause contributes useful information about scope and filtering, 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?
With no output schema and no annotations, this tool needs a more complete description. It lacks guidance on pagination, result shape, sort behavior, and when to prefer this tool over search_disclosed_reports or other search tools. The description is adequate for orientation but not enough for confident invocation in a multi-tool context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 71%, and the description mirrors what the schema already exposes by naming keyword, program, severity, and state filters. It adds no new semantics for sort, page_size, or page_number, and it does not help clarify the undocumented page_number parameter. Still, it provides a reasonable orientation to the main filterable facets.
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 a specific verb and resource: 'Search and list your HackerOne reports.' It also names the main filter dimensions (keyword, program, severity, state). It does not explicitly contrast with sibling tools, but the phrase 'your HackerOne reports' distinguishes it from hackerone_search_disclosed_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?
No guidance is given for when to use this tool versus alternatives such as hackerone_search_disclosed_reports, hackerone_search_programs, or hackerone_get_report. The description implies a search/list context but provides no exclusions or routing hints for an agent choosing among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search in-scope assets by program and/or asset substring, optionally bounty-only. Asset without program matches program names first (empty = no match, pass program_handle).
| Name | Required | Description | Default |
|---|---|---|---|
| asset | No | Substring of asset identifier (e.g. 'api', '.com') | |
| limit | No | ||
| program | No | Program handle to filter by (e.g. 'uber') | |
| bounty_only | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals a non-obvious matching behavior (asset-only searches match program names first, and empty asset yields no match unless program_handle is passed). However, it does not disclose other behavioral traits such as pagination, result ordering, or whether the search is case-sensitive.
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. The second sentence adds a necessary usage caveat. It is slightly dense but every clause 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 search tool with 4 optional parameters and no output schema, the description covers the main search semantics and a key edge case. However, it omits details like result format, pagination, and default limit behavior, which an agent might need to interpret results correctly. It is adequate but not 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?
Schema description coverage is 50%: asset and program have descriptions, while limit and bounty_only do not. The description adds context for the asset and program parameters by explaining their combined behavior, but it does not add meaning for limit or bounty_only beyond their names. This is adequate but not exceptional.
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 ('Search') and resource ('in-scope assets'), and identifies the key filtering dimensions (program, asset substring, bounty-only). It is distinguishable from siblings like hackerone_search_programs and hackerone_get_program_scope, though it does not explicitly name them.
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 context for when to use this tool: searching in-scope assets by program and/or asset substring, optionally bounty-only. It also provides a usage caveat ('Asset without program matches program names first (empty = no match, pass program_handle)'), which helps an agent avoid a common mistake. It does not explicitly state when to prefer a sibling tool, but the scope is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0hackerone_analyze_report_patternshackerone_api_gethackerone_download_attachmenthackerone_get_balancehackerone_get_earningshackerone_get_hacker_profilehackerone_get_program_detailshackerone_get_program_scopehackerone_get_program_weaknesseshackerone_get_reporthackerone_get_report_activitieshackerone_get_report_with_conversationhackerone_hack_briefhackerone_list_hacker_invitationshackerone_list_payoutshackerone_list_program_membershackerone_list_programshackerone_list_scope_exclusionshackerone_program_audit_loghackerone_program_balancehackerone_program_bounty_tablehackerone_search_disclosed_reportshackerone_search_programshackerone_search_reportshackerone_search_scopesScored across 25 tools
Each tool maps to a specific HackerOne resource/action (report details vs conversation vs activity vs earnings), so misselection risk is low. The only mild ambiguity is the catch-all hackerone_api_get, which overlaps with any existing endpoint, though the description explicitly reserves it for gaps.
All tools use the hackerone_ prefix and snake_case, with a dominant verb_noun pattern (get_, list_, search_, download_). A few program-owner tools (program_balance, program_bounty_table, program_audit_log) and hack_brief break the verb-first pattern, but the convention is still highly predictable.
At 25 tools this is at the heavy end of the 16-25 range. Each tool appears purposeful, but the surface is large and could overwhelm an agent selecting from it.
The read/analysis side is thorough: reports, programs, scope, earnings, payouts, and admin tools are covered. However, write actions are missing — there is no way to create/update reports, reply in conversations, or otherwise mutate state, and hackerone_api_get is read-only, leaving some workflows dead-ended.
Read-only public CVE records, capability metadata, and agent instructions from Hacker Bob.
Read-only CVE intelligence, remediation playbooks, and agent setup guides. Not a scanner.
Read-only access to your CodeMouse accounts, repositories, and AI pull-request reviews.
Programmatic control of the Hiro security platform: scans, tasks, plans, and approvals.