BountyVerdict Agent Decision Tools

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

Goes beyond annotations by disclosing pricing (free preview, $0.03 retry), authentication requirement, and read-only nature. No contradiction with annotations.

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

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

Description is concise (3 sentences) and front-loaded with key points. No redundancy, includes a sample link.

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 tool with cost and authentication complexity; covers all necessary context: cost model, usage timing, limitations, and read-only guarantee.

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

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

Only one parameter with 100% schema coverage; description adds no extra parameter details beyond usage context. Baseline 3 is appropriate.

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

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

The description clearly states the tool audits a repository's instruction stack before assigning a coding agent, and distinguishes itself from CI diagnosis. The title and description together provide a specific verb+resource.

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 clear context: 'Use before assigning a coding agent...' and 'This does not diagnose CI.' Does not name sibling tools explicitly but gives enough guidance for when to use.

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 complements annotations (readOnlyHint, idempotentHint, destructiveHint) by stating 'Read-only; never invent arguments.' It also discloses the cost behavior (free preview vs. paid signed retry) and provides a sample endpoint. This adds behavioral context beyond the structured annotations, such as the dual-call pattern and pricing details.

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

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

The description is concise (4 sentences) and well-structured: it front-loads pricing info, then states the use case, provides an alternative, and ends with a read-only caveat and sample link. Every sentence adds value without redundancy.

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

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

Given the low complexity (single parameter, required, with schema coverage and annotations), the description covers all necessary aspects: pricing, use case, alternative, sample, and safety declaration. An output schema exists, so return values are already handled. The description is complete for an agent to correctly select and 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?

Schema description coverage is 100% for the single parameter (issue_url), so the baseline is 3. The description does not add new semantic information about the parameter beyond what the schema provides, but it mentions 'real input' and 'signed retry' in the context of usage, which is not parameter-specific.

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

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

The description clearly states the tool's purpose: to check the claimability risk of a single GitHub bounty issue, returning an evidence-linked verdict (AVOID, CAUTION, VIABLE). It specifies the resource (GitHub bounty issue) and action (check), and distinguishes from the sibling tool rank_github_bounties, which is for 2-10 candidates.

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

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

The description explicitly states when to use this tool ('Use before coding one public GitHub bounty issue') and when not to ('For 2-10 candidates use rank_github_bounties'). It also explains the pricing structure (first call free, signed retry costs) and provides a sample URL, giving clear guidance on how and when to invoke the tool.

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 discloses important behaviors beyond annotations: it is read-only, never invokes tools, and includes pricing details for the first unsigned call vs. retry. Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description reinforces and extends this with concrete operational details. No contradiction.

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

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

The description is relatively concise and front-loaded with key points: pricing, usage, and read-only nature. It includes a workflow link for detailed steps. However, it mixes operational notes (pricing) with functional description, which could be more streamlined. Still, it is efficient and avoids redundancy.

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

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

Given the tool's complexity (5 required parameters, nested objects, output schema), the description provides sufficient context: purpose, when to use, behavioral constraints, and a link to detailed workflow. The output schema exists, so don't need to describe return values. The description is complete for effective usage.

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

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

Schema description coverage is 80%, so the schema itself documents parameters adequately. The description does not add specific parameter semantics (e.g., what baseline or current snapshots represent beyond the schema). It provides high-level context but relies on schema for details. Baseline 3 is appropriate given 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 states the tool's purpose: to compare baseline and current MCP tools/list snapshots for breaking schema or safety-hint changes. It uses specific verbs ('compare', 'check') and identifies the resource (MCP tools/list snapshots). The description distinguishes the tool from its siblings by focusing on drift detection, while sibling tools cover auditing, bounties, and GitHub actions.

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

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

The description provides explicit usage context: 'Use before accepting an MCP tools/list update...' and states what the tool does not do ('It never fetches or invokes tools'). It also mentions pricing for first call and retry. Though it doesn't explicitly list alternatives, the unique purpose is clear given sibling tool names.

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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint true), the description adds critical behavioral context: the free preview vs paid authorized retry ($0.07 USDC), and the read-only nature. No contradictions with annotations.

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

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

Three concise sentences that front-load key info: pricing preview, usage, alternative. No unnecessary words; 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?

Given the presence of an output schema (explaining return values), annotations covering safety, and full schema coverage, the description adds exactly what's missing: pricing, usage guidance, alternative tool, and a sample URL. Completes the picture for agent decision-making.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds 'using attempt and historical fingerprints' but 'attempt' is already documented in schema; 'historical fingerprints' is not a parameter and provides minimal extra meaning. No additional parameter details beyond schema.

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

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

The description clearly states the tool's purpose: to decide whether a failed GitHub Actions run should be retried or fixed. It specifies the resource (completed failed run) and distinguishes from the sibling tool diagnose_github_actions_run for root cause analysis.

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

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

Explicitly states when to use: for deciding retry vs fix on a single failed run. Provides clear alternative: use diagnose_github_actions_run for root cause. Also includes procedural guidance: read-only, never invent arguments, and mentions pricing/auth model for signed vs unsigned calls.

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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details beyond these: cost model for first call vs. authorized retry, and a read-only admonition. This provides useful context about authorization and pricing. No contradiction with annotations.

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

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

The description is several sentences long, covering cost, usage, sample, and sibling reference. While all information is relevant, the main purpose is buried in the third sentence. Could be more front-loaded for quicker comprehension. Adequate but not highly concise.

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

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

Given a single parameter, rich annotations, and an output schema (not shown but exists), the description covers key aspects: purpose, cost/auth model, read-only nature, sibling alternative, and a sample. It does not discuss error handling or limits, but for a simple tool this is sufficient. No significant gaps.

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

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

Schema coverage is 100% with a pattern and description for 'run_url'. The tool description adds a sample URL and clarifies that only canonical run URLs are accepted, but it adds minimal semantic value beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Use to find why one public GitHub Actions run failed and get redacted evidence plus concrete next actions.' It also distinguishes itself from the sibling tool 'classify_github_actions_flake' by directing users to that tool for retry-vs-flake decisions, making the purpose and scope 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 context on when to use the tool: first unsigned call is free and returns a preview, while an authorized signed retry costs $0.04. It also explicitly says 'Read-only; never invent arguments.' It mentions an alternative sibling for retry/flake classification, but does not provide exhaustive when-not-to-use guidance.

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

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

Annotations already mark as readOnly, idempotent, not destructive. Description adds behavioral details: first call returns free preview and exact quote, only authorized signed retry costs $0.40. Mentions partial failures. No contradiction with annotations.

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

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

Description is concise with multiple sentences covering key aspects: free preview, paid execution, usage range, sibling differentiation, read-only instruction, and a sample. No fluff; 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?

Given the tool has a single parameter, good annotations, and an output schema, the description sufficiently covers all needed context: input constraints, cost behavior, alternative tool for single issue, read-only nature, and expected output (verdicts, evidence, ranking). Includes a sample for reference.

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

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

Schema coverage is 100% with detailed description for each parameter. The tool description adds the requirement that URLs be distinct and duplicate rejection happens before payment, which goes beyond schema. However, the description does not add substantial new meaning beyond the schema's 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 the tool's purpose: to choose the best candidate from 2-10 public GitHub bounty issues with full verdicts, evidence, ranking, and partial failures. It also explicitly distinguishes it from sibling check_github_bounty by specifying the range of issues.

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

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

Provides explicit usage context: use for 2-10 issues, for one issue use check_github_bounty. Also explains the cost model (free preview, paid signed retry) and instructs never to invent arguments. Clearly defines when and how to use.

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