Skip to main content

Writing Effective Prompts

The prompt is what you tell the AI to do each time the task runs. Specific instructions reduce ambiguity and make results easier to evaluate, but model output can vary even with the same prompt and input.

When instructions are incomplete, the AI may infer missing details, choose its own approach, or stop without producing the intended result. Define an outcome for incomplete checks, such as a report identifying unreadable files and missing records.

A vague prompt is not just a risk of getting no output. Because AI Tasks run unattended and no one reviews the plan before it executes, a prompt that does not clearly scope what to act on, whether that is a file, a folder's settings, a user or group, or a site-wide setting, can cause the AI to change or remove the wrong thing, with no chance to catch the mistake first.

This applies to more than file operations: a poorly scoped prompt for an onboarding or offboarding task can just as easily grant or revoke the wrong person's access. Precision matters more here than in the AI Assistant, where every action waits for your approval before it happens.

What a Good Prompt Covers

A well-written prompt covers four things:

What to act on. Tell the AI exactly what to look at: a folder, a file, a user, a group, or a site setting. Include the full path or the specific name rather than a general area.

If you are using a File Action trigger and want the AI to process a specific file type, name it in the prompt. "When a new CSV file is uploaded to /Intake/Partners..." is more reliable than "Look at the folder and see what arrived," and "Check the members of the Contractors group" is more reliable than "Check who has access."

What to do with it. Describe the task clearly. If you want the AI to validate content, tell it what a valid file looks like. If you want it to check a permission or a configuration, tell it what the correct setting is. The AI does not know your business rules unless you write them into the prompt.

What to produce, or what to change. Tell the AI the output format and where to write it. If you want a markdown file, say so. If you want the file in a specific folder with a specific naming convention, include that.

If the task also makes a change, like removing a user from a group or revoking a folder permission, say so explicitly rather than leaving it implied by the goal. Without a clear output instruction, the AI may respond in the chat session only and not write a file.

What to do when something goes wrong. Tell the AI what to do if the data is missing, a permission conflicts with what you expect, or the target cannot be found. "If the file is missing required columns, write a report to /Exceptions explaining what is missing" is better than leaving the error case undefined.

Prompt Structure That Works

The following structure makes the intended work and its exception cases explicit:

  1. The trigger context: what just happened or the first source to examine
  2. What to act on and what to check
  3. What to produce and where to write it, or what change to make
  4. What to do if something does not meet expectations

Good Prompt vs. Weak Prompt

The examples below show the same task written two ways. The weak version is not obviously bad. It describes what you want at a high level, but leaves out the specifics the AI needs to produce consistent results.

Invoice validation

Trigger: File Action on the /Intake/Invoices folder. Add a source pattern like invoice_*.pdf to limit which uploads fire the task.

Weak prompt

When a new invoice arrives in /Intake/Invoices, validate it and move valid ones to /Processing/Ready. If something looks wrong, flag it.

This sounds reasonable but "validate it" gives the AI nothing to check against. The AI needs the required fields, their expected formats, and the conditions that make an invoice need review. "Flag it" is also undefined. Flag it how? The AI may leave a note in the chat session and stop, or produce a different result on every run.

Create /Processing/Reviews before enabling the task. The reviewer uses the report to check the invoice; a document can contain every required field and still name the wrong vendor or total.

Prompt:

When a new file is uploaded to /Intake/Invoices, open it and assess whether it contains the following fields: vendor name, invoice number, invoice date, line items with quantities and unit prices, and a total amount. Write an assessment to /Processing/Reviews named [original filename]-review.md. For each field, list the extracted value and its page or section, or mark it as missing or unreadable. Record any uncertainty. If the document cannot be read, record that the assessment could not be completed. Leave the invoice in /Intake/Invoices for a person to review before release.


Partner delivery report

Trigger: Interval (daily) or a Custom Schedule set to your preferred time each day.

Weak prompt

Check /Transfers/Inbound for partner deliveries and create a daily summary report. Group by partner.

The prompt names a folder, but "daily summary" does not specify the time window, details to include for each file, or output location. The AI will pick a format and location on its own, which may differ every run. There is also no instruction for what to do when no files arrived.

Prompt:

