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

Annotations already mark the tool read-only and idempotent, and the description adds valuable context: the original text is not modified, no sanitized representation is returned, processing is local, and response modes change the output. No contradiction with 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 is well-structured into overview, usage guidance, and return contract. It is slightly longer than minimal but every sentence earns its place, and the core purpose is front-loaded.

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 read-only analysis tool, the description is complete: it covers what it does, when to use it, alternatives, side-effect behavior, response modes, and return shape. The output schema also exists, so the description does not need to over-explain returns.

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%, so the baseline is 3. The description adds extra value by clarifying response_mode behavior and the policy_not_found error case, going beyond the schema without repeating 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?

The description opens with a specific verb and resource: 'Inspect text locally and report detected sensitive content without producing sanitized output.' This immediately distinguishes it from redaction/export tools and makes the tool's purpose unmistakable.

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 explicitly says when to use the tool ('when you need to understand what PII, secrets, or credentials are present... but do not need redacted text') and names alternatives for other needs: prepare_for_external_ai, create_safe_copy, and restore_text. This gives an agent clear routing guidance.

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 goes well beyond the annotations by disclosing concrete side effects: writes to SECUREDACT_SAFE_COPY_DIR, never modifies the supplied content, never overwrites existing files, requires a bare '.txt' or '.md' filename, and blocks/reports 'blocked' on unconfigured directory, invalid filename, or policy failure. It also specifies the return shape.

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?

Three short paragraphs are used: purpose in the first sentence, usage guidance in the second, and side effects/return in the third. Every sentence earns its place and the description is front-loaded with the primary action.

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 side-effecting nature of the tool, the description covers the operation, side effects, blocking/failure conditions, and return format. Combined with the rich output schema and annotations, an agent has all necessary information to invoke it correctly and safely.

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 input schema already documents all three parameters with detailed descriptions (100% coverage), so the description's restatements such as 'content is not modified' and 'bare target filename' add little new meaning. The baseline of 3 applies; the description does not need to compensate for missing schema coverage.

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 states a specific verb and resource: 'Sanitize text locally and write the approved result to a new file in the Safe Copies directory.' It explicitly contrasts this with in-memory sanitization and names sibling tools for alternative use cases, so an agent can distinguish it immediately.

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 gives an explicit 'Use this when' condition (need a sanitized on-disk copy for storage, handoff, or archival) and names three sibling tools with their respective conditions: prepare_for_external_ai for sanitized text only, analyze_text for inspection-only, and restore_text for reversing a prior session. This is clear decision guidance.

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, idempotentHint=true, and destructiveHint=false, so the agent knows the safety profile. The description adds valuable context: it explicitly states that the tool does not transmit text externally and that processing is local. It also discloses that unknown policy names return a policy_not_found error and describes the response structure (status field with values). This goes beyond annotations to explain operational behavior.

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 focused and well-structured. It opens with a clear directive and then alternates between contrasts and return-format details. Every sentence adds value, and the return format is clearly specified. It loses one point for being slightly longer than necessary, but it is still quite efficient with no fluff.

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 moderately complex with 4 optional parameters and an output schema, so the description does not need to explain return values in detail. It covers key aspects: what it does, when to use it, distinctions from siblings, policy parameter semantics, and the response_mode conditional field. It does not mention rate limits or auth, but given the annotations indicate a safe read-only operation and the schema is fully documented, a 4 is appropriate for completeness.

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%, so the baseline is 3. The description adds significant parameter semantics beyond the schema: it explains the 'policy' parameter with default value and common values, warns about unknown policies causing errors; it clarifies 'response_mode' values including 'restore_capable' and mentions the conditional 'restoration_session' field in the output. It also explains 'language' options globally. This enriches parameter understanding.

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 begins with a clear directive: 'Use this before sending user-supplied or potentially sensitive text to an external AI service.' It specifies the action ('inspects and sanitizes'), the resource ('text'), and the local scope ('does not transmit the text externally'). It names its siblings and contrasts with them, making it easy to distinguish from alternatives like analyze_text and redact_text.

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 explicitly states when to use it ('before sending... to an external AI service') and what it is not for. It enumerates alternative tools by name and explains their different purposes: 'analyze_text for inspection-only classifications, redact_text for the lower-level compatibility path, create_safe_copy when a sanitized file is required, and restore_text only to reverse a prior local session.' This gives clear routing guidance.

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 adds valuable behavioral context beyond the annotations, noting that normal modes return the same approved result as prepare_for_external_ai and that 'legacy' mode returns sensitive local-review details under a deprecation_code and must never be sent externally. This complements the readOnlyHint and idempotentHint annotations without contradiction.

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 organized and front-loaded with the most critical routing guidance: prefer prepare_for_external_ai. Each paragraph earns its place, covering normal modes, legacy mode caveats, and return behavior without unnecessary 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 that an output schema exists and the annotations cover read-only, idempotent, non-destructive behavior, the description provides sufficient context for selecting and invoking the tool correctly. It explains when to use it, what modes exist, and the sensitive nature of legacy output, leaving no critical gap for an agent.

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%, so the input schema already documents all parameters well. The description reinforces the response_mode semantics and legacy sensitivity but does not add substantial new meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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 identifies redact_text as a lower-level redaction entry point and contrasts it with prepare_for_external_ai, stating that it performs the same local sanitization in normal modes. It also specifies the distinct 'legacy' mode purpose, making its role unambiguous relative to sibling tools.

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 explicitly tells agents to prefer prepare_for_external_ai for normal outbound workflows and to use redact_text only when needing the lower-level compatibility path or 'legacy' mode for local review. This gives clear when-to-use and when-not-to-use guidance, directly addressing the main alternative.

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 carry almost no signal (all hints false), so the description bears full responsibility for behavioral disclosure, and it delivers: local-only processing, that restored values are raw PII/secrets never to be transmitted, that the mapping form bypasses the session vault, and the exact response contract (status, restored_text, reason_codes). This goes well beyond what the annotations provide and directly informs safe invocation.

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 purpose is front-loaded and the structure flows from what-it-does to when-to-use to security boundary to return format. It is somewhat longer than necessary — the mapping/trusted_local_review constraint is stated both in the description and in the schema — but the repeated security warnings are justified given the sensitivity of restored data.

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?

