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

No annotations provided, so the description carries the full burden. It discloses that the tool returns a tiny response and counts various categories. However, it does not clarify the behavior of the refresh parameter or whether counts are cached.

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

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

Two sentences, front-loaded with key information, no superfluous content. Each phrase 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?

Covers the tool's main purpose and breakdowns, but omits explanation of the refresh parameter. For a simple tool with one optional parameter, this is a notable gap in completeness.

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

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

Schema coverage is 0% (no parameter described). The sole parameter 'refresh' is not mentioned in the description, leaving its purpose unexplained. Description must compensate for low coverage but fails to do so.

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

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

The description clearly states it counts programs with specific breakdowns (total, bounty, VDP, by submission_state) and explicitly distinguishes from listing, which differentiates it from sibling tools like list_programs.

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 advises to use for 'how many ...' questions, implying when to count rather than list. Also notes it's a cheap, small API call, guiding efficient usage.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. The description only says it 'formats' a report, but does not state whether it has side effects (e.g., saves the report), requires authentication, or has rate limits. For a tool that likely only returns formatted text, this is insufficient.

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

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

The description is a single concise sentence. However, it sacrifices necessary detail for brevity. Every word matters, but important aspects like output format and parameter hints are omitted. It is not overly long, but it could be more informative without losing conciseness.

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

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

Given 6 required parameters, no output schema, and no annotations, the description is far from complete. It does not explain the return value (markdown text), any constraints (e.g., character limits), or how the parameters relate to a HackerOne report. The agent would have to infer too much.

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

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

The schema has 6 required string parameters with no descriptions (0% coverage). The description adds no information about parameter semantics. For example, 'weakness' could be a CWE ID or name, and 'steps' likely means steps to reproduce, but nothing clarifies this. The agent receives no guidance beyond parameter 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?

The description clearly states the tool formats a HackerOne-style report in markdown. The verb 'Format' and resource 'HackerOne-style report' are specific, and it distinguishes from sibling tools like 'get_report' (retrieves existing reports) and 'list_my_reports' (lists reports). However, it could explicitly mention that it does not submit the 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?

No usage guidelines are provided. There is no indication of when to use this tool versus alternatives such as 'get_report' or 'list_my_reports'. The description does not include any context about prerequisites or when not to use it.

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

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

No annotations are provided, so the description must convey behavioral traits. It states 'Omitted filters are not applied' which implies independent filtering, but it does not disclose whether the tool is read-only, requires authentication, has rate limits, or what the 'refresh' parameter does (e.g., force fetch from API). The behavior of the 'refresh' parameter is completely unexplained.

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

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

The description is a single sentence with inline examples, making it efficient and front-loaded with the tool's purpose. It avoids unnecessary words and the examples are directly integrated. However, the lack of any structure (e.g., separate parameter descriptions) slightly reduces clarity for the refresh parameter.

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

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

Given the tool has 4 parameters, no output schema, and no annotations, the description provides a basic understanding of filtering but falls short on explaining the 'refresh' parameter, return format, and what 'compactly' means. For a simple filtered list tool, 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 0%, so the description must provide meaning. It adds value for three parameters (bookmarked, offers_bounties, submission_state) by providing example values, but does not explain the 'refresh' parameter at all. Additionally, it does not specify data types, allowed values (e.g., whether submission_state has a fixed set), or null semantics beyond default null.

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

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

The description clearly states that the tool lists programs matching filters, and provides examples like 'all VDPs (offers_bounties=false)'. It specifies the resource (programs) and action (list with filters). However, it does not explicitly differentiate from sibling tool 'list_programs', which may serve a similar unfiltered purpose.

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

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

The description gives contextual examples for when to use each filter (bookmarked, offers_bounties, submission_state), which implies usage scenarios. However, it lacks guidance on when to prefer this tool over siblings like 'list_programs' or 'count_programs', and does not specify 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.

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

The description explicitly states it is a read operation, which implies non-destructive behavior. No annotations exist, so description bears full burden; it is adequate but could mention authentication requirements.

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

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

Single sentence, no wasted words. Front-loaded with verb and resource.

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 parameter-less read tool with no output schema, the description fully informs the agent of the tool's function. No additional context needed.

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?

