check_payment_page_scripts

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

The description thoroughly discloses behavioral traits beyond annotations (none provided): it describes the default summary response shape with by_severity counts, by_rule histogram, top findings, and a pagination cursor. It mentions caching with a 10-minute TTL and server caps on limit (LIMIT_EXCEEDS_PAGE_SIZE). It also notes framework awareness (net/http, gin, echo), which is critical for accurate scanning.

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 dense but efficient, front-loading the core action and violations. It is a single paragraph that could be broken into sections, but it is not excessively long (about 150 words). Every sentence provides valuable information, with minimal 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 (8 parameters, output schema present, diverse detection rules), the description is complete. It covers detection rules, PCI DSS mapping, framework support, response shapes, pagination, caching, server caps, and filter behavior. No gaps are evident.

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?

Input schema has 100% parameter description coverage, so the description only adds marginal value, such as clarifying default exclude patterns and the effect of min_severity/rule_filter on response shape. Since the schema already documents each parameter adequately, a 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 it scans Go source files and HTML templates for payment page script security violations (PCI DSS 6.4.3, 11.6.1). It lists specific detection types (missing CSP headers, unsafe-inline/unsafe-eval, external scripts without SRI, inline scripts without nonce), making the tool's purpose highly specific and distinct from sibling tools like check_auth_strength or check_encryption.

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 advises preferring this tool for mixed queries and explains how response shape changes with filters (min_severity / rule_filter forces flat response). It provides guidance on pagination (follow cursor) and filter usage. However, it does not explicitly state when not to use this tool or name alternatives, though the sibling list implies other tools for different checks.

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