ghost-x402-market-intel-vet-schema

by dev.workers.ghost-agent-os.ghost-identity

ghost_pre_spend_gate

THE PRE-SPEND GATE. Call this immediately before your agent pays an x402/API provider, with the task's own economics. Returns ALLOW / FALLBACK / DECLINE / INSUFFICIENT_EVIDENCE — not advice: a decision your payment path should enforce. It joins the provider's measured record (independent payers, concentration, price drift, reachability, funding links, on-chain verdict) to YOUR numbers (customer_revenue, value_of_success, max_budget, required_margin, failure_cost, switching_cost) and answers the question ranking cannot: is paying for THIS task profitable, and at which provider. Where the task's value is known it maximises expected net value; where it is not, it minimises cost per verified success — which is why it will refuse the cheapest call when a cheaper provider succeeds less often. Unknown economics stay UNKNOWN and are never invented. Report the result afterwards to /v1/gate/outcome (free) — that is the only source of the success rates it uses. Paid per decision via x402, or drawn from prepaid credit; a cached decision inside valid_until and an INSUFFICIENT_EVIDENCE answer are free.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`task_id`	Yes
`currency`	No		USD
`task_type`	Yes	What kind of job this is. Success history is pooled under it, so it must be stable.
`max_budget`	No
`failure_cost`	No
`revenue_models`	No	Optional. Say what the task is worth in the terms you actually measure, and Ghost derives value_of_success / customer_revenue / max_budget from it — never overriding a value you stated yourself. Each entry needs a `type`: SALES_ROI (spend, qualified_leads?, meetings?, closed_deals?, realized_revenue?), AFFILIATE_ROI (commission_rate?, order_value?, conversion_probability?, tool_cost?, inference_cost?, transaction_cost?), PROCUREMENT_SAVINGS (current_total_cost?, alternative_total_cost?, switching_cost?, migration_cost?), RETURN_ROI (expected_return, data_cost?, model_cost?, execution_cost?, expected_risk_loss?; expected_return is YOURS to state and is never estimated by Ghost), CREDIT_AFFORDABILITY (available_credit, planned_spend?). Ratios are derived only where the denominator exists; conversion rates are never invented.
`switching_cost`	No
`required_margin`	No
`customer_revenue`	No
`value_of_success`	No
`payment_signature`	No	x402 PAYMENT-SIGNATURE header value. Omit it to receive the payment terms; call again with it to run the tool.
`success_definition`	Yes	What counts as success, written down BEFORE paying. verified_success is later judged against this.
`fallback_authorized`	No	May Ghost route to a different candidate than the first? Off by default: an unrequested reroute is a payment the operator did not choose.
`provider_candidates`	Yes

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully carries the transparency burden: it states the output is 'not advice' but an enforceable decision, that unknown economics stay UNKNOWN and are never invented, and that derived values never override caller-stated values. It also discloses the feedback loop (only /v1/gate/outcome feeds success rates), the pricing/free conditions, and the refusal behavior when a cheaper provider succeeds less often. These are meaningful behavioral traits beyond what schema annotations could convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the tool's purpose and timing, then layers behavioral rules, economic inputs, and payment mechanics. It is a long, dense single paragraph with some stylistic repetition (e.g., 'never invented' appears in both description and schema), but nearly every sentence adds substantive guidance. The length is largely justified by the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 14 parameters, no annotations, and no output schema, the description covers the full workflow: when to call, what verdicts to expect, what inputs matter, how pricing/free cases work, and what to do afterwards. Combined with the rich input schema, an agent has enough context to invoke the tool correctly and interpret the high-level result categories. The per-verdict handling is left to the payment path, which the description explicitly states.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 36%, so the description needs to compensate, and it does meaningfully. It names the caller's economic inputs (customer_revenue, value_of_success, max_budget, required_margin, failure_cost, switching_cost), explains revenue_models derivation rules per type, and clarifies that RETURNS_ROI's expected_return is caller-owned. It also advises preferring the LIVE 402 amount for provider_candidates. Some parameters such as task_id and currency are left entirely to the schema, so the compensation is strong but not complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise, action-oriented role: 'Call this immediately before your agent pays an x402/API provider' and names the exact return verdicts (ALLOW / FALLBACK / DECLINE / INSUFFICIENT_EVIDENCE). It explicitly distinguishes itself from advice and from ranking, making its unique function clear. The sibling tools are unrelated (commerce search/vet/schema freshness), so there is no ambiguity in the tool's domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an explicit temporal instruction ('immediately before your agent pays') and a follow-up protocol ('Report the result afterwards to /v1/gate/outcome'). It also explains the payment flow: omit payment_signature to receive terms, call again with it to run, paid per decision or prepaid, and free for cached decisions or INSUFFICIENT_EVIDENCE. This is enough to route an agent through the correct sequence without additional inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ghost-x402-market-intel-vet-schema tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.2/5.0

Disambiguation4/5

Each tool targets a distinct stage of the x402 provider workflow: search for provider selection, vet for a single known provider, pre_spend_gate for task-level payment economics, and schema_freshness for contract drift. Search and pre_spend_gate both surface payment-related decisions, but their descriptions make the separation relatively clear.

Naming Consistency3/5

All tools share the ghost_ prefix and snake_case style, which is consistent at a high level. However, the pattern is mixed: commerce_search and commerce_vet are verb-oriented, while pre_spend_gate and schema_freshness are noun-oriented, so there is no uniform verb_noun convention.

Tool Count5/5

Four tools is well-scoped for a focused market-intel, vetting, and schema-freshness server. Each tool covers a distinct part of the pre-payment decision workflow without redundancy or bloat.

Completeness5/5

The tool surface covers the full apparent lifecycle: discovering and ranking providers, vetting a named provider, making a task-specific pre-payment decision, and checking schema freshness before repeated use. No obvious dead-end or missing operation is apparent from the domain implied by the tools.

Resources

Need Help?