No parameters exist; schema coverage is 100%. Baseline 3 applies as description adds no parameter information but doesn't need to.

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

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

Description clearly states the action (Read) and resource (your current HackerOne balance), making its purpose unambiguous and distinct from siblings.

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

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

No guidance on when or when not to use this tool. While context implies it's for checking balance, 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.

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

With no annotations, the description bears full responsibility for behavioral disclosure. It states 'Get' implying a read operation, but does not specify idempotency, permissions required, response size, or any side effects. Basic expectations are inferred but not explicitly clarified.

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

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

The description is a single, concise sentence that immediately conveys the tool's purpose and required input. Every word is necessary, and there is no redundancy or wasted space.

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

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

Given the tool's simplicity (single required parameter, standard retrieval operation), the description is largely complete. However, the lack of an output schema means details about the return structure are absent, but the description 'full policy/details' broadly covers expectations.

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 explicitly mentions the parameter 'handle' with the phrase 'by its handle', clarifying its purpose. Since there is only one parameter and it is explained, the description adds sufficient semantic value beyond the schema.

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

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

The description uses specific verb 'Get' and resource 'full policy/details for a program', clearly indicating the tool retrieves complete information for a single program. It distinguishes from sibling tools like 'list_programs' (which lists multiple) and 'filter_programs' (which filters), as it targets a unique program by handle.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'list_programs' or 'filter_programs'. There is no mention of prerequisites, when not to use it, or trade-offs compared to siblings.

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

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

No annotations provided, so the description carries full burden. It indicates a read operation with summarization, but lacks details on authentication, rate limits, or side effects. Minimal behavioral disclosure.

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

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

The description is a single concise sentence, but underspecifies. It could add parameter context without becoming verbose.

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

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

For a simple 2-parameter tool with no output schema, the description covers the basic purpose but omits parameter details and behavioral context, leaving gaps for the agent.

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

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

With 0% schema description coverage, the description must explain parameters. It does not mention 'handle' or 'refresh', leaving their meaning and usage unclear.

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

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

The description clearly states the tool retrieves structured scopes for a program, summarized in/out of scope. It uses a specific verb and resource, distinguishing it from sibling tools like search_scopes or filter_programs.

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

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

The description implies use when needing scopes for a specific program, but does not specify when to avoid this tool or mention alternatives like search_scopes. No context for exclusions or prerequisites.

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

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

No annotations are provided. The description discloses the output fields (name, external_id, description) but does not mention any behavioral traits such as side effects, authorization requirements, or rate limits. It is a minimal disclosure for a simple list 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 a single sentence of 20 words, front-loaded with the action and resource, with no extraneous information.

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

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

Given the tool has only one parameter and no output schema, the description adequately lists the return fields and gives an example of external_id format. It misses details like potential constraints or ordering, but is largely complete for its simplicity.

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% with no description for the handle parameter. The description only implies handle identifies a program, but does not explicitly state its meaning, format, or how to obtain it. This provides only marginal added 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 the tool lists weaknesses (CWE types) for a program, specifying the returned fields: name, external_id, and description. This distinguishes it from siblings like list_cwe_types (which might list all CWE types) and get_program_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?

Usage context is implied: you need a specific program handle to list its weaknesses. However, no explicit guidance on when to use this vs alternatives or any prerequisites is provided.

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

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

With no annotations, the description bears full responsibility for behavioral disclosure. It states 'Read' (non-destructive) but does not mention permissions, error conditions (e.g., missing report), or any side effects.

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

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

The description is a single, concise sentence with no unnecessary words. It is front-loaded with the action. However, additional useful details could be added without harming conciseness.

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

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

Given a simple tool with one parameter and no output schema, the description covers the core purpose but omits return format, error handling, and access requirements. It is minimally adequate but not comprehensive.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'by its id' but does not clarify the format, source, or expected value of report_id. The parameter lacks semantic enrichment.

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

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

The description clearly states the verb 'Read', the resource 'a specific report', and the method 'by its id'. This distinguishes it from sibling tools like list_my_reports and 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 provided on when to use this tool over alternatives such as list_my_reports or search_disclosed_reports. The description lacks any context about prerequisites or exclusions.

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

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

