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:

Vague (fails)

Get the pricing from this page

The agent doesn’t know what “pricing” means to you. Annual vs monthly? Features included? What format?

Better (might work)

Extract the product name, price, and stock status. Return as JSON.

Clearer, but still ambiguous. What if there are multiple prices? What JSON structure?

Production-ready

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

Data Extraction

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.

Form Filling

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 [e-mail] 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.

Multi-Step Workflow

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: [e-mail]
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

Specify output format

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 }
  ]
}

Handle edge cases

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" }.

Use numbered steps for sequences

For multi-step workflows, number the steps:

1. Click "Login"
2. Enter username "[e-mail]"
3. Enter password "demo123"
4. Click "Submit"
5. Wait for dashboard to load
6. Extract the account balance shown in the header

Trigger cross-step memory explicitly

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”

Describe elements visually

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"

Set explicit boundaries

Limit scope to avoid over-extraction:

Extract the FIRST 10 products only from the current page.
Do not click pagination or load more items.

Include termination conditions

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

Use explicit fallbacks

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.

Template A: Product Extraction

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.

Template B: Listing Extraction

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.

Template C: Company Research

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.

Template D: Multi-Page Navigation

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.

Template E: Search and Filter

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.

Template F: PDF Extraction

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" }
  ]
}

Template G: Form with Verification

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"
}

Template H: Extraction with Fallbacks

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 when runs should reuse saved session state

Related

AI Integration Guide

Integrate TinyFish Web Agent with your LLM

API Reference

Complete endpoint documentation

Examples

Real-world code examples

FAQ

Common questions answered