PromptGuard

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

Goes beyond the readOnlyHint/openWorldHint/destructiveHint annotations by disclosing the return shape (labeled placeholders), the guarantee that original text is never returned, and a billing note that each call consumes one Request on the plan. Missing only edge-case behavior such as input size limits or what happens when no PII is found.

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-loaded with the action and output contract, then a clearly separated usage paragraph; no filler sentences. The placeholder examples are slightly repetitive but earn their place by making the output format concrete.

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 tool is simple (one required string parameter) and an output schema exists, so return values needn't be spelled out — yet the description still summarizes them usefully along with the quota cost. Nearly complete; only input limits and no-PII-match behavior are left unstated.

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?

Only one parameter, and the schema already describes it fully at 100% coverage ('The text content to redact PII from'). The description adds no syntax, encoding, or size guidance for that parameter, so the schema carries the whole burden — baseline 3.

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 ('Redact PII ... from text') and enumerates the entity classes it targets, plus the exact output form ([EMAIL_REDACTED], etc.). It implicitly separates itself from promptguard_scan_text by asserting 'Never returns the original text', but never names the scan sibling or contrasts the two explicitly.

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?

A dedicated 'When to use' clause gives three concrete scenarios (pre-LLM prompt, customer messages, RAG ingestion), which is clear context for selection. It stops short of stating when not to use it or pointing to promptguard_scan_text for detection-only needs.

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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered elsewhere. The description adds real value by disclosing the mechanism ('pattern matching' on imports and client instantiations), which tells the agent results are heuristic and bounded to the five listed SDKs, but it says nothing about result shape or what happens with non-matching or mixed-language input.

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 tight sentences: capability and mechanism first, then triggers, with zero repeated field names or filler. Nothing could be removed without losing 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 one-parameter, read-only tool with an output schema and full annotation coverage, the description supplies what is needed to invoke it correctly. The remaining gap is routing: it never positions itself against promptguard_scan_text or points to promptguard_redact as the natural next step.

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 a single parameter at 100% schema description coverage, the schema already explains that 'code' is the content to analyze. The description adds no format, size, or language constraints for that input, so it sits at the structural baseline rather than exceeding it.

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 ('Analyze code for LLM SDK usage patterns') and narrows scope to a named vendor list plus import statements and client instantiations. The sibling promptguard_scan_text is not named, so the code-vs-text distinction must be inferred from the tool names rather than stated.

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?

An explicit 'When to use' clause gives three concrete triggers: after generating LLM-SDK code, during PR review, and for audit coverage gaps. It stops short of exclusions or naming promptguard_scan_text/promptguard_redact as the follow-on or alternative path.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally; the description's real addition is the cost disclosure that 'each call counts as one Request on your PromptGuard plan', which no annotation conveys. The rest of the behavioral content (decision, confidence, threat type, reason) restates what the existing output schema already returns, so the net value beyond structured fields is modest.

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 sentences, front-loaded with the purpose, followed by a clearly labelled usage clause — no filler. The enumeration of return fields is mildly redundant given the output schema exists, but it is short and reads as a useful summary rather than padding.

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 two-parameter tool with full schema coverage, annotations, and an output schema, the description covers purpose, quota cost, and usage context, which is most of what an agent needs. It stops short of noting any input-size limits or how to act on a 'block' decision, which would be the remaining 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?

Schema description coverage is 100%, including the content_type enum explaining prompt vs. response, so the schema carries the parameter semantics on its own. The description adds no guidance about how content_type affects scanning or about text size/format expectations, so baseline 3 applies.

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 gives a specific verb and resource ('Scan text') and enumerates the threat classes it detects (prompt injection, jailbreaks, PII leakage, toxic content), which is far more concrete than a generic 'check text'. It never names its near sibling promptguard_scan_code or promptguard_redact, so the agent must infer the boundary from those tools' own names rather than from this description.

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?

An explicit 'When to use' clause lists three concrete scenarios: reviewing user-facing prompts, testing LLM inputs, and pre-flight checking content before sending to a model. What is missing is any exclusion or routing rule, e.g. when to prefer promptguard_scan_code for code payloads or promptguard_redact when PII should be removed rather than flagged.

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?

Annotations already declare this is a read-only, idempotent, non-destructive, closed-world call, so the bar is lower, yet the description still adds real value by specifying what the payload contains and how it differs between the hosted server (plan) and the local CLI server (key type, proxy URL, providers). It stops short of saying whether the call makes network requests or what it returns when unconfigured, which is the only remaining behavioral gap.

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 front-loaded sentences: the capability first, then the parenthetical scope of returned fields, then a labeled usage line. Every clause carries information and nothing is repeated from the schema or annotations.

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 is present, so return-value documentation is not the description's job, and annotations fully cover the safety profile. The description supplies the one thing structured fields cannot: the distinction between hosted and local server reporting.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Schema coverage is 100% and the empty object schema is unambiguous.

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 gives a specific verb-plus-resource: show whether PromptGuard is set up and signed in, plus version and account/configuration details. The resource is categorically distinct from the sibling scan/redact tools, so an agent can route between them without opening either schema.

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 has an explicit 'When to use' clause naming two concrete situations: verifying configuration and confirming the running version. There are no when-not conditions or named alternatives, but no sibling overlaps with status checking, so the guidance is effectively sufficient.

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