scan_text

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

Annotations only declare the safe-read profile (readOnly, idempotent, non-destructive); the description adds substantial behavior beyond them: placeholder/variable forms are skipped, 'secret-sentinel: ignore' and 'pragma: allowlist secret' lines land in 'suppressed' rather than findings, and secret values are always redacted to at most 4 chars. It also discloses truncation semantics (truncated flag, total_findings, counts_by_severity).

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?

Front-loaded with the one-line purpose, then structured Args/Returns sections; every clause is informative rather than filler. The 33-detector enumeration is long, but it defines detection coverage an agent would otherwise have to guess, so it mostly earns its 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?

There is no output schema, and the description compensates by specifying the return shape (clean, findings with file/line/pattern/severity/redacted/advice, files_scanned, summary) plus the redaction guarantee. Suppression, truncation and parameter behavior are all covered, so nothing needed to call this correctly is missing.

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 carries the full burden and does: text is 'raw text to scan (code, config, diff output, logs...)', source_name is the label populating each finding's 'file' field, and max_findings explains the default 200, that 0 means no limit, ordering is most-severe-first, and which extra fields appear when capped.

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?

States a specific verb and resource ('scan a snippet of text or code for exposed secrets') and immediately scopes the input class. Against siblings scan_file, scan_directory and scan_git_staged, the in-memory text-snippet scope makes the boundary clear without opening any 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?

Usage is only implied: the tool takes raw text, so the agent can infer it is for content already in hand rather than a path. It never states when to prefer scan_file/scan_directory over this one, nor any exclusions or prerequisites.

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