Look at the /Transfers/Inbound folder and list every file that was created in the last 24 hours. For each file, record the filename, file size, and the time it arrived. Group the files by the top-level subfolder they are in (each subfolder represents a partner). Write the summary as a markdown file to /Reports/Daily named delivery-report-[today's date].md. If no files arrived in the last 24 hours, write the report anyway and note that no deliveries were received.


Sensitive content screening

This example uses AI to assess passages in context against your intake guidelines and write a report for a reviewer. Use deterministic checks for fixed patterns. A reviewer decides whether to release the document, including when the AI reports no findings.

Trigger: File Action on the /Intake/External folder. Add a source pattern like review_*.pdf to limit runs to the expected documents. This example requires PDFs with readable text.

Weak prompt

When a file is uploaded to /Intake/External, scan it for PII or confidential data. If anything is found, hold it for review. Otherwise let it proceed.

"PII or confidential data" does not tell the AI which information needs review in this workflow. Supply guidelines that explain what the intended recipient may receive and which content requires approval.

"Hold it for review" and "let it proceed" leave the output and release decision undefined. Ask for a report on every assessment and keep the source document available for the reviewer.

For the prompt below, store your guidelines in /Screening/intake-guidelines.md and create the /Screening/Reports folder before enabling the task.

Prompt:

When a new file is uploaded to /Intake/External, read /Screening/intake-guidelines.md and assess the document for passages that appear to contain personal information or confidential commercial terms covered by those guidelines. Write a report to /Screening/Reports named [original filename]-review.md. For each finding, identify the relevant section or page and explain why the passage may need review under the guidelines, without copying sensitive values. Record any uncertainty or content you could not read. If nothing is identified, say "No passages identified for review." If the guidelines or document cannot be read, record that the assessment could not be completed. Leave the source file in /Intake/External for a person to review.


Configuration audit

Trigger: Interval (weekly) or a Custom Schedule set to a specific day and time, like every Monday morning.

Weak prompt

Check each folder under /Partners to make sure it is configured correctly and send me a report.

"Configured correctly" has no definition here. GPG enabled? Correct permissions? A notification set up? The AI will check whatever it decides is relevant, which will differ from run to run. "Send me a report" is also a problem. AI Tasks write files to folders. They do not send email, and "me" is not defined.

Prompt:

Look at each subfolder inside /Partners. For each partner folder, check the following: the folder has at least one user assigned with read and write permissions, GPG encryption is enabled, and a Notification is configured to alert on file uploads. Write a report to /Admin/Audits named partner-config-audit-[today's date].md. For each partner folder, list the folder name and whether each check passed or failed. If a check cannot be determined, note it as unknown. At the end, summarize how many folders passed all checks, how many had at least one failure, and list the folders that need attention.


User access cleanup

Trigger: Interval (weekly).

Weak prompt

Check the Contractors group and remove anyone who shouldn't have access anymore.

"Shouldn't have access anymore" has no definition. Does that mean the account is disabled, inactive for some period, or the contract has ended? "Remove" is also undefined: remove from the group, revoke folder permissions, or disable the account entirely? Nothing is written down, so there is no record of who was changed or why.

Prompt:

Look at the members of the Contractors group. For each member, check whether the account is disabled. If it is, remove that user from the Contractors group and revoke their permissions on the /Projects/Active folder. Write a report to /Admin/Access-Cleanup named cleanup-[today's date].md listing each user changed, what was revoked, and any accounts that could not be processed.


User offboarding verification

Trigger: Ad-Hoc, run manually each time someone is offboarded. Use Ad-Hoc when the work is not on a fixed schedule but you want to run the same prompt on demand. Reusing the verification prompt keeps the checks consistent across offboardings without relying on memory or a separate manual checklist.

Weak prompt

Make sure [username] no longer has access after they were offboarded.

"Access" could mean folder permissions, group memberships, share links, or all three. The AI will decide what to check. There is also no output. No report is written, so there is no record of what the AI found or confirmed.

Prompt:

Check whether the user [username] still has access anywhere on the site. Look at folder permissions, group memberships, and active share links. For each area, list what was found and whether the access has been removed. Write a report to /Admin/Offboarding named offboarding-[username]-[today's date].md. Identify the records supporting each finding and any checks that could not be completed. If no active access is found in these areas, report that result for administrator review without treating uncompleted checks as passed.

What Makes a Prompt Fail

Too vague. "Analyze the file and do something useful" leaves the AI to decide what matters and what result to produce. It may act on assumptions or stop without useful output. State the subject, criteria, and required result.

No output instruction. If the prompt does not say where to write the result, the AI may respond only in the chat session and not produce a file. Always specify the output location and format.

Assumes the AI knows your business context. The AI does not know what a valid invoice looks like for your organization, what your partner naming conventions are, what counts as inactive for a contractor account, or what your compliance requirements are. If it matters, write it into the prompt.

Too many tasks in one prompt. Asking one task to validate, classify, summarize, and route a file produces unpredictable results. Each of those is a separate job. Break complex workflows into multiple tasks, or use an Automation to route files to folders where separate, focused tasks pick them up.

No source pattern on a high-volume File Action trigger. If the trigger folder receives many files and the prompt is designed for a specific file type, the task will run on every file including ones it cannot process. Set a source pattern like *.pdf or report_*.xlsx to limit which files trigger the run.

Vague scope for a change. A prompt that says "remove access" or "clean up permissions" without naming the specific group, folder, or permission to touch can cause the AI to change more, or less, than you intended. Be as specific about what to change as you are about what to read.

No error handling. A prompt that only describes the happy path leaves the AI without guidance when something goes wrong. Always include instructions for the exception case.

When a run fails or produces no output, open the chat session in Chat Logs. The transcript shows exactly where the AI stopped and what it encountered. Fix the prompt and use Ad-Hoc to re-run manually before putting it back on a schedule.

Tips for Getting Good Results

Start with Ad-Hoc trigger when building a new task. Run it manually several times on real files to confirm the output matches what you expect before switching to a schedule or file action trigger.

Use a workspace to test new tasks before running them on production folders. This limits the impact if the prompt needs adjustment.

Review the chat log after each test run. The transcript shows exactly what the AI did, which files it accessed, what decisions it made, and where it got stuck. This is the fastest way to identify what the prompt is missing.

Keep one prompt focused on one job. A task that does one thing well is easier to test, easier to debug, and produces more consistent output than a task that tries to do everything.

If the AI is not producing what you expect, review the prompt for unclear instructions or missing context, revise it, and test again. Continue evaluating task results after enabling the task; new inputs and model changes can affect later assessments.