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

Goes well beyond the readOnly/idempotent/openWorld annotations: discloses that it only issues GETs and 'never starts, aborts or re-bills a run', latency (<1 s) and poll cadence (10-30 s), that there is no abort tool and aborts happen in the Apify console, cost/auth requirements, terminal status semantics, and named error codes including retryability. This is exactly the extra context annotations cannot carry.

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 labeled sections (WHAT/WHEN TO USE/WHEN NOT TO USE/BEHAVIOR/COST/RETURNS/PARAMETERS/EXAMPLE) that make it scannable, and every block earns its place. It is nonetheless long and verbose relative to a 3-parameter read tool, with some redundancy between WHAT, RETURNS and PARAMETERS.

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?

Despite an output schema existing, the description still supplies the status enumeration, the finished-semantics for terminal states, partial-results-while-RUNNING behavior, the full error set, and a worked example. Nothing an agent needs to poll correctly is missing.

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 100%, so the baseline is 3, but the description adds real semantics: runId's provenance ('comes from guard_text run.run_id'), page ordering ('in write order'), and the pagination contract ('keep calling with nextOffset until it is null and finished is true'). It doesn't restate limit/offset types, which the schema already covers.

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 ('Read-only follow-up to guard_text... returns the run status and one page of its result rows') and immediately scopes what it does not do ('It scans nothing itself'). An agent can distinguish it from guard_text, restore_placeholders and list_detectors without opening any 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?

Explicit WHEN TO USE ('only after guard_text returned run.run_id... poll until run.finished is true') and WHEN NOT TO USE with named alternatives ('to scan or redact (guard_text...)... To restore placeholders... restore_placeholders'). It also states a hard boundary ('Cannot read runs of other Actors'), leaving nothing to inference.

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/idempotentHint/destructiveHint=false, and the description adds the operational context that matters: it is a paid Apify Actor run with per-document and per-finding pricing, error rows are free, a 1000-document cap, a 280s wait, and exactly what each call bills. It also discloses that placeholder_map carries ORIGINAL sensitive values and that numbering restarts per call, which is the kind of safety-relevant behavior structured fields cannot express. (Minor tension: 'random salt per run' in hash mode means repeated calls differ, but this concerns return values rather than state mutation, so it does not amount to a contradiction of idempotentHint.)

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?

Headers (WHAT/WHEN TO USE/WHEN NOT TO USE/COST/RETURNS/EXAMPLE/PARAMETERS) make a long body navigable and front-load the identity of the tool. The length is largely justified by 13 parameters and a paid pipeline, but there is some repetition (the restore 'same output for free' caveat and billing behavior are restated more than once), which keeps it from a 5.

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 13-parameter, nested-object, paid tool with an async path, the description covers everything an agent needs: cost model, batching limits, the waitForFinish=false polling handoff to get_run_results, error-row semantics, and the round-trip contract with restore_placeholders. An output schema exists, yet the RETURNS note still flags the critical distinction between masked findings and the original-value placeholder map.

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?

Although schema description coverage is 100%, the description adds the cross-parameter logic the schema cannot: at least one of texts/documentUrls is required despite both being optional, mode gates which other fields apply, returnPlaceholderMap only functions with redact+placeholder, detectNames/detectAddresses must be true before PERSON/LOCATION/STREET_ADDRESS can appear in entityTypes, and entityTypes filters post-detection (unknown names silently match nothing). This meaningfully exceeds the 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 WHAT section names a specific verb (scans/detects/redacts) and resource (text documents and public URLs) and enumerates the entity classes it covers. It explicitly positions itself against siblings ('the only tool in this server that inspects content') and routes to list_detectors, restore_placeholders, and get_run_results by name, so an agent can distinguish it without opening any 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?

Dedicated WHEN TO USE and WHEN NOT TO USE blocks name the exact scenarios (before sending prompts/tickets/logs to an LLM) and the precise alternatives for each edge case: restore_placeholders for putting originals back, list_detectors for entity types, get_run_results to avoid re-billing. It even calls out non-goals (no OCR, not for email deliverability).

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial non-obvious context: the catalog is version-pinned to the server rather than fetched from the Actor, so newer Actor builds may support unlisted types; it is free and needs no APIFY_TOKEN. This is exactly the kind of behavioral detail annotations cannot express.

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?

Heavy but front-loaded and labelled (WHAT / WHEN / WHEN NOT / BEHAVIOR / COST / RETURNS / PARAMETERS / EXAMPLE), so an agent can scan to the needed section. The RETURNS block is somewhat long for a tool that has an output schema, though its guidance on stripping parenthesised notes and the 'opt-in' flags is genuinely actionable 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 zero-parameter, read-only catalog with a full output schema, the description supplies everything else an agent needs: cost, token requirements, version-skew caveat, and how to translate returned entries into valid guard_text arguments. Nothing required to call it correctly is missing.

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?

Zero parameters, so the baseline is 4; schema coverage is 100% and the description confirms 'none; call with {}'. It adds no per-parameter meaning because none exists, but the call convention is stated unambiguously.

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 resource — the catalog of PII/secret entity types and redaction styles — and immediately disambiguates it from scanning ('Reference data, not a scan... Inspects no text'). The distinction from guard_text is explicit, so an agent can route correctly 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?

Dedicated WHEN TO USE and WHEN NOT TO USE sections name the concrete triggers (choose entityTypes/redactionStyle, estimate cost, explain coverage) and the anti-triggers (checking text → guard_text; undoing redaction → restore_placeholders; not needed before every guard_text call since defaults apply). Alternatives are named, not implied.

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?

Goes well beyond annotations: discloses no network call, the map never leaves the machine, millisecond latency, size limits (1000 texts / 5,000,000 chars), cost (free, no APIFY_TOKEN), what cannot be restored (masked/hashed), and a critical safety caveat that output contains original sensitive values and must not be sent back to the LLM. Annotations already say readOnly/idempotent/non-destructive; description adds local-only execution and data-handling warnings.

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 WHAT/WHEN TO USE/WHEN NOT TO USE/BEHAVIOR/COST/RETURNS/PARAMETERS/EXAMPLE headings make it scannable. Despite length, each section carries distinct, actionable content with no filler; the example is compact and illustrative.

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?

Covers everything an agent needs: correct sequencing, alternatives, local-only guarantee, limits, cost, return fields (replacements, unknown_placeholders), the INPUT_TOO_LARGE error, and the sensitive-output handling rule. With an output schema present, the description still adds the 'do not send back to LLM' caveat that the schema cannot express.

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 100% and the description still adds meaning: placeholderMap must come from the exact redact call that produced the placeholders, numbering restarts per call, only [UPPERCASE_TYPE_N] keys within brackets are used, matching is exact, case-sensitive, and single-pass, and a rewritten placeholder without brackets is not restored. These are behavioral semantics not captured by the 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 WHAT section states a specific verb (restore/put back), resource (original values into texts with placeholders), and positions it as 'the last step of the round trip and the default way to restore'. It explicitly names the counterpart guard_text and its mode, so an agent can distinguish it from siblings without opening schemas.

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?

Provides explicit WHEN TO USE (after guard_text redact with placeholder style, before showing user), WHEN NOT TO USE (finding/redacting PII -> guard_text, listing types -> list_detectors), and a preference rule (prefer over guard_text mode=restore because free and local). This is textbook when/when-not/alternatives guidance.

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