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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds context beyond that: it clarifies the tool returns rules (not actual scanning), and it includes a detailed privacy disclosure about how arguments are stored (hashed keys, no IPs, no personal data). This provides meaningful behavioral transparency that the annotations alone do not cover.

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 longer than ideal but well-structured: purpose first, then usage guidance, then privacy. The privacy paragraph is necessary given the tool's context, though it could be condensed. The key operational instructions are front-loaded and clear, so it earns a 4 for structure despite verbosity.

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 has no output schema, so the description carries the burden of explaining what is returned. It explains the rules' nature, how to apply them, what to send to audit_stack, and the 'unknown' fallback. This is sufficient for an agent to use the tool correctly; the only minor gap is lack of detail on the exact format of returned rules, but that is not critical for 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 100% – the single 'vendors' parameter is documented as 'Only these vendors, by id or name (default: all).' The description does not add substantial parameter-level detail, but it reinforces the concept of vendor names and the ~100 vendor count. Baseline of 3 is appropriate given the schema already covers 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 opens with a specific statement of what the tool does: provides detection rules for paid services (package names, env var patterns, config files, API hosts, feature patterns for ~100 vendors). This is a clear verb+resource with concrete scope, and it distinguishes itself from sibling tools by describing the local application and the audit_stack output target.

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 explicit usage direction: apply rules locally and send only vendor/feature names to audit_stack, never code or secret values. It also notes that names without rules come back under 'unknown.' While it doesn't explicitly compare to alternatives, the workflow guidance is concrete and actionable.

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