scan_prompt

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

Annotations already mark it read-only and idempotent, but the description goes well beyond them: runs fully offline, no network call, no API key, no stored credentials, no writes outside the process, no jurisdiction filter, and it does not classify risk tiers or call remote APIs. This is exactly the extra behavioral context annotations cannot convey.

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?

Purpose and scope are front-loaded in the first two sentences, which is the right structure. It loses a point for run-on colon/dash chaining and for repeating the offline/no-network point three separate times.

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?

An output schema exists, so return shape need not be documented, yet the description still signals the SAFE / RISK_DETECTED outcome and that findings are cited. For a one-parameter scanner every call-time decision an agent needs — when, with what input, under what exclusions — is covered.

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 single parameter's schema description already states the non-empty, pre-generation, not-already-produced-output rules. The description largely restates that same constraint ('must be a non-empty candidate prompt about to be sent to a model (empty/whitespace is rejected)') rather than adding syntax, format, or size guidance, so baseline 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 opening states a specific verb and resource — scanning an AI prompt against the offline TrustLint regex corpus — and immediately delimits what it is not (not the hosted policy engine, not a system classifier). It is trivially distinguishable from list_rules and check_compliance without opening either schema.

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?

Explicit timing rule ('Use when the prompt is about to be sent') plus an explicit exclusion and named alternative ('for post-hoc evaluation of already-produced text, use check_compliance'). The pre-generation-only constraint is stated twice, leaving nothing to inference.

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