mask_text

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

With no annotations, the description carries the full load, and it does disclose genuinely useful behavior: arguments are provider-visible, masking happens locally, and mask_numbers defaults to preserving code numbers. It is silent on whether masking is reversible, what session_id does (conspicuous given create_privacy_session/clear_privacy_session siblings), and what the masked output looks like beyond the strategy names.

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-loads the purpose and rationale before the parameter glossary, and the per-parameter lines are terse with no filler. Some lines are comma-spliced into run-ons that slightly blur which parameter each clause belongs to.

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 values need not be described, and the mode/strategy vocabulary is covered. Still, for an 11-parameter tool with zero annotation and zero schema-description coverage, leaving session_id and sql_dialect unexplained is a meaningful gap an agent would have to guess around.

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 0%, so the description must compensate, and it does partially — it names eight of eleven parameters and enumerates the allowed mode and strategy values, which the schema does not. But it never explains what the values mean in practice (e.g., entities_only vs aggressive, bracket vs hash vs pseudoword), and session_id and sql_dialect go completely undocumented.

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 ("Mask text") plus the operational rationale that tool arguments are provider-visible, so an agent immediately knows the point of the call. It does not differentiate itself from the sibling mask_code, which is a real ambiguity given this tool has a code_aware mode and a code_language parameter.

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 line "pre-mask confidential data locally" gives a clear motivating context for when to call it. However, no exclusions are stated, and the obvious alternative — mask_code, listed as a sibling — is never acknowledged, leaving the code-vs-text routing to inference.

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