De-identify Clinical Text (PHI Removal)

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

Annotations indicate read-only and non-destructive behavior; the description adds valuable specifics about what entity types are detected (MRNs, ages, phone numbers) and the exact replacement format ('[NAME]', '[DATE]'). The HIPAA compliance claim adds important regulatory context not found in annotations.

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 consists of two efficiently structured sentences with zero redundancy. The first states the core operation; the second details the specific PHI categories, replacement patterns, and compliance standard. Every clause conveys distinct, necessary information.

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?

For a single-parameter text processing tool without an output schema, the description adequately covers the transformation logic (what gets replaced and with what). It would be marginally improved by explicitly stating that the tool returns the anonymized string, though this is reasonably implied by the 'replaces... with' phrasing.

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?

With 100% schema description coverage, the input parameter 'text' is fully documented in the schema itself. The description implies the content should be clinical text but does not add additional semantic constraints, format requirements, or examples beyond what the schema provides, warranting the baseline score.

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 specific verbs ('Detect and mask') and clearly identifies the resource ('Protected Health Information in clinical text'). It effectively distinguishes itself from sibling code-lookup tools (get_code, search_codes, etc.) by specifying the domain is clinical text de-identification rather than medical coding.

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 provides clear context for when to use the tool ('HIPAA-compliant de-identification') and lists specific entity types handled (names, dates, SSNs, etc.). While it doesn't explicitly name alternatives to avoid, the domain focus makes the appropriate use case unambiguous.

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