With an output schema present and 100% parameter coverage, the description needs only to add selection and safety context, which it does thoroughly. An agent has everything needed to decide when to call it, which parameters to supply, what security posture to assume, and what the response will contain.

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%, so the baseline is 3; the description raises it by explaining the two mutually exclusive invocation forms (restoration_session vs mapping + trusted_local_review) and adding the security consequence of the mapping form. It adds semantic cohesion among the parameters that the schema's individual field descriptions do not provide.

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 opens with a specific verb and resource ('Reverse a prior SecuRedact protection step') and clearly frames the operation as trusted-local reconstruction. It also differentiates itself from the key sibling by explicitly naming prepare_for_external_ai as the tool for the opposite direction, so an agent can disambiguate 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?

Usage conditions are explicit: call it only after receiving a restoration_session from a prior SecuRedact step, never to sanitize data, and never on text not previously protected. It names the alternative tool (prepare_for_external_ai) and states the exact precondition ('restore_capable'), leaving no ambiguity about when this tool applies.

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, idempotentHint=true, destructiveHint=false. The description adds useful context beyond those: side effects ('reads a file from local disk and never transmits it'), defense ordering ('Sensitive paths and escapes are blocked before any file content is read'), and return safety ('sanitized_text is safe to forward'). This aligns with and complements the 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 is front-loaded with the core purpose, then usage guidance, then side effects. It is moderately sized and each sentence earns its place, though the three-paragraph structure could be tightened slightly 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?

There is an output schema, and the description still gives a concise summary of return fields (status, path, sanitized_text) and edge cases (blocked/ok). It covers when to use the tool, alternatives, side effects, and defense guarantees. With schema and annotations carrying the rest, nothing an agent needs to invoke or react to this tool 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 description coverage is 100%, with each parameter (path, policy, max_bytes) already described with details about defenses and defaults. The description adds no additional parameter-level semantics, so the baseline of 3 is appropriate—it doesn't degrade or enhance schema-provided 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 states a specific verb+resource: 'Safely read a local file and return only its sanitized (PII/secrets removed) text.' It explicitly differentiates from siblings by naming prepare_for_external_ai and create_safe_copy, so an agent can distinguish it 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?

It gives explicit when-to-use: 'Use this when you must ingest a local file's contents for use with an external AI but want path-traversal, size, and binary defenses plus sanitization applied first.' It also provides concrete when-not and alternatives: 'If the content is already in memory, use prepare_for_external_ai; for a sanitized file on disk, use create_safe_copy.'

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