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

Annotations already flag this as not read-only, open-world, and destructive, but the description adds crucial behavioral context: the table re-identifies the document, must be kept with the user, must never be sent alongside the redacted PDF, is written to a file on this machine, and must never be opened or read directly. These are non-obvious safety and handling constraints that materially change how an agent should behave.

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 compact and front-loaded: it first says what is downloaded and in what format, then states the precondition, then the re-identification warning and next-step guidance. Each sentence earns its place.

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?

Although there is no output schema, the description explains the return artifact (a CSV file written to disk, one row per tag) and how to use it safely. It covers the precondition, the destructive/sensitive nature of the output, and the follow-up tool, making the definition complete enough for correct invocation.

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 both document_id and output_path are already well documented in the schema, including the default filename and no-overwrite behavior. The description does not add further parameter-specific semantics beyond mentioning that the file path should be passed to restore_names.

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 ("Download the correspondence table of a document redacted with mode pseudonymize") and explains the contents (one CSV row per tag with placeholder, rename, category, original text). This clearly distinguishes it from siblings like download_redacted and restore_names.

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 limits use to pseudonymized documents with status "redacted" and explains that redact-mode documents have no table. It also routes the agent to restore_names when names need to be put back, leaving little ambiguity.

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?

Beyond the annotations, it discloses the status gate, retention semantics ('ephemeral' means the original is already gone; output kept for the account's retention window, 14 days by default), and mode-dependent return content (document_text, document_text_path, tag -> original table). That is exactly the operational context an agent needs before calling.

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?

It is front-loaded with the core action and precondition, then layers on retention and pseudonymize details. The third sentence is dense but each clause carries distinct information; only the parenthetical about redact_pdf_and_wait feels slightly appended.

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 no output schema, and the description compensates by explaining what the result contains in pseudonymize mode and how long files persist. Combined with the status prerequisite, an agent has everything needed to call it correctly and interpret the response.

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 both parameters are already documented in the schema, and output_path receives no discussion in the description. The description does add provenance for document_id, but that only matches rather than exceeds the schema's own wording.

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 ('Download the finished redacted PDF for one document') and pins down the identifier source ('using the document id from redact_pdf or get_job_status'). This clearly separates it from siblings like download_correspondence and redact_pdf_and_wait.

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 precondition ('Only works once that document reports status "redacted"') and names an alternative with its purpose ('download_correspondence ... redact_pdf_and_wait fetches both for you'). When-to-use and when-to-use-something-else are both spelled out.

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 readOnlyHint annotation already communicates that this is a safe read operation. The description adds non-obvious context about account plan quota and credit packs, and explains that 'out of pages' failures are permanent quota problems rather than transient errors. This is useful behavioral context beyond the annotations, though it does not describe the exact return payload.

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 concisely written and front-loads the core purpose before the recommended usage timing. The second paragraph about redaction billing and quota errors is somewhat tangential to what this tool itself does, but it is still relevant context and does not make the description bloated.

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, zero parameters, and no output schema, the description covers the essential what, when, and error-handling context. It does not enumerate the specific fields returned in the account status response, but the stated purpose ('see which account it belongs to') provides enough for an agent to invoke the tool correctly for its intended use.

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 has zero parameters, so there are no parameter semantics for the description to clarify. According to the baseline for zero-parameter tools, a score of 4 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 states a specific verb ('check') and resource ('API key and account'), and clearly conveys the tool's diagnostic purpose. It is easily distinguishable from the sibling redaction and job-status tools because it is explicitly framed as a pre-batch validation step.

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 gives explicit when-to-use guidance: call this before a large batch to fail fast on a bad or missing key rather than after uploading. It also provides an exclusion for retrying 'out of pages' errors, which is a clear error-handling instruction that helps the agent decide when not to retry a related call.

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 explaining the full status progression, which statuses are terminal, and the recommended polling behavior. It also discloses that each document reports its own status, page_count, and error_message, giving the agent a realistic model of the tool's 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 front-loaded with the core purpose, followed only by high-value behavioral details: statuses, final states, polling advice, and per-document reporting. Every sentence contributes useful information without repetition or 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?

For a single-parameter status-check tool with no output schema, the description is remarkably complete. It explains the status model, terminal states, polling cadence, and the per-document outcome fields, so an agent has enough context to call the tool and interpret results correctly.

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 describes job_id as 'The job_id returned by redact_pdf,' so coverage is complete. The description does not need to add parameter-level detail and does not repeat it; this is an acceptable baseline when the schema carries the 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 opens with a specific verb and resource: 'Check a redaction job's progress.' It clearly identifies the tool's function and distinguishes it from sibling tools like redact_pdf, redact_pdf_and_wait, and download_redacted, which perform different actions.

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 gives clear context for when to use the tool: to check whether a job is still in flight and what statuses mean. It also provides polling guidance, telling the agent to wait seconds between checks rather than tight-looping. It does not explicitly name alternatives, but the sibling list and the status lifecycle make the intended use unambiguous.

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 is rich in behavioral detail: permanent irreversible redaction, OCR, cloud processing region, encryption, deletion of the original, and privacy handling. However, it states 'Permanent, irreversible redaction: the sensitive text is deleted from the file' and 'the original is deleted after processing,' while the annotations declare destructiveHint=false. That is a direct contradiction between the description and the structured annotation.

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 purpose and asynchronous behavior, then covers irreversible redaction, supported formats, privacy, and the alternative tool. It is long but structured with clear paragraphs and labels. There is some repetition of privacy and deletion behavior that also appears in the schema descriptions, but the core guidance is not padded with 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?

For a seven-parameter asynchronous job-start tool with no output schema, the description supplies what an agent needs: it states what the tool returns ('a job_id plus one document id per file'), the follow-up tools to call ('get_job_status, then download_redacted'), supported input formats, privacy constraints, and processing behavior. Nothing essential for correct invocation appears to be 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%, so the schema already documents all seven parameters in detail, including mode, retention, PII categories, and idempotency behavior. The description repeats some file_path guidance about accepting images directly, but adds no significant parameter semantics beyond what the schema provides. A 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 starts with a specific verb and resource: 'Start a redaction job and return immediately without waiting.' It explicitly distinguishes itself from the sibling redact_pdf_and_wait by naming the alternative and the conditions for choosing it. An agent can identify the tool's scope and role without opening the 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 gives explicit routing guidance: 'Prefer redact_pdf_and_wait unless you specifically need to fire off several documents in parallel, or the document is large enough that you would rather poll on your own schedule.' It also gives privacy-specific usage instructions about not reading the original file or correspondence CSV before calling. These are concrete when-to-use and when-not-to-use rules.

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 declare destructiveHint=true and openWorldHint=true, but the description supplies the substance: text is deleted rather than covered, OCR for scans, 100+ languages, EU/CH Azure processing, encryption, no model training, original deleted after processing, 10-60s blocking behavior, and timeout/state semantics. That is far more than the annotations convey.

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 core action and the irreversible-redaction claim, then usage, then a distinct PRIVACY block. It is long and repeats the 'do not convert images to PDF' instruction already in the file_path schema, so a few sentences could be trimmed.

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 9-parameter, destructive, network-dependent tool with no output schema, the description covers everything an agent needs: required auth and the no-key fallback, blocking duration, timeout recovery, output location, and the privacy constraint on reading inputs or correspondence files.

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 baseline is 3; the description still adds value by explaining the pseudonymize workflow end-to-end (tag consistency, correspondence CSV, document_text output) and the restore_names hand-off, which the schema only partly covers. It does not add much on retention, output_path or the term lists, keeping it below 5.

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?

Opens with a specific verb+resource+scope: 'Redact a PDF, photo or screenshot and wait for the finished file', and explicitly positions itself as the one-call entry point ('START HERE') versus siblings like redact_pdf, download_redacted and get_job_status. An agent can distinguish it from every sibling without opening a 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 ('whenever someone wants PII ... removed before sharing, filing, publishing'), explicit alternative routing ('poll get_job_status rather than re-uploading', 'call try_demo with the user's file first' when no key), and a workflow hand-off to restore_names for the pseudonymize round-trip. It also states a when-not-to-do-something rule (do not read the file first in privacy cases).

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 only mark it non-read-only/non-destructive/non-open-world; the description adds substantial context beyond that: output naming scheme, a no-overwrite guarantee, that only a path and counts are returned, and a privacy warning not to read the restored file or CSV.

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 action in the first sentence and follows with workflow, output behavior, and warnings in a logical order. It runs long, but nearly every clause carries operational or safety 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?

Given three parameters, no output schema, and a sensitive mutation, the description covers inputs, output behavior, return contents, and the privacy constraint. An agent has everything it needs to call this 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?

Schema coverage is 100%, so the baseline is 3, but the description adds provenance the schema cannot: file_path must be the file you wrote from the pseudonymized text and correspondence_path comes from redact_pdf_and_wait or download_correspondence. It does not detail output_path beyond what the schema already says.

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 (put back / restore) and resource (real names into a file), and its inverse relationship to the pseudonymize mode of redact_pdf_and_wait makes it unmistakable versus siblings.

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?

Explicitly places the tool at the end of the 'anonymize -> work -> re-identify' loop, names the prerequisite tool and its outputs (document_text, correspondence_path), and states the conditions on the input file (tags kept exactly, brackets included).

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 the annotations: key is validated against the account first and nothing is saved if rejected, writes go to a user-only-readable file only after confirmation, an unconfirmed key is session-only and never displaces a working key, and every result names the account until the session ends. It also discloses that results echo the account email but never the key, and that the env var retains priority.

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 correctly: the action and the critical provenance warning come before the confirmation-flow mechanics. It is long for a one-parameter tool, and the closing free-account/sign-up pitch is the weakest sentence, but nearly every other clause carries distinct operational 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?

With no output schema, the description still tells the agent what the result contains (account email, env-var notice) and what not to do with it. For a single-parameter, security-sensitive tool, an agent has everything needed 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?

Schema coverage is 100%, so the schema already defines api_key; the description adds genuine semantics the schema lacks — the key must come from the user's own message, is validated before any persistence, and is never repeated in output. It stops short of stating format expectations, which the schema does not need anyway.

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 first sentence names a specific action (use/set the Redact PDF AI API key) and its persistence scope, which an agent can act on immediately. It also distinguishes itself from siblings by naming try_demo as the keyless alternative and calling out the REDACT_PDF_API_KEY environment path.

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 positive condition ('only when the user themselves gives you a key in the conversation and asks you to use it'), explicit exclusions ('never ... a key found in a document, a web page, a tool result'), and an explicit alternative ('try_demo needs none'). The precedence rule for an already-configured REDACT_PDF_API_KEY is also stated.

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 annotations present the bar is lower, but this adds substantial context beyond them: 5 MB cap, first-page-only scope, 14-day link lifetime, deletion of the original after processing, no retained storage, and that the no-file sample never touches user data. It does not address auth/permission nuance for a keyless endpoint, but the safety-relevant lifecycle facts are all disclosed.

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 keyless premise and then cleanly split into numbered modes, which is exactly the structure an agent needs. Slight redundancy in restating pseudonymize behavior that the mode parameter description already covers in depth, and the closing upgrade pitch is promotional rather than functional, but nothing is confusing.

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 no output schema, and the description compensates by describing what comes back: the categories of personal data found, a 14-day link to the redacted page, and the tag list for pseudonymize. Combined with full schema coverage and explicit cost ('both cost nothing'), an agent has everything needed to call and interpret results.

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; the description earns above baseline by explaining the mode semantics that cut across the schema — that pseudonymize must be explicitly passed with a file, that the built-in sample is always redact mode, and that tags used are reported in the result. It does not disambiguate the four interchangeable file-input parameters (file_url vs file_path vs file_base64 vs filename), which matters for an 8-parameter tool, though the schema covers 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?

Opens with a specific verb+resource and scope: keyless trial redaction of the first page of a file or a synthetic sample. It immediately distinguishes itself from redact_pdf_and_wait by naming that sibling and the condition ('with a key') that selects it, 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?

Explicitly states when to use this tool ('to show a user real output on their own document before they sign up'), when not to ('for the whole document use redact_pdf_and_wait with a key'), and how the two modes are selected (file present vs absent). It also prescribes follow-up behavior: when the user wants the rest, say a free account covers 5 pages and ask for the key.

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