> ## Documentation Index > Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt > Use this file to discover all available pages before exploring further. # Goal Prompting Guide > Write goals that make TinyFish Web Agent work like magic This guide teaches you how to write goals that succeed on the first try. The examples are tested against real production traffic. The patterns work. Copy them, modify them, use them. **Quantified impact:** In testing, specific goals completed **4.9x faster** and returned **16x less unnecessary data** compared to vague goals for the same task. ## The Mental Model Think of TinyFish Web Agent as a capable but literal-minded assistant sitting in front of a browser. **What it can do:** * See exactly what you would see on the screen * Click, type, scroll, and navigate * Wait for dynamic content to load * Follow instructions precisely * Return structured data * Navigate multi-page PDFs and extract content * Remember information across workflow steps * Parse natural language into form fields **What it cannot do:** * Read your mind about what you meant * Guess what to do when something unexpected happens * Know your business context unless you tell it * Decide on output format without explicit instructions Your job is to remove ambiguity. The more explicit your goal, the higher your success rate. ## Match Goal Style to Task Type Different tasks benefit from different goal-writing approaches: | Task Type | Recommended Style | Key Principle | | ------------------------ | ---------------------- | ------------------------------------------------ | | Price/product extraction | Specific, constrained | List exact fields, exclude extras | | Form filling | Natural language | Describe the person/entity, let agent map fields | | Multi-step workflows | Numbered steps | Enable cross-step memory references | | Batch execution | Minimal, strict schema | Only essential fields for consistency | ## The Anatomy of a Great Goal Every effective goal has up to seven components. Simple tasks may need only two or three. Complex extractions benefit from all seven. | Component | Purpose | Example | | ---------- | --------------------- | ------------------------------------------ | | Objective | What to achieve | "Extract pricing information" | | Target | Where to focus | "from the pricing table" | | Fields | What data to extract | "product name, price, availability" | | Schema | Output structure | "Return as JSON with keys: name, price" | | Steps | Sequence of actions | "Close the cookie banner first" | | Guardrails | What NOT to do | "Do not click purchase buttons" | | Edge cases | Handle the unexpected | "If price shows 'Contact Us', set to null" | ## The Transformation Pattern Here's how the same task looks at three quality levels: ``` Get the pricing from this page ``` The agent doesn't know what "pricing" means to you. Annual vs monthly? Features included? What format? ``` Extract the product name, price, and stock status. Return as JSON. ``` Clearer, but still ambiguous. What if there are multiple prices? What JSON structure? ``` Extract the following from this product page: - Product name (full title as displayed) - Current price (number only, no currency symbol) - Original price if on sale, otherwise null - Currency code - In stock (true/false) If a cookie banner appears, close it first. Do not click any Add to Cart or purchase buttons. If price shows "Contact for price", set current_price to null. Return as JSON with this structure: { "product_name": "string", "current_price": number or null, "original_price": number or null, "currency": "string", "in_stock": boolean } ``` This tells the agent exactly what to do at every decision point. ## Task-Specific Examples For extraction, be specific and constrained to prevent over-fetching: ``` Extract ONLY the following from the pricing table: - plan_name: string - monthly_price: number (no currency symbol) - annual_price: number (no currency symbol) - feature_count: integer Do not extract feature descriptions or marketing copy. Return as JSON array. ``` For forms, use natural language—the agent handles field mapping: ``` Fill out the contact form with this information: John Smith is a software engineer at Acme Corp in San Francisco. His email is john.smith@acme.com and phone is 415-555-0123. He's interested in the Enterprise plan and wants a demo next week. Submit the form when complete. ``` The agent maps "software engineer" to job title, "Acme Corp" to company, etc. For workflows, use numbered steps to enable cross-step memory: ``` Complete this account verification workflow: 1. Navigate to the login page and click "Forgot Password" 2. Enter the email address: test@example.com 3. Note the confirmation message shown (save this for later) 4. Check the email inbox at the provided URL for the code 5. Return to the original site and enter the code from step 4 6. Confirm the new password form appears Return the confirmation message from step 3 and success/failure status. ``` ## Single Runs vs. Batch Execution Understanding when you're running a single task versus scaling to many is critical for goal design. ### Single Runs (Playground & Individual API Calls) **When you use this:** * Testing and validating goals in the Playground * One-off extractions or automations * Prototyping before scaling **Goal design principles:** * Focus on completeness—you want rich results from this one run * Include detailed edge case handling since you can iterate * Add verbose output instructions for debugging ### Batch Execution (Projects & Concurrent API Calls) **When you use this:** * Processing hundreds or thousands of URLs * Scheduled monitoring jobs * Building datasets at scale **Goal design principles:** * Optimize for consistency—every run should return identical structure * Minimize fields to only what you need * Use strict schemas for reliable downstream processing | Aspect | Single Run | Batch Execution | | ----------------- | ------------------------ | ------------------------------- | | Field count | More fields, richer data | Minimal fields, only essentials | | Error handling | Verbose, for debugging | Structured, for automation | | Schema strictness | Flexible | Exact match required | | Edge cases | Detailed instructions | Fail-fast with error flags | | Goal length | Longer, comprehensive | Shorter, focused | ## Schema Enforcement for Batch Runs When running the same goal repeatedly, schema consistency is critical. Without explicit enforcement, the agent may return slightly different field names across runs. **Best practice:** Provide an example schema with exact field names AND sample values. ``` Return JSON matching this exact structure: { "product_name": "Example Product Title", "current_price": 29.99, "currency": "USD", "in_stock": true } ``` Why sample values matter: * Field names alone can be ambiguous (`price` vs `"price": "29.99"` vs `"price": 29.99`) * Sample values clarify expected types (number vs string, boolean vs "yes/no") * The agent mirrors the pattern it sees **Anti-pattern:** `Return as JSON with product name, price, and availability.` This might return `{"name": "..."}` one time and `{"product_name": "..."}` another. ## Goal Writing Tips Tell TinyFish Web Agent how to structure the response: ``` Extract product data. Return as JSON with this structure: { "products": [ { "name": string, "price": string, "rating": number } ] } ``` Anticipate what might go wrong: ``` Extract the price from the product page. If the product is out of stock, return { "price": null, "outOfStock": true }. If no price is found, return { "price": null, "error": "Price not found" }. ``` For multi-step workflows, number the steps: ``` 1. Click "Login" 2. Enter username "demo@example.com" 3. Enter password "demo123" 4. Click "Submit" 5. Wait for dashboard to load 6. Extract the account balance shown in the header ``` When data from one step is needed later, tell the agent to remember it: ``` IMPORTANT: On Step 6, a verification code will be displayed. You MUST remember this code and enter it exactly on Step 7. ``` Other phrases that work: * "Remember these values—you'll need them for verification" * "Note the confirmation number displayed" * "Save this for later" When element IDs aren't known, describe visually: ``` Click the blue "Add to Cart" button below the price ``` Instead of: ``` Click the button with id="add-to-cart-btn" ``` Limit scope to avoid over-extraction: ``` Extract the FIRST 10 products only from the current page. Do not click pagination or load more items. ``` Tell the agent when to stop: ``` Stop when ANY of these is true: - You have extracted 20 items - No more "Load More" button exists - You have processed 5 pages - The page shows a login prompt ``` When a page might have multiple layouts: ``` Extract the product price from this page. Primary approach: Look for the price in the main product details section. If not found: Check the "Buy Box" sidebar on the right. If still not found: Look for a "See price in cart" button. Return: { "price": number or null, "price_location": "main" or "sidebar" or "cart_required" or "not_found" } ``` ## The Intern Test Ask yourself: If I handed this goal to a smart but literal-minded intern who has never seen this website, would they: * Know exactly where to look first? * Know when to stop? * Know what to do if something unexpected happens? * Know the exact format I want the answer in? If any answer is "they would have to guess," add more detail. ## Ready-to-Use Templates Copy and modify these templates for your use cases. ``` Extract the following from this product page: - Product name (full title) - Current price (number only, no currency symbol) - Original price if on sale, otherwise null - Currency code - Availability status - Shipping information if shown If a cookie or consent banner appears, close it. Wait for the price to fully load before extracting. Return as JSON. ``` ``` Extract the first [N] listings from this page. For each listing, extract: - [Primary identifier: name, title, etc.] - [Key attributes: location, price, size, etc.] - [Secondary attributes as needed] - Listing URL If there is a "Load More" button, click it once before extracting. Scroll down to ensure all visible listings are loaded. Return as a JSON array. ``` ``` Extract the following from this company/profile page: - Name - Description or tagline - Industry or category - Size or scale indicators - Location - Website or contact info if shown - Any key metrics displayed Return as JSON. ``` ``` Extract [data type] from this page. For each item, extract: - [Field definitions] After extracting from the current page: 1. Look for a "Next" button or pagination link 2. If found and you have fewer than [N] items, click it 3. Wait for the new page to load 4. Continue extracting Stop when you have [N] items or no more pages exist. Return all results as a single JSON array. ``` ``` On this page: 1. Find the search box 2. Enter "[search query]" 3. Click search or press Enter 4. Wait for results to load 5. Extract the first [N] results For each result, extract: - [Field definitions] Return as a JSON array. ``` ``` Extract the following from this PDF document: 1. Navigate through all pages of the PDF 2. For each page, extract: - [Specific content: tables, headings, paragraphs] - Page number If the PDF has a table of contents, use it to locate [specific section]. Scroll through the entire document to ensure all pages are processed. Return as JSON with structure: { "document_title": "string", "total_pages": number, "extracted_content": [ { "page": number, "content": "string or structured data" } ] } ``` ``` Complete this form workflow: 1. Navigate to the form at [URL or describe location] 2. Fill in the form with this information: [Natural language description of the data] 3. Click Submit/Continue 4. On the confirmation page, note the reference number or confirmation message 5. If a verification step appears: - Note what verification is required - Complete it if possible 6. Return to confirm final success state Return: { "form_submitted": boolean, "confirmation_reference": "string or null", "verification_required": "string description or null", "final_status": "success" or "pending_verification" or "failed" } ``` ``` Extract [data] from this page. Primary location: [main expected location] Fallback 1: [alternative location if primary missing] Fallback 2: [second alternative] For each item found, extract: - [Field definitions] - source_location: where the data was found If no data found in any location, return: { "success": false, "error": "data_not_found", "locations_checked": ["primary", "fallback1", "fallback2"] } ``` ## Troubleshooting Common issues and how to fix them: | Issue | Likely Cause | Solution | | --------------- | ---------------------------------- | ------------------------------------------------------ | | Empty results | JavaScript didn't finish rendering | Add "Wait for \[specific element] to fully load" | | Missing fields | Data hidden until interaction | Add "Click \[button] to expand" or "Scroll down first" | | Wrong data | Goal was ambiguous | Be more specific about which section to extract from | | Partial results | Pagination not handled | Add explicit "click Next" instructions with a limit | | Blocked | Site has bot protection | Try `browser_profile: "stealth"` with proxy | | Slow completion | Goal too vague | Add specific field constraints, reduce scope | | Timeout | Task too complex | Break into smaller runs or add termination conditions | Runs have a 10-minute timeout. Design goals to complete their core task well within that limit. For complex multi-step workflows, break them into smaller runs. ## Observed Behaviors TinyFish Web Agent handles common natural language variations automatically: | Input | Interpreted As | | ---------------- | ------------------ | | "March 15, 1985" | 1985-03-15 | | "tech" | Technology | | "mornings" | Morning (9am-12pm) | | "TX" | Texas | Letter-based phone numbers like `555-WORK-123` may be converted to keypad digits (`555-967-5123`). ## Known Limitations | Limitation | Notes | | ----------------- | ----------------------------------------------------------------------------------------------------------------- | | CAPTCHAs | Cannot solve reCAPTCHA or similar challenges | | Infinite scroll | May not scroll to load all content automatically | | Login persistence | Use [Browser Context Profiles](/key-concepts/browser-context-profiles) when runs should reuse saved session state | ## Related Integrate TinyFish Web Agent with your LLM Complete endpoint documentation Real-world code examples Common questions answered