GrowVib is an AI-native SMM and social media growth marketplace for autonomous agents. Search and compare services across Instagram, TikTok, YouTube, Telegram, X, Facebook, Twitch, Spotify and 50+ other platforms. Buy followers, views, likes, subscribers, members, reactions and engagement. GrowVib provides canonical service classification, recommendations with reasons and quantitative trade-offs, live quotes, and accountless USDC purchases via x402 on Base and Solana.
Scored across 9 tools
Most tools have clearly distinct purposes, and descriptions explicitly cross-reference each other (search_catalog = 'START HERE', get_service = 'already have an id', recommend_service = 'need the right plan'). The two payment paths (create_checkout vs create_paid_order) and their status counterparts (get_checkout_status vs get_paid_order_status) could still be confused, but descriptions give clear guidance on when to prefer each.
Every tool follows a consistent snake_case verb_noun pattern (create_checkout, get_quote, list_paid_orders, recommend_service, search_catalog). Verbs map predictably to actions (create/get/list/search/recommend), with no style mixing.
Nine tools is well-scoped for a catalog-plus-ordering-plus-payment domain. Each tool earns its place: discovery (search/get/recommend), pricing (get_quote), two payment flows, and their status/list tracking.
The surface covers the full buy flow: search → inspect → recommend → quote → order/checkout → track status → list orders. However, there is no tool to cancel or refund an order despite statuses like CANCELED and REFUNDED existing, and account connection is only reachable via an external OAuth endpoint rather than a tool.
Create a checkout session: a payment link a PERSON opens and pays in their own USDC wallet (Base or Solana), for when you cannot sign a payment yourself or the user wants to pay with their own wallet. Pick the service with search_catalog or recommend_service and price it with get_quote first, then call this with service_id, quantity and link. The result carries page_url (give it to the person), the exact amount, expires_at (the price is held until then, 30 minutes by default) and a token for get_checkout_status. Creating a session moves no money and reserves nothing: nothing is charged until the person signs in their wallet, and an unpaid session simply expires. Each call opens a NEW session, so call it once per intended order and reuse the token you were given. Prefer create_paid_order when you hold a wallet and should pay yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| link | Yes | The target link the order is delivered to. | |
| quantity | Yes | Quantity to order. | |
| return_url | No | Optional https URL shown to the person as a link after paying (where they came from). Never followed by the server. | |
| service_id | Yes | The service id from search_catalog. | |
| ttl_seconds | No | Optional: hold the price for LESS than the default 30 minutes. A larger value is clamped to the default, never granted. | |
| external_ref | No | Optional reference of your own (an order or conversation id, at most 128 characters), echoed by get_checkout_status. | |
| service_option_id | No | Optional specific service option id; defaults to the service's primary option. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (not read-only, not idempotent, open-world), and the description adds substantial context beyond them: no money moves, nothing is reserved, nothing is charged until the person signs, unpaid sessions simply expire, and each call opens a NEW session so the token must be reused rather than the tool re-called.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded and the sentences are dense with actionable detail. There is mild redundancy between "moves no money and reserves nothing" and "nothing is charged until the person signs", but overall the length is justified by the workflow and return-value guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the returned fields (page_url, exact amount, expires_at, and a token for get_checkout_status), and it covers prerequisites, side effects, expiry behavior, and the sibling alternative. Nothing needed to call or follow up correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description still adds ordering semantics (price with get_quote first, then pass service_id/quantity/link) and explains that ttl_seconds holds the price with a 30-minute default, which reinforces the parameter's effect rather than merely restating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Create a checkout session") and immediately characterizes it as a payment link a person opens and pays in their own wallet on Base or Solana. It explicitly distinguishes itself from create_paid_order, so an agent can route correctly without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use condition ("when you cannot sign a payment yourself or the user wants to pay with their own wallet"), names the alternative with the opposite condition ("Prefer create_paid_order when you hold a wallet and should pay yourself"), and prescribes the upstream workflow (search_catalog / recommend_service then get_quote).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Place an order and pay for it with USDC on Base or Solana, with no GrowVib account and no human in the loop, using the x402 payment protocol. Call it FIRST without the payment argument: it returns the exact payment requirements, one accepts entry per network (amount in atomic units, asset, recipient, network, and for Solana the facilitator's feePayer). Pick the network your wallet is on: sign an EIP-3009 transferWithAuthorization (Base) or build and sign the USDC transfer transaction (Solana) for exactly those requirements, then call it AGAIN with the same arguments plus payment set to the signed x402 payment payload. Anything paid above the order's price stays as spendable balance on the wallet's account, so many small orders can be paid for with one settlement. If a call reports that the payment is still being confirmed, do NOT sign and send a new payment: the first one may already have gone through. Use get_quote first if you only want a price.
| Name | Required | Description | Default |
|---|---|---|---|
| link | Yes | The target link the order is delivered to. | |
| payment | No | The signed x402 v2 payment payload. Omit on the first call to receive the payment requirements. | |
| quantity | Yes | Quantity to order. | |
| service_id | Yes | The service id from search_catalog. | |
| agent_token | No | The agent_token from a previous order's result. Send it INSTEAD of `payment` to pay out of the balance you already hold, with no new signature and nothing on chain. Requires `idempotency_key`. If your balance does not cover the order you get the payment requirements back as usual. | |
| idempotency_key | No | A value unique to this order attempt (a UUID is fine), required when using `agent_token`. Sending the same key again returns the SAME order instead of buying a second time, so a retry after a timeout is safe. | |
| service_option_id | No | Optional specific service option id; defaults to the service's primary option. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds rich behavior beyond annotations: two-phase protocol flow, overpayment retained as spendable balance, idempotency via idempotency_key/agent_token instead of new signatures, and the retry-safety warning about pending confirmations. Annotations cover the safety flags; the description supplies the operational protocol context they cannot.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the two-phase instruction and network selection before edge cases, and every sentence earns its place. It is dense but justified for a multi-step protocol tool; slightly verbose for a single paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A 7-param destructive, open-world mutation tool with no output schema is fully covered: purpose, phased calling, network/asset handling, balance/idempotency, and retry semantics. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description meaningfully explains the unusual semantics: `payment` is a signed x402 payload omitted on the first call, and the `agent_token`/`idempotency_key` pairing for balance payment. It adds protocol-level meaning the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('place an order and pay for it') with the exact payment rails (USDC on Base/Solana via x402) and the differentiating constraint (no account, no human). It explicitly routes to sibling get_quote for price-only use, distinguishing it from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('Use get_quote first if you only want a price'), the exact two-phase call sequence (first without payment, then with), how to select a network, and a critical anti-pattern ('do NOT sign and send a new payment'). Alternatives and exclusions are both named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a checkout session created with create_checkout: its status (open, pending, paid, paid_no_order, failed, expired), the frozen quote, and once paid the payment and the order with its tracking code. Poll it after handing the person the link, every few seconds, until it reports paid or expired. pending means a payment is being confirmed: tell the person to wait, never to pay again. paid_no_order means the money arrived as balance on the paying wallet's account but the order could not be placed; the person was told to contact support. Read-only and idempotent, so polling is safe.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The token from create_checkout's result. It is the session's bearer: whoever holds it can read the session and, while it is open, pay it, so do not post it anywhere but here and the person's own page_url. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive; the description goes well beyond them by decoding each status value, warning never to pay again during pending, explaining that paid_no_order means funds landed as balance but no order was placed, and noting polling is safe. That is real operational context an agent cannot infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and payload, then adds the polling loop and the two ambiguous status meanings. Dense and every sentence carries information, though the status enumeration could be trimmed slightly without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly carries the burden of describing return values: the status set, the frozen quote, and post-payment payment/order/tracking data. Nothing an agent needs to call and interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the token parameter is already fully documented there, including its bearer/security semantics. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read a checkout session created with create_checkout') and enumerates exactly what it returns: status, frozen quote, and once paid the payment and order with tracking code. This clearly separates it from create_checkout and get_paid_order_status without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit operational guidance: poll after handing over the link, every few seconds, until it reports paid or expired, plus what to tell the person for pending and paid_no_order. It does not name a sibling alternative (e.g. get_paid_order_status) for the paid-after-the-fact case, so it falls just short of the top rung.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Track an order placed with create_paid_order: status, start count and remaining quantity. Pass the agent_token that create_paid_order returned (or one from the wallet sign-in at POST /v1/agent/auth/challenge). Read-only and idempotent, so polling it is safe. Statuses: PENDING, SUBMITTED, PROCESSING, COMPLETED, PARTIALLY_COMPLETED, CANCELED, FAILED, PARTIALLY_FAILED, REFUNDED, PARTIALLY_REFUNDED.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | The order_id from create_paid_order. | |
| agent_token | Yes | The agent_token from create_paid_order's result, or from the wallet sign-in. It proves which wallet is asking; an order that is not this wallet's is reported as not found. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, idempotentHint and destructiveHint, so the safety profile is pre-declared. The description adds real value beyond that: the full status enumeration, the authorization semantics (agent_token proves wallet ownership; a foreign order is reported as not found), and the polling-safety guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the purpose, then the credential requirement, then the behavior/status list. Every sentence carries distinct information with no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description names the fields returned and enumerates all possible status values, plus the auth requirement and polling safety. Nothing an agent needs to call and interpret this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both param descriptions already state provenance ('order_id from create_paid_order') and the wallet-proof/not-found behavior. The description essentially restates the schema text rather than adding syntax, formats or edge cases, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (track/get status) plus the exact resource (an order created by create_paid_order) and enumerates the returned fields (status, start count, remaining quantity). The reference to create_paid_order and the contrast with list_paid_orders lets an agent distinguish it from siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: use it to poll an order after create_paid_order, and it explicitly notes polling is safe due to read-only/idempotent behavior. It stops short of naming when to prefer the sibling list_paid_orders (e.g. 'to see all orders, use list_paid_orders instead'), so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the exact price that will be charged, with no account needed. Call this before every order: never total up the per-1000 prices the catalog tools return yourself, because the quantity bounds and rounding are applied here and nowhere else. Returns unit price and total in USD, priced by the same server-side path a real order uses. It places no order and charges nothing. The result's payment_methods says how the order can be paid: from a connected GrowVib account (connect one over OAuth at the /mcp endpoint, which is where the account ordering tool lives), or, when listed, with no account at all over x402 (USDC on Base or Solana, via create_paid_order or the REST endpoint it names; payment_methods.x402.networks lists the rails).
| Name | Required | Description | Default |
|---|---|---|---|
| quantity | Yes | Quantity to order (e.g. number of members or views). | |
| service_id | Yes | The service id from search_catalog. | |
| service_option_id | No | Optional specific service option id; defaults to the service's primary option. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and non-destructive, but the description goes well beyond them: it explains that pricing runs through the same server-side path as a real order, that no order is placed and nothing is charged, and it interprets the shape of the result via payment_methods (connected GrowVib account over OAuth, or x402 with no account). That is exactly the kind of behavioral and auth context annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded with the key constraint ('call before every order, never total prices yourself'), and each sentence carries distinct information. It is somewhat long and dense, especially the final sentence about payment methods and OAuth endpoints, which could be tightened, but nothing is wasted repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a pricing-read tool with no output schema, the description is complete: it states what is returned (unit price and total in USD), how pricing is computed, that no side effect occurs, and how the result maps to payment paths. An agent has everything needed to invoke and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents service_id, quantity and service_option_id. The description adds the procedural context of 'quantity bounds and rounding are applied here,' which is meaningful, but it does not clarify parameter syntax, accepted ranges or option-id sourcing beyond what the schema states. Baseline 3 is appropriate when the schema carries the parameter burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description delivers a precise verb+resource ('Get the exact price that will be charged') and explicitly distinguishes itself from the catalog tools by warning not to total up per-1000 prices yourself. It also frames itself relative to the ordering siblings by defining what it does NOT do ('places no order and charges nothing'). An agent can cleanly separate this from search_catalog and create_paid_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit workflow directive: 'Call this before every order,' states the alternative behavior to avoid ('never total up the per-1000 prices the catalog tools return yourself'), and names the real-order path for conversion (create_paid_order / REST endpoint). This is a strong, actionable when-and-how-when-not statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up ONE service you already have the id for. No id yet? Find one with search_catalog. Want a single option chosen for a quantity rather than all of them? Use recommend_service. Returns the service's full detail, including ALL of its plan options (id, name, price per 1000, min/max quantity, quality tier, typed axes such as country or watch length, listed delivery speed and start window, and the recommended flag), so you can present the available plans and quantity range to the user, then pass the chosen service_option_id to get_quote and create_paid_order (this endpoint lists it while the accountless x402 payment channel is on), or create_checkout when a person will pay in their own wallet instead (listed while checkout sessions are on).
| Name | Required | Description | Default |
|---|---|---|---|
| service_id | Yes | The service id from search_catalog. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety bar is pre-cleared. The description adds real value beyond that: it enumerates the returned payload (all plan options with price per 1000, min/max quantity, quality tier, typed axes, delivery speed, recommended flag) and notes the conditional availability of the x402 and checkout flows. It stops short of pagination or size/rate limits, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the two alternatives, then the return payload, then downstream routing. Every sentence carries information, though the parenthetical conditionals about which endpoints are 'listed' make the tail dense and slightly harder to scan than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully compensates by detailing exactly what is returned (plan-level fields and the recommended flag) and how to use the result downstream. An agent has everything needed to call this correctly and interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter and schema description coverage is 100%, so the schema already defines service_id and its origin ('from search_catalog'). The description reinforces this ('you already have the id for') but adds no format, validation, or edge-case detail beyond the schema, matching the baseline 3 for a fully covered schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Look up ONE service') and immediately scopes it to a known id. It explicitly differentiates itself from search_catalog (when no id exists) and recommend_service (when a single option is wanted), so an agent can pick it without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use routing ('No id yet? Find one with search_catalog', 'Want a single option...? Use recommend_service') and names the downstream consumers of the returned service_option_id (get_quote, create_paid_order, create_checkout). Nothing about selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the orders belonging to the wallet behind an agent_token, newest first, each with the same fields get_paid_order_status returns. Use it when you no longer have the order_id an order gave you: after a restart, when resuming work another session started, or to check everything this wallet has bought. Pass the agent_token from any of its orders (or from the wallet sign-in at POST /v1/agent/auth/challenge). Optional status narrows to one order status, page and page_size page through the rest (page_size defaults to 10 and is capped at 100; the result carries the total so you know when to stop). Read-only and idempotent, so polling it is safe.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number (default 1). | |
| status | No | Optional order status to filter by: PENDING, SUBMITTED, PROCESSING, COMPLETED, PARTIALLY_COMPLETED, CANCELED, FAILED, PARTIALLY_FAILED, REFUNDED or PARTIALLY_REFUNDED. | |
| page_size | No | Rows per page (default 10, maximum 100). | |
| agent_token | Yes | The agent_token from one of this wallet's orders, or from the wallet sign-in. It proves which wallet is asking; only that wallet's orders are returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, yet the description adds real value: newest-first ordering, the fact that the result carries a total so pagination termination is knowable, and that polling is safe. It partially restates the read-only/idempotent hints, which is why it is not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense but well-ordered paragraph: purpose, then when-to-use, then parameters, then safety. Nothing is wasted, though it is long enough that a reader must work through it rather than skim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by stating that rows carry the same fields as get_paid_order_status and include a total for pagination. Combined with the annotation-supplied safety profile, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description goes further: it tells the caller where to obtain agent_token (from any of its orders or the wallet sign-in endpoint) and how paging terminates via the returned total. These are usage semantics the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list orders for the wallet behind an agent_token) plus the ordering (newest first) and scope (only that wallet's orders). It is cleanly separable from the sibling get_paid_order_status, which returns one order by id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the trigger conditions: when you no longer hold the order_id, after a restart, or when resuming another session's work. The alternative (get_paid_order_status with an order_id) is implied by contrast, so the agent knows which tool to pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Choose WHICH plan option to order, once you know what to buy and for how many. Use it instead of comparing options yourself from search_catalog or get_service. Takes a service (or a platform plus a goal), a quantity, an audience and a preference. Returns one recommended option plus the cheapest, highest-tier and fastest-listed alternatives. Each pick carries the price per 1000, the total for this quantity, the quantity range it accepts, its quality tier, typed axes such as country or watch length, the listed delivery speed and start window, a sensitive flag marking a deliberate product such as a negative reaction, and short reasons written for the buyer. Branch on the typed fields; the reasons are prose in the requested locale and state only what an option gives, so their absence is never a drawback. One reason states how many independent delivery pools can serve the option, when two or more can: it is a count of the ways we can deliver it, not a promise about any one order, and a pick without it is not worse. The response also says how many options were considered, how many fit, and why the rest fell out (rejected: audience_mismatch, quantity_below_min, quantity_above_max, dominated). It carries quoted_at and catalog_version: the version fingerprints the option data the answer came from, so if you recommend, ask the user, then order, re-call and compare catalog_version to know whether the card changed in between. Prices are live at order time; placing an order re-prices from the same data get_quote does, so treat quoted_at as when this answer was computed, not as a price hold. tradeoffs compares each alternative with the lead as data (price and total deltas, quality steps, listed speed ratio, start bucket delta, max quantity delta, plus gives and costs naming the dimensions it wins and loses on; null means one side lists nothing). Use it to CHOOSE and to explain a choice as what each option gives ("$18.60 less for one tier lower and twice the listed rate"); never present a pick to the user as a percentage more expensive than another. Identify the service by service_id (from search_catalog) OR by platform + goal (the deliverable, e.g. platform "youtube" and goal "short-views" or "followers"). Read-only: it places no order. Pass the returned option_id as service_option_id to get_quote and create_paid_order (this endpoint lists it while the accountless x402 payment channel is on), or create_checkout when a person will pay in their own wallet instead (listed while checkout sessions are on).
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | The deliverable metric key (followers, likes, views, short-views, members, comments, ...). Used with platform when service_id is omitted. | |
| locale | No | Language of the option labels and the reasons: en (default), fa, ru, uz or id. The typed fields are locale-independent, so pass the user's language freely. | |
| audience | No | "worldwide" (default) for untargeted delivery, or "<axis>:<value>" such as "country:usa" or "emoji:❤️". The response lists the audiences the service serves. | |
| platform | No | Platform key (telegram, instagram, tiktok, youtube, ...). Used with goal when service_id is omitted. | |
| priority | No | "balanced" (default), "cheapest", "quality" or "fastest": which pick leads. fastest ranks on the LISTED delivery rate then start window (the listing's own claims); when no eligible option lists either it falls back to balanced. | |
| quantity | Yes | The quantity the user wants to order; every pick accepts it. | |
| service_id | No | The service id from search_catalog. Optional when platform and goal are given. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces 'Read-only: it places no order' while adding substantial context they cannot: live pricing at order time, quoted_at as computation time not a price hold, catalog_version as a change-detection fingerprint, and the meaning of the delivery-pool count. This is rich behavioral disclosure well beyond the annotation set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded, but the body is a dense wall of run-on sentences with repeated disclaimers ('their absence is never a drawback,' 'a pick without it is not worse'), which restate the same caveat. Much earns its place, but the volume and repetition hurt parseability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description carries the return-value burden and does so thoroughly: the lead pick plus three alternatives, the typed fields, the rejection reasons, tradeoffs semantics, and the catalog_version comparison workflow. An agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema cannot: the service_id XOR platform+goal identification strategy, the fastest fallback behavior for priority, and the audience axis format. It clarifies how parameters combine rather than just restating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Choose WHICH plan option to order,' and immediately scopes it ('once you know what to buy and for how many'). It explicitly distinguishes itself from siblings search_catalog and get_service, so an agent can tell what this does without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('instead of comparing options yourself'), names the alternatives it replaces (search_catalog, get_service), and routes the result forward to get_quote/create_paid_order/create_checkout with the exact field (option_id as service_option_id). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
START HERE when you do not yet know which service to buy: this is the entry point to the catalog. Already have a service id? get_service returns that one in full detail. Know the service and only need the right plan for a quantity? recommend_service picks one. Searches the sellable social growth service catalog (Telegram, Instagram, TikTok, YouTube and more). Each result includes the service (id, name, platform, starting/cheapest price per 1000) AND its plan options (each with id, name, price per 1000, min/max quantity) - present the options to the user and let them choose a plan, then pass that service_option_id to get_quote and create_paid_order (this endpoint lists it while the accountless x402 payment channel is on), or create_checkout when a person will pay in their own wallet instead (listed while checkout sessions are on) instead of defaulting to the cheapest.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results per page (1-50, default 20). | |
| query | No | Keyword search over service names and descriptions. Pass concrete keywords (e.g. "telegram members"); map the user's natural-language intent (budget, country, speed) onto the structured filters below. | |
| locale | No | Catalog language for names/descriptions (default en). Each service is returned once per call in this single language. | |
| offset | No | Row offset for paging (default 0). The response returns total, limit, offset and returned; fetch the next page with offset += limit while offset+returned < total. | |
| country | No | Filter to geo-targeted services for a country (matches the catalog's geo-target codes, e.g. a country name or code). Most services are global and unaffected. | |
| sort_by | No | Sort order: "newest" (default) or "name" (alphabetical). | |
| platform | No | Filter by platform key, e.g. telegram, instagram, tiktok, youtube. | |
| max_price | No | Only services whose starting price per 1000 is at most this (USD) - use for a budget cap. | |
| min_price | No | Only services whose starting price per 1000 is at least this (USD). | |
| sort_order | No | "asc" or "desc". Defaults to desc for newest, asc for name. | |
| speed_tier | No | Filter by delivery speed tier (e.g. instant, fast) - use for "fastest delivery" requests. | |
| quality_tier | No | Filter by quality tier, e.g. standard, premium. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real context beyond that: each service is returned once per call in a single language, results bundle service plus its plan options, and it flags that the paid-order and checkout paths are only listed while those channels are enabled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The routing information is front-loaded and every sentence carries signal. The final sentence is a run-on with nested parentheticals and a duplicated 'instead' ('...or create_checkout when a person will pay... instead of defaulting to the cheapest'), which costs some readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the return shape (service id, name, platform, starting price per 1000, plus plan options with id, name, price per 1000, min/max quantity) and by pointing to the pagination fields. Nothing an agent needs to call and chain this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the schema already documents each filter. The description still adds value by telling the agent to pass concrete keywords to query and to map natural-language intent (budget, country, speed) onto the structured filters, which is usage semantics the schema does not state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Searches the sellable social growth service catalog') and explicitly frames itself as the entry point. It names siblings get_service and recommend_service and the condition under which each is preferred, so an agent can differentiate without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('START HERE when you do not yet know which service to buy'), two when-not-to-use branches with named alternatives, and the downstream routing (pass service_option_id to get_quote/create_paid_order or create_checkout). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_checkoutget_checkout_statuscreate_paid_orderget_paid_order_status2 fields changedInput schema / properties / agent_token / descriptionPrevious value: -"The agent_token from place_paid_order's result, or from the wallet sign-in. It proves which wallet is asking; an order that is not this wallet's is reported as not found."New value: +"The agent_token from create_paid_order's result, or from the wallet sign-in. It proves which wallet is asking; an order that is not this wallet's is reported as not found."Input schema / properties / order_id / descriptionPrevious value: -"The order_id from place_paid_order."New value: +"The order_id from create_paid_order."place_paid_orderlist_paid_ordersget_paid_order_statuspaid_order_statusget_quoteget_servicepaid_order_statusplace_paid_orderrecommend_servicesearch_catalogSMM panel catalog: cheapest services across panels, Trust Scores, reviews, comparisons, panel tools
Market data and web intelligence for AI agents, paid per call in USDC on Base via x402.
AI brand/token visibility, prediction-market odds & cheap x402 data feeds for AI agents.
Hire Vevang's AI agents, pay-per-call in USDC on Base via x402: video, visibility, verify, extract
Add one secure layer between your agents and this server.
