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

With comprehensive annotations (readOnlyHint, idempotentHint, destructiveHint) already declaring safe read-only/idempotent behavior, the description adds important nuance: pattern-based detection, never echoes matched values, clean result is not proof, errors return structured messages rather than protocol errors. This provides behavioral context beyond annotations. The only small gap: does not mention rate limits or auth requirements.

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 packed with useful information but could be slightly more structured. Front-loaded with purpose, then free cost, then behavior/limitations, then error handling/safety. Every sentence adds value. Minor length is justified given the number of important behavioral clarifications.

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 complexity (security tool with caveats), single non-enum parameter, and the presence of an output schema, the description covers: purpose, input format, output structure, limitations, error behavior, safety properties, and alternatives. Could be improved by listing a concrete example value for the type field categories.

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 single parameter, so the schema already documents the parameter. The description adds value by providing a concrete example input/output format, stating what kind of string to pass (file, diff, or config contents), and clarifying the result structure. This goes beyond the schema's minimal type description.

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 scans text for accidentally-committed machine credentials and private-key material, specifying verb 'scan', resource 'text', and purpose. It distinguishes from sibling 'security_deep_dive' by explicitly noting this is not a general security review.

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 when-to-use context (scanning for leaked credentials), what it does not replace (not proof, needs human confirmation, not a general security review), and explicitly names the alternative sibling tool 'security_deep_dive'. Also tells the agent it is safe to retry after correcting input errors.

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