# Realask — full agent guide

Ask the real world a current question about a US local business and get a structured, time-stamped, confidence-scored answer - and, where enabled, have something arranged there on a named customer's behalf with proof of what was agreed.

## When to reach for this
The fact changes faster than the web reflects it, or was never published: today's stock, a real all-in price, same-day availability, an edge-case capability, a policy exception, the current wait. Use this instead of guessing from a listing, a cached page, or opening hours.

Not this: The answer is reliably published and stable. Search is cheaper and faster for that.

## Question shapes

### single_business
Does one specific business have or do X right now, and at what price?
Example: "Does ABC Tire have two Michelin Pilot Sport 4S 235/40R19 in stock today and what is the installed price?"
Typical price: $1.50 | typical time: 180s
Fact keys returned: in_stock, quantity_available, installed_price_minor, earliest_availability

### find_any
Find any nearby business that can satisfy X today; stop at the first confirmed match.
Example: "Find a phone repair shop within 8 miles that can replace an iPhone 16 Pro screen today."
Typical price: $4.00 | typical time: 300s
Fact keys returned: best_match, alternatives_attempted, in_stock, earliest_availability

### compare
Collect comparable facts from several businesses and rank them.
Example: "Check up to five shops and find the lowest installed price for two tires today."
Typical price: $9.00 | typical time: 420s
Fact keys returned: ranked_businesses, installed_price_minor, availability

### capability
Can a business perform an unusual or edge-case job, and under what constraints?
Example: "Can a local print shop print white ink on this material by Friday?"
Typical price: $4.00 | typical time: 300s
Fact keys returned: can_perform, by_deadline, constraints, quoted_price_minor

### policy
Will a specific business accept a policy exception?
Example: "Will this hotel accept a 1 a.m. check-in and oversized vehicle parking?"
Typical price: $2.00 | typical time: 240s
Fact keys returned: policy_confirmed, conditions

### status
What is the current status right now: walk-ins, wait time, open?
Example: "Is the restaurant accepting walk-ins and what is the current wait?"
Typical price: $1.00 | typical time: 120s
Fact keys returned: accepting_walk_ins, current_wait_minutes

## Reading a result

- `answer.resolved` — was the objective met.
- `answer.best_match.outcome` — confirmed_match | confirmed_no_match | uncertain | not_reached | declined | not_attempted | suppressed.
- `answer.best_match.facts` — only facts confirmed at >= 0.80 confidence. Safe to act on.
- `answer.best_match.fact_details` — every fact with status, confidence, source, age_seconds.
- `evidence` — short verbatim excerpts with speaker role and timestamp.
- `limitations` — what was not verified and why. Read this before acting.
- `freshness.age_seconds` — how old the answer is; `fact_class` says how fast it decays.

## Confidence policy
- scale: 0-1, attached to every fact
- 0.95-1.00: direct, unambiguous employee statement, critical values repeated back and confirmed
- 0.80-0.94: directly stated once
- 0.60-0.79: hedged or indirect: reported as uncertain, never as verified
- below_0_60: returned as unconfirmed evidence only
- conflicts: surfaced explicitly, never averaged into a single number
- guarantee: answer.best_match.facts contains only confirmed values; everything else is in fact_details with its status

## Cost and latency control
- Quotes are free and immutable. Decide from the quote before paying.
- `verification_mode`: "auto" reuses a fresh cached fact when it is safe, "live_verified" forces a new call, "digital_fast" never calls.
- `limits.max_businesses` and `limits.deadline_seconds` bound both price and time.
- `priority: true` shortens expected completion for a surcharge.
- Supply `callback_url` instead of polling; the webhook is HMAC-signed.

## What this service will not do
- Anything outside the United States
- Sales, marketing, solicitation, political persuasion, debt collection, or repeated contact
- Negotiating, ordering, booking, or committing on the caller's behalf
- Medical, legal, emergency, or financial-trading questions
- Requests for personal or sensitive data about anyone
- Businesses with no callable public phone number

## Calling policy (why businesses answer)
Calls identify as an AI assistant, state the narrow reason, ask only what the job needs, never record audio, and stop immediately on request. A business can opt out at https://realask.net/opt-out or by calling the number back.

## Endpoints
- capabilities: https://realask.net/v1/capabilities
- quote: https://realask.net/v1/quotes
- purchase: https://realask.net/v1/jobs
- status: https://realask.net/v1/jobs/{job_id}
- result: https://realask.net/v1/jobs/{job_id}/result
- openapi: https://realask.net/openapi.json
- mcp: https://realask.net/mcp
- llms: https://realask.net/llms.txt