ai-guardrails

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

No annotations are provided, so the description must carry the full burden of disclosure. It states 'heuristic scoring' and mentions the output (score 0–1 and risk level), but it does not explain what 'risk level' entails, how scoring works, or any limitations of the heuristic approach. This leaves significant behavioral ambiguity for an agent.

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, front-loaded sentence that efficiently communicates the action and output. No redundant or irrelevant information is included, making it highly concise and well-structured.

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's simplicity (one parameter and no output schema), the description provides a basic overview of functionality and output. However, it lacks details on interpreting the risk level, any edge cases (e.g., empty input), or how the heuristic scoring behaves. This is adequate for a simple tool but not fully complete.

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 has one parameter 'text' with zero description coverage, and the tool description does not elaborate on the input. It only implies the text should contain hedge phrases, but it does not specify expected format, length, or sample examples. The description adds minimal value beyond the raw schema.

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 a specific verb 'scoring' and identifies a clear resource ('LLM hedge phrases') with a defined purpose (correlate with hallucinated outputs). It distinguishes this tool from siblings like check_safety and detect_pii, which target different risks. The output specification (score 0–1 and risk level) further clarifies its function.

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 does not provide any guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or comparisons with sibling tools such as full_check or redact_pii. The only implicit usage is that it is for hallucination scoring, but no explicit context is given.

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

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

The description discloses the detection mechanism (weighted keyword detection) and the return format (0–1 score with a verdict), which adds behavioral context beyond the unannotated tool. However, it doesn't mention potential edge cases, thresholds, or side effects.

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?

Two short sentences with no filler. The first sentence explains the purpose and method, the second describes the output, making it efficient and well-structured.

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 simple tool with one parameter and no output schema, the description covers purpose and return values, but it lacks usage context, such as when to prefer this tool over siblings, and omits any behavioral caveats. Hence it's minimally adequate.

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 has no field descriptions and 0% coverage, so the description must clarify the `text` parameter. It implicitly indicates that `text` is the content to be checked, but lacks details such as length limits or encoding requirements.

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?

Clearly states 'Check text for harmful content' with a specific verb and resource, distinguishing it from sibling tools like check_hallucination and detect_pii. The addition of 'using weighted keyword detection' clarifies the method.

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?

No explicit guidance on when to use this tool versus alternatives like full_check or detect_pii. The description implies its use for safety checking but does not mention exclusions or alternative scenarios.

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

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.

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

With no annotations, the description must disclose behavioral traits. It covers the default and configurable checks, but does not explicitly state that the operation is read-only, what the output format is, or how errors are handled. The term 'checks' suggests non-mutating, but this is implicit.

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 concise, just two sentences, and front-loads the specific action. Every clause adds useful information about the tool's behavior, with no redundant filler.

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's simplicity and lack of annotations/output schema, the description adequately explains how to configure checks but leaves out expected return values and fails to mention the role of the 'text' parameter. It is minimally complete but has clear gaps.

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 description adds meaningful context for the 'checks' parameter by listing valid options and the default. However, it provides no explanation for the required 'text' parameter, and with 0% schema description coverage, the description should compensate for both parameters but only does so partially.

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 it runs PII, safety, and/or hallucination checks in one call, using the specific verb 'Run' and resource 'checks'. It distinguishes itself from sibling tools that handle individual checks by emphasizing the combined, single-call nature.

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?

It explains the default check combination and how to specify a custom set via the checks parameter, which implies when to use this tool (when combining multiple check types). However, it does not explicitly contrast this with using the individual sibling tools for single checks.

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

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

With no annotations, the description partially compensates by explaining the output format for each mode (mask vs. tag). However, it does not disclose whether the input text is returned as a new string, whether modification occurs in place, or any limitations of PII detection. The behavioral disclosure is adequate but not rich.

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 only two sentences, front-loaded with the main action, and every word adds value. It avoids redundancy and is appropriately sized for the tool's complexity.

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?

The description covers the core behavior and modes but does not explicitly state the return value (e.g., 'returns the redacted text'). It also does not reference sibling tools for comparison, which would enhance completeness. Given the tool's simplicity, the description is nearly complete but has a notable gap.

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 must compensate. It provides meaningful semantics for the 'mode' parameter with concrete examples, which goes beyond the enum values. The 'text' parameter's purpose is self-evident from the tool name and description, so it is sufficiently explained.

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's function: 'Redact PII from text' with a specific verb and resource. The mode details further clarify the two distinct behaviors, distinguishing it from sibling tools like detect_pii.

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 does not provide any guidance on when to use this tool versus alternatives such as detect_pii or full_check. It only explains the modes, not the appropriate context or conditions for invoking the tool.

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