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 7 tools
Each tool targets a distinct step in the order lifecycle: search_catalog for discovery, get_service for one service's detail, recommend_service for plan selection, get_quote for exact pricing, create_paid_order for purchasing, get_paid_order_status for individual tracking, and list_paid_orders for history. Even the overlapping-looking tools are clearly separated by role (find vs. fetch vs. recommend vs. quote vs. execute).
All tools follow a consistent verb_noun pattern in snake_case: create_, get_, list_, recommend_, search_. The few multi-word objects like paid_order_status and paid_order are still grammatically uniform, and there are no camelCase or symbol mismatches.
Seven tools is a well-scoped size for a commerce/ordering domain. Each tool covers a genuine phase of the user journey (discover, choose, price, pay, track, list) without redundancy or bloat.
The surface covers the full ordering workflow: browsing, detail lookup, intelligent recommendation, price quoting, paid order placement, status polling, and order listing. There are no dead ends; any tool's output feeds logically into the next step, and accountless payment is handled within create_paid_order.
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.
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).
| 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it enumerates the returned plan fields (id, name, price per 1000, min/max quantity, quality tier, typed axes, delivery speed, recommended flag) and discloses an operational condition, that the endpoint only lists while the accountless x402 payment channel is on. That is real behavioral context not present in structured fields.
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 and routing alternatives are front-loaded, which is exactly right for selection. It runs long in the middle, with a dense parenthetical inventory of every returned field, but that detail is justified because there is no output schema; minor trimming is possible.
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 and a single parameter, the description carries the burden of explaining return values and does so completely, including the plan-level fields and the downstream service_option_id handoff. The only soft spot is the trailing x402 aside, which is slightly cryptic but does not block correct invocation.
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?
One parameter with 100% schema description coverage that already states the id comes from search_catalog, so the schema carries the load and the baseline is 3. The description reinforces provenance but adds no syntax or format detail beyond the schema; the service_option_id mentioned is an output, not this tool's input.
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 gives a specific verb+resource ('Look up ONE service you already have the id for') and immediately scopes it against siblings, explicitly noting that search_catalog finds ids and recommend_service picks a single option. An agent can distinguish it from all six siblings 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?
It states the precondition ('you already have the id'), the fallback for when that precondition fails ('No id yet? Find one with search_catalog'), and the alternative for the selection use case ('Use recommend_service'), plus the downstream handoff to get_quote and create_paid_order. When-to-use and when-to-use-something-else are both explicit.
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).
| 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 mark the tool as readOnly and idempotent, but the description goes much further: it states 'Read-only: it places no order,' clarifies that prices are live at order time and quoted_at is not a price hold, explains the catalog_version mechanism for staleness detection, and details the semantics of the reasons field ('absence is never a drawback'). It also discloses the 'sensitive flag' behavior and the 'tradeoffs' structure. No contradictions with annotations.
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 description is long but front-loaded with the core purpose and differentiation. Every subsequent sentence adds critical operational detail (return fields, pricing semantics, safety caveats, parameter relationships). Despite its length, there is no redundancy; each section earns its place given the tool's complexity (7 parameters, nuanced behavioral rules).
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 carries the full burden of explaining return values, which it does thoroughly: it lists the recommended option plus three alternatives, the fields each pick carries (price per 1000, total, quantity range, quality tier, typed axes, delivery speed, start window, sensitive flag, reasons), and the response-level fields (quoted_at, catalog_version, considered/fit/rejected counts, tradeoffs). It covers both how to use the result and how to chain it with other tools (pass option_id to get_quote/create_paid_order).
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?
Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains the service_id vs platform+goal tradeoff, how priority selects the lead ('fastest ranks on the LISTED delivery rate then start window'), and how audience format works. It also clarifies the relationship between quantity and picks ('every pick accepts it'). These enrich the schema's basic definitions.
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 states a specific verb and resource: 'Choose WHICH plan option to order', and immediately distinguishes it from siblings by saying 'Use it instead of comparing options yourself from search_catalog or get_service.' It also clarifies the input alternatives (service_id or platform+goal), making the tool's role unambiguous.
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?
The description gives explicit when-to-use guidance: 'once you know what to buy and for how many.' It explicitly contrasts with siblings and names the alternative: 'instead of comparing options yourself from search_catalog or get_service.' It also instructs how to use it for choosing and explaining, and warns against certain user presentations ('never present a pick to the user as a percentage more expensive').
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) 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 the safety profile is covered. The description adds real value beyond that: the per-result payload shape (service + plan options), the paging contract (total/limit/offset/returned with the concrete offset+=limit pattern), and the note that this endpoint lists service_option_id while the accountless x402 channel is on. Missing only rate/quota details, which are minor here.
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 decision cue ('START HERE') and organized body-then-workflow. The single dense paragraph packs several ideas (routing, payload, pagination, next step) without wasted sentences, though it runs long and could be split for scanability.
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, and the description compensates by enumerating the exact fields returned for services and their plan options, plus the pagination fields. Combined with the full parameter schema, an agent has enough to call and consume this tool 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 a baseline of 3 applies, but the description adds intent-mapping guidance not in the schema: 'map the user's natural-language intent (budget, country, speed) onto the structured filters below', which ties budget/speed/geo requests to min_price/max_price/speed_tier/country. That is genuine semantic value on top of the 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?
Specific verb+resource ('Searches the sellable social growth service catalog') with explicit scope (Telegram, Instagram, TikTok, YouTube). It explicitly distinguishes itself from the two closest siblings, get_service and recommend_service, by naming the exact situation each covers.
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?
Opens with 'START HERE when you do not yet know which service to buy' and gives a precise routing rule for both alternatives: 'Already have a service id? get_service...' and 'Know the service and only need the right plan? recommend_service...'. It also tells the agent what to do with results (present plans, pass service_option_id to get_quote/create_paid_order) rather than defaulting to the cheapest.
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_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_catalogMarket 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
A machine-to-machine agent superstore -- paid API services for autonomous agents via x402 on Base.
Add one secure layer between your agents and this server.