No annotations are provided, and the description does not disclose any behavioral traits such as whether the tool is read-only, if it caches results, or the effect of the refresh parameter. Minimal transparency beyond the basic action.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core purpose. However, it omits important parameter information that could be included without sacrificing conciseness.

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

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

Despite the tool's simplicity (one optional param, no output schema), the description lacks any mention of what the tool returns (e.g., a list of names) or the behavior of the refresh parameter, leaving the agent with incomplete 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 coverage is 0% and the description makes no mention of the single parameter 'refresh'. It provides no additional meaning beyond the schema's type and default, leaving the agent without guidance on how to use the parameter.

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

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

The description clearly states the verb 'list' and resource 'valid CWE/weakness names', and explicitly links its purpose to the 'cwe' filter in search_disclosed_reports, distinguishing it from 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 when to use the tool (when needing CWE names for filtering), but provides no explicit guidance on when not to use it or alternatives, and does not address the refresh parameter's role in usage decisions.

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

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

No annotations are present, so the description carries full responsibility for disclosing behavior. It only says 'List', implying a read operation, but does not mention pagination, sorting, filtering, or any other behavioral traits. This is a significant gap for a tool with no annotation support.

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

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

The description is a single, front-loaded sentence with no wasted words. It is appropriately concise for a parameterless 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?

Given the lack of output schema and annotations, the description should explain what the list of earnings contains. It does not specify fields, format, or any additional context, leaving the agent with insufficient information to interpret the results.

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

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

There are zero parameters, and schema coverage is 100%. According to the rubric, a baseline of 4 is appropriate since the description adds no additional parameter information, but none is needed.

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

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

The description clearly states the action ('List') and the resource ('your HackerOne earnings'). It is specific and unambiguous, but does not differentiate from sibling tools like 'get_balance' which might also relate to financial data.

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

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

No guidance is provided on when to use this tool versus alternatives. The description merely states what it does, with no context about when it is appropriate or when to use other tools like 'get_balance' or 'list_my_reports'.

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

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

Discloses that the tool lists only the user's own submitted reports and the output fields (id, title, state, dates). No contradictions with annotations (none provided). Could mention pagination or ordering, but acceptable for a simple list.

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 efficient sentences: first states purpose and output, second provides usage guidance. No filler words.

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

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

Complete for a parameterless list tool with no output schema. Tells what it does, output format, and how to get details. Could mention ordering or number of results, but not critical.

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?

No parameters, so baseline 4. Description adds meaning about output format beyond schema (compact fields).

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

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

Clearly states it lists the user's own submitted reports with compact output including id, title, state, dates. Distinguishes from sibling get_report by specifying compact vs full detail.

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 get_report for full detail of one report, providing an alternative. This guides the agent when to use this tool vs the sibling.

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

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

Discloses that the full list is large and compact reduces response size. No annotations exist, so description carries the burden well, though it omits stating it's read-only.

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

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

Two sentences, no fluff, front-loaded with main purpose. Every sentence adds value.

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

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

Covers purpose, usage, and one parameter. Lacks explanation of refresh parameter and response format, but for a simple list tool, it's largely sufficient.

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?

Explains compact parameter in detail (what fields it returns and size benefit), but refresh parameter is left unexplained. Schema coverage is 0%, so description partially 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?

Description clearly states 'List all HackerOne programs your account can access' – a specific verb and resource. It also distinguishes from sibling 'count_programs'.

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 suggests using compact=true for large lists and directs to count_programs for totals, providing clear when-to-use guidance.

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

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

No annotations provided, so description carries full burden. It discloses that the tool scans every program (one API call per program) and can be slow/rate-limited, which is critical behavioral context. Does not mention any side effects or return format.

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?

Very concise: two sentences in first paragraph for purpose, two sentences for behavior and parameter guidance. No redundant information, front-loaded with key action.

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

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

Covers purpose, performance, and one parameter. Lacks explanation of the 'refresh' parameter and does not describe the output format. Given the tool's simplicity and no output schema, it is still partially incomplete.

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

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

Schema description coverage is 0%. The description adds value for the 'limit' parameter (explains its effect on speed and scope) but does not explain the 'refresh' parameter, leaving it ambiguous.

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

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

The description clearly states the tool ranks programs by attractiveness with explicit criteria (bounties, scope breadth, severity), distinguishing it from siblings like list_programs or filter_programs.

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

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

