{"uid":"cap_IXsY50AzzHDqI685sub-F","slug":"agent-preflight-tool-call-evaluator-ae295e7e","name":"Agent Preflight Tool-Call Evaluator","description":"Pre-execution decision for a metered search or browse tool call. Evaluates the proposal; does not execute the external tool.","url":"https://api.agent-preflight.com/v0.2/preflight/tool-call?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"task":{"type":"object","required":["goalHash"],"properties":{"goalHash":{"type":"string","description":"Opaque goal correlation token"}},"additionalProperties":false},"tool":{"type":"object","required":["provider","operation","request","estimatedExternalCostUsd"],"properties":{"request":{"type":"object","properties":{"url":{"type":"string","minLength":1},"query":{"type":"string","maxLength":500,"minLength":1},"max_results":{"type":"integer","maximum":10,"minimum":1}},"description":"Provider-specific payload. search/web_search requires query (string 1..500) and optional max_results (1..10). browse/fetch requires url (http/https).","additionalProperties":true},"provider":{"type":"string","minLength":1,"description":"Tool provider. Supported: search, browse"},"operation":{"type":"string","minLength":1,"description":"Tool operation. Supported: search:web_search, browse:fetch"},"estimatedModelCostUsd":{"type":"number","minimum":0,"description":"Optional estimated USD model cost for this step"},"estimatedExternalCostUsd":{"type":"number","minimum":0,"description":"Estimated USD cost of the external tool call"}},"additionalProperties":false},"runId":{"type":"string","minLength":1,"description":"Caller-scoped run identifier"},"budget":{"type":"object","required":["remainingUsd"],"properties":{"reservedUsd":{"type":"number","minimum":0},"remainingUsd":{"type":"number","minimum":0},"maxToolCallsRemaining":{"type":"integer","minimum":0}},"additionalProperties":false},"stepId":{"type":"string","minLength":1,"description":"Caller-scoped step identifier within the run"},"history":{"type":"array","items":{"type":"object","required":["toolCallId","fingerprint","outcome","ageSeconds"],"properties":{"outcome":{"enum":["success","terminal_failure","transient_failure"],"type":"string"},"goalHash":{"type":"string"},"ageSeconds":{"type":"number","minimum":0},"toolCallId":{"type":"string"},"fingerprint":{"type":"string"},"resultReference":{"type":"string"}},"additionalProperties":false},"maxItems":100,"description":"At most 100 caller-owned prior outcomes; reuse requires explicit permission, positive freshness TTL and matching nonempty goal hashes."},"retryCap":{"type":"integer","default":1,"minimum":1},"capabilities":{"type":"object","properties":{"canReduceScope":{"type":"boolean"},"canReusePriorResult":{"type":"boolean"}},"additionalProperties":false},"preflightPriceUsd":{"type":"number","default":0.002,"minimum":0,"description":"Modeled actionable fee only; cannot change the actual HTTP settlement price."},"freshnessTtlSeconds":{"type":"number","maximum":1000000000,"minimum":0,"description":"Explicit positive TTL required for reuse. Omitted or zero disables reuse."}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.002","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.002/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_6Njw5tsvXtS5iwb0ylMwL","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.002","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Evaluates whether an AI agent should proceed with a metered search or browse tool call, considering budget, history, and deduplication — without executing the external tool.","exampleAgentPrompt":"Before I run this web_search for 'best open source LLMs 2024' with an estimated cost of $0.01 and I have $0.50 remaining in budget, check whether I should proceed — my run ID is 'run-42' and this is step 3.","exampleUseCases":[{"title":"Budget gate before web search","prompt":"I'm about to run a web search for 'latest Fed interest rate decision' — estimated cost is $0.005 and I have $0.12 left in my budget. Should I go ahead with it? My run ID is 'run-99' and this is step 2."},{"title":"Deduplication check before re-fetching URL","prompt":"I want to fetch https://example.com/earnings-report before processing it, but I think I may have already done this earlier in the run. Check my call history and tell me if I should skip it — run ID is 'run-77', step 5, estimated cost $0.008."},{"title":"Cost guard for agent with tight token budget","prompt":"My agent is on step 8 of run 'run-007' and wants to do a web_search for 'climate policy EU 2024' with max 5 results and an estimated external cost of $0.003. I only have $0.02 remaining — should the agent proceed or abort?"}],"resultDescription":"A preflight verdict indicating whether the agent should proceed with the planned tool call, along with signals for deduplication (whether this call was already made), budget adequacy, and any blocking reasons — all without actually executing the external search or browse operation.","failureModes":["Missing required fields (goalHash, provider, operation, estimatedExternalCostUsd, remainingUsd) returns validation error","Unsupported provider or operation values return an error indicating unsupported tool","Remaining budget of zero or below estimated cost likely returns a block decision","Malformed history entries may cause the request to be rejected","Payment not provided or x402 payment failure results in 402 response before evaluation occurs"],"whenToPreferThis":"Use this endpoint when your AI agent is about to execute a metered external tool call (search or web browse) and you need a lightweight, fast pre-execution gate that checks budget sufficiency, deduplication against call history, and overall worthiness — before incurring real costs. Prefer this over executing blindly when running multi-step agentic workflows where tool call costs accumulate, when the same URL or query might be fetched multiple times across steps, or when you need auditable go/no-go decisions logged per step.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-13T12:34:36.348Z","isFirstParty":false,"canonicalSlug":"agent-preflight-tool-call-evaluator-ae295e7e"}