# Techniques and best practices Toolhouse is already good at understanding the type of worker you need to create. When you describe a task, Agent Editor builds the right prompt for you and asks follow-up questions to help your worker adapt to your team or organization. The techniques below will help you get consistently better results as you build and refine your workers. *** ### Let Agent Editor do the first draft Don't try to write a perfect prompt from scratch. Describe what you want in plain language — Agent Editor will generate a structured prompt and ask clarifying questions to fill in the gaps. It's faster to refine a generated prompt than to write one from zero. If the first draft isn't quite right, don't rewrite it manually. Instead, tell the editor what's missing: > "This looks good, but the worker should also send a Slack notification after completing the task." Agent Editor will revise the prompt for you. *** ### User awareness When creating or editing a worker in Agent Editor, you can use shortcuts that are automatically resolved to your account details: * **"Send a recap to my email"** — configures the worker to send output to the email address you used to sign up for Toolhouse. No need to type your address manually. * **"Schedule this agent daily at 8am"** — sets up a recurring schedule at 8am in your local timezone, automatically detected from your account. These shortcuts work anywhere in the Agent Editor prompt field. *** ### Time awareness Your workers always know the current date and time. You don't need to pass timestamps in your messages or prompts — the worker handles this automatically. This makes it straightforward to build workers that reason about time without any extra configuration: > "Send a summary of this week's activity every Friday at 5pm." "Only run this task on business days." "Flag any items created more than 30 days ago." *** ### Separate instructions from data One of the most effective habits when building workers is keeping *how to do the task* separate from *what to use when doing it*. * Put step-by-step instructions, decision logic, and behavioral rules in the **system prompt** * Put reference material (templates, datasets, guidelines, examples) in **Agent Files.** This separation makes both easier to maintain. When your HTML email template changes, you update the file without touching the prompt. When you want to change how the worker writes subject lines, you update the prompt without touching the template. **Example:** A worker that creates and schedules email campaigns should have: * A prompt describing when to send, how to choose subject lines, and how to handle errors * An `email-template.html` file in Agent Files containing the layout See [Skills & Knowledge](/toolhouse/capabilites/skills-and-knowledge.md) for more on how to structure your files effectively. *** ### Prefer text-like files and formats Whether you're using File Download, Document Parser, or Agent Files, your worker performs best when working with text-friendly formats — Markdown, plain text, CSV, HTML, JSON. Binary files, images, and heavily formatted documents introduce noise that can degrade output quality. When you have a choice of format, pick the simpler one. A CSV is easier for a worker to reason about than an Excel file. A Markdown document is easier to follow than a formatted Word doc. *** ### Use Virtual Computer for heavy lifting If your worker needs to do something computation-intensive — process a large dataset, run statistical analysis, make multiple API calls, or transform files — offload it to the Virtual Computer rather than asking the worker to do it in context. A useful rule of thumb: if the task would take a human more than a few seconds to do in a spreadsheet, it's probably a good candidate for the Virtual Computer. You don't need to configure this manually. Just describe the task clearly and Toolhouse will attach the Virtual Computer if it's needed. To make it explicit: > "Use the virtual computer to process this data." *** ### Connect to APIs by uploading their documentation Your worker can talk to any API on the internet, not just the integrations Toolhouse provides. If you need to connect to an internal tool or a third-party service, upload its documentation directly in Agent Editor — a PDF, plain text file, or OpenAPI spec all work. The more precise the documentation, the more reliably your worker will call the API correctly. An OpenAPI spec is ideal when available. See [Virtual computer](/toolhouse/capabilites/virtual-computer.md) for step-by-step instructions. *** ### Break complex workflows into smaller workers If a task has many distinct steps — fetch data, transform it, generate a report, send a notification — consider whether it should be one worker or several. Smaller, focused workers are easier to debug, easier to update, and less likely to lose track of context midway through a task. Toolhouse workers can trigger other workers, so you can chain them together into a pipeline while keeping each one simple and maintainable. *** ### Test with simple cases first Before running a complex workflow end-to-end, test each piece in isolation. If your worker fetches data, transforms it, and then posts to Slack, verify the fetch step works before adding the transformation logic. You can prompt your worker to stop after a specific step: > "Fetch the report and tell me what you found. Don't send anything yet." Once each step works independently, combine them and test the full flow. *** ### Be explicit about edge cases Workers follow instructions literally. If your prompt doesn't account for a situation, the worker will make its best guess — which may not match what you'd want. Think about what should happen when things don't go as expected: * What if the data is empty? * What if the API returns an error? * What if the file is in the wrong format? Adding a short "if this happens, do that" clause to your prompt prevents a large category of unexpected behavior: > "If the spreadsheet has no rows, send a Slack message saying no data was found and stop." *** ### Retry on failure Some failures are transient — a Virtual Computer task that hit a resource limit, a file download that timed out, an API that was briefly unavailable. In most cases, simply prompting your worker to retry is enough: > "That didn't work — please try again." If a task fails repeatedly, check whether the issue is structural (wrong URL, missing credentials, unsupported file format) rather than transient before retrying. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.toolhouse.ai/toolhouse/toolhouse/techniques-and-best-practices.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.