Provides advice on when to use the tool (ranking) and performance considerations (slow on cold cache, suggests using limit for quick results). Does not explicitly mention when not to use, but the context implies alternatives.

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

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

No annotations provided, so description carries burden. States 'authenticated read-only GET' indicating safety. However, it doesn't detail behavior for invalid paths, rate limits, or response format. Adequate but could be more 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?

Description is concise and front-loaded with purpose. The list of known endpoints is useful but slightly lengthens it. Efficient overall.

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

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

No output schema and missing return value description. Authentication details are implied but not explicit. Could be more complete by noting expected response shape or error handling for a raw GET tool.

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

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

Schema coverage is 0% with no descriptions. The description adds value by specifying 'Pass a RELATIVE path (no host)' for path and implies params are for query parameters. Significantly compensates for lack of schema descriptions.

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

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

The description clearly states 'Authenticated read-only GET against any HackerOne v1 path, for reads not covered by a dedicated tool.' It provides a specific verb (GET) and resource (HackerOne v1 path) and distinguishes from siblings by indicating it's for uncovered reads.

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 'for reads not covered by a dedicated tool' and lists known read endpoints, guiding when to use this tool. Also instructs to pass a relative path. Slightly missing explicit when-not scenarios, but context is clear.

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

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

Discloses it returns up to 10 matches with name and handle, but does not mention behavior for empty term or the refresh parameter. Without annotations, more detail on side effects or auth would help.

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

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

Two sentences, efficiently describes action and output with no wasted words.

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

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

Covers core functionality but lacks details on refresh parameter, search semantics (case sensitivity, partial matches), and output format beyond name/handle.

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

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

With 0% schema coverage, description partially explains 'term' (name/handle) but omits 'refresh' entirely, failing to compensate for the lack of documentation.

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

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

The description clearly states the tool searches HackerOne's public program directory by name/handle term, which distinguishes it from siblings like list_programs and 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?

Implied usage for searching programs by name/handle, but no explicit guidance on when to use this tool over siblings like search_disclosed_reports or list_programs.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format ({total_count, results[...]}), pagination via size/from_, default sort logic, and date bounds with YYYY-MM-DD format. It does not mention rate limits or authentication requirements, but it is sufficiently transparent for a read-only search 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 concise (5 sentences) and well-structured: first sentence states purpose, followed by filter list, sort defaults, date bounds, pagination, and return format. Every sentence adds value with no redundancy or fluff.

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

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

Given the 11 parameters, no output schema, and no annotations, the description is highly comprehensive. It covers all parameters, return structure, pagination, and default behaviors. It lacks details on error handling or rate limits, but it is sufficient for an agent to understand and use the tool correctly.

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

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

The input schema has 0% description coverage, leaving all parameter meaning to the description. The description thoroughly explains each parameter: query, severity, cwe, cve, program, sort (with default behavior), since/until (with format), size, and from_. It provides valid values and context beyond the schema, making parameter usage 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?

The description clearly states it searches 'HackerOne's PUBLIC disclosed reports (hacktivity)', distinguishes from sibling search tools like search_directory and search_scopes, and details the specific resource and verb. It also lists multiple filters, making the purpose unambiguous.

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

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

The description provides clear context for when to use the tool (to search public disclosed reports) but does not explicitly state when not to use it or mention alternative tools. It explains default sort behavior and parameter usage, which helps, but lacks exclusions or comparisons to siblings.

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

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

No annotations provided, but the description discloses performance implications: cold cache makes one API call per program, causing slowness/rate limits. This adds value beyond the schema.

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 sentences, each earning its place: purpose, then behavioral note and tip. No wasted words, front-loaded with purpose.

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

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

Covers purpose and performance but lacks output format description and does not explain the refresh parameter. Given no output schema, more detail on return values would improve completeness.

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

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

Schema coverage is 0%, so description must add meaning. It explains query (keyword), limit (controls scanning), and asset_type (optional), but does not mention refresh. The explanations are minimal but useful.

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

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

The description clearly states the tool searches assets across programs by keyword and optional asset_type. It is distinct from sibling tools like search_directory and 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?

Provides context that scanning all programs can be slow/rate-limited and suggests using limit for quick results. No explicit when-not or alternatives, but the context is clear.

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