Credits, jobs, and retries
Quote research, respect spending approvals, and handle asynchronous work without duplicate charges.
Quote research before spending#
research:read authorizes research access, and data retrieval can consume Dativue credits.
Use quotes for the proposed research before spending; derive quote items from the discovered tool operation, preset, and bounded quantity.
Use this mapping for the current tool contract, checking that the tool is discovered and its operation is accepted by the discovered research_credit_quote schema:
| Discovered tool | Quote item |
|---|---|
search_keyword_ideas, search_keyword_trends, search_serp, search_competitor_visibility, search_keyword_gap, search_ai_visibility, search_ai_response, search_reviews, search_web_mentions, search_backlinks, search_local_businesses, search_apps, search_products, search_technology, search_site_audit, search_domain_profile | kind: "search", operation: remove the search_ prefix, preset: the call's preset or "standard", quantity: number of planned calls |
social_search, social_profile, social_posts | kind: "social", operation: remove the social_ prefix, platform: the validated call's platform, quantity: number of planned calls |
social_get, social_comments, social_transcript | kind: "social", operation: remove the social_ prefix, platform: derived from the validated HTTPS URL, quantity: number of planned calls |
research_credit_quote, research_job_status | Free; no billable quote item |
For URL-based social tools, parse the hostname and match exact domains or subdomains: youtube.com/youtu.be to youtube, tiktok.com to tiktok, instagram.com to instagram, reddit.com/redd.it to reddit, x.com/twitter.com to x, and linkedin.com to linkedin.
Reject credentials in URLs, unsupported hosts, and deceptive suffixes such as youtube.com.example.org.
Quantity counts calls, not returned rows, keywords, domains, or transcript seconds within one call.
Group calls with identical kind, operation, platform, and preset by their bounded quantity.
Quote each additional planned retrieval or pagination call; cached responses may cost less, but do not assume a new call is free.
For a newly discovered tool without a known billing mapping, keep discovery working and block its paid execution until a documented mapping is available. Do not guess a price from the tool's name, annotations, or description.
Respect spending approvals#
A quote is an estimate or maximum hold, not a permanent price or a spending authorization.
Respect the product's existing approval and budget policy, including autonomous work.
Never accept a model-supplied approved: true as authority to spend.
Bind approval to the authenticated customer, exact tool and validated arguments, stable operation ID, and approved maximum credits, using the host's existing policy for expiration and changed quotes.
When a search call needs Dativue's approvedMaxCredits argument, populate it server-side from that approval; never trust a model-supplied maximum as evidence of consent.
Show an insufficient-credit message and a link to the customer's Dativue account when appropriate.
Retry with stable idempotency keys#
Generate a stable idempotencyKey on the server for each intended billable operation and persist it with the exact arguments.
Reuse that key and body for retries after network uncertainty.
Never automatically issue a new key to retry a request whose outcome is unknown.
Reusing a key with different arguments can produce IDEMPOTENCY_CONFLICT; do not suppress that error.
Preserve MCP protocol errors, tool isError, and Dativue's inner result error/status separately.
Use bounded network timeouts and retry limits; honor rate limits and retry guidance.
Resume pending jobs#
Some research calls return pending results with a jobId instead of immediate data.
Poll that exact ID with research_job_status, bounded backoff, and an overall timeout.
Persist the job ID if work must resume after a request or process ends.
Do not repeat the original paid call to check job completion.
Quote and status calls are free, but status polling still has rate limits.
Keep pending, complete, failed, empty, and partial results distinct in the UI and agent response.