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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It lists the types of PII detected, but does not disclose the output format (e.g., whether it returns a boolean, list of matches, or redacted text) or any side effects. Without an output schema, this ambiguity is a significant gap for a detection tool.

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 a single, well-structured sentence that front-loads the purpose ('Detect PII') and immediately lists supported types. Every word contributes meaning, with no fluff or redundancy. It is appropriately concise for a simple one-parameter tool.

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 has no output schema and no annotations, the description should have explained the return behavior (e.g., list of matches, confidence scores, or a simple flag). It does not. The description also lacks guidance on usage vs. siblings. While the tool is simple, the missing output information leaves it incomplete for an agent to understand what to do with the result.

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?

The schema already covers the 'text' parameter (100% coverage), providing a baseline of 3. The description adds value beyond the schema by enumerating specific PII types, giving the agent a clearer understanding of what constitutes PII and what the tool will scan for. This enriches the parameter's semantic meaning.

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 uses the specific verb 'Detect' and clearly identifies the resource ('PII in a text string') with enumerated categories (email, phone, SSN, etc.). This clearly distinguishes it from sibling tools like redact_pii, which implies a different action (redaction), and check_hallucination/check_safety which target other concerns.

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 implies usage by stating it detects PII, but does not explicitly say when to use it vs. alternatives like redact_pii. The existence of sibling tools provides context, but there is no explicit when-to-use or when-not-to-use guidance. The purpose is clear enough that an agent could infer, but it lacks direct exclusions.

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