Data feeds for AI agents: list products, sign up, check balance, get a top-up link, fetch data.
Scored across 6 tools
Each tool targets a clearly distinct action: account management, data fetching, product lookup, top-ups, catalogue listing, and sign-up. Even the two catalogue tools are cleanly separated by list vs. single-item retrieval.
Most tools follow a clear verb_noun pattern: fetch_data, get_product, get_topup_link, list_products. account_status and sign_up deviate slightly, but the overall style is consistent and predictable.
Six tools is well-scoped for this server's purpose: account creation, catalogue exploration, data retrieval, and billing/top-up. Each tool earns its place with no redundancy.
The core workflow is covered end-to-end: sign up, discover products, fetch data, check status, and top up. A login/reconnect tool is hinted at but not provided, which is a minor gap rather than a blocking one.
Reads the account behind the secret: tier, accepted Terms version, the products it may call, the balance in credits the account bought minus the spend those credits funded, the last 30 days of usage per day, product and key, and the 50 latest balance movements. A product's own daily credits are spent before that balance and are no part of it, so a call can be served while it reads zero; list_products carries each product's credit account. Pass the secret sign_up returned as the secret argument; the data key your client configuration sends cannot read the account and answers 403 wrong_credential. Charges nothing; without a string the platform answers 401 invalid_key.
| Name | Required | Description | Default |
|---|---|---|---|
| secret | No | the account's secret — the string sign_up returned as secret; the client configuration's header holds the data key, which this tool cannot use; when both are present the argument wins |
| Name | Required | Description |
|---|---|---|
| body | No | |
| fault | No | |
| usage | No | |
| record | No | |
| status | No | |
| account | No | |
| headers | No | |
| upstream | No | |
| body_text | No | |
| configure | No | |
| transport | No | |
| key_source | No | |
| request_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive; the description adds meaningful non-obvious behavior beyond that: the request charges nothing, wrong credentials return specific errors (401/403), and the account balance excludes product daily credits. No contradiction 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 every clause carries information, including error cases and credential routing. It is front-loaded with the core action and return contents; a slight readability cost comes from packing all caveats into two long sentences.
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?
Coupled with an existing output schema and annotations that already establish read-only/idempotent behavior, the description covers authentication, pricing, error behavior, and credit semantics. Nothing needed for correct invocation 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?
Although the schema covers the parameter well, the description adds crucial provenance and precedence: the secret must come from sign_up, a client-config data key is not sufficient, and if both are supplied the secret argument wins. This is information an agent cannot infer from the schema alone.
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 opens with 'Reads the account behind the secret', a specific verb plus a clearly bounded resource, then enumerates the principal data returned (terms version, products, balance, usage, movements). It also distinguishes itself from list_products by pointing out where product-specific credit accounts live, so an agent can tell sibling tools apart.
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 concrete when-to/not-to guidance: it tells the agent the secret must come from sign_up, that the client configuration's data key will not work and yields 403, and that a missing string yields 401. It also directs product-level credit inquiries to list_products, making the boundary between the two tools explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches one data response: GET data.forum.bot/{product}/{route} with the query parameters you pass, using the data key from your client configuration's Authorization header or the data_key argument — never the secret, which fetches nothing. A successful call is billed the product's price per call; a refused call costs nothing. The result carries the payload with the platform's meta block (licence and attribution) and the rate-limit headers; the balance is read with account_status, never from a data response. Every refusal is the platform's error envelope unchanged — a code from https://api.forum.bot/errors.json; 402 payment_required means the key is known but cannot pay for this product now, and 401 invalid_key means it is authorized for no product at all, most often because every credit is spent. Both carry an action_url: a human tops up there (get_topup_link returns the page) and the same key serves again within the engine's build interval plus the region's poll interval.
| Name | Required | Description | Default |
|---|---|---|---|
| route | Yes | a route from get_product, without the product prefix — e.g. current or timeline/1h | |
| params | No | query parameters, sent as given; the parameters a route requires are in get_product | |
| product | Yes | a product slug from list_products | |
| data_key | No | only when the client cannot send an Authorization header — the data_key.key sign_up returned in this session; when both are present the argument wins |
| Name | Required | Description |
|---|---|---|
| body | No | |
| fault | No | |
| usage | No | |
| record | No | |
| status | No | |
| account | No | |
| headers | No | |
| upstream | No | |
| body_text | No | |
| configure | No | |
| transport | No | |
| key_source | No | |
| request_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, indicating a safe read operation. The description adds significant behavioral context: it explains that successful calls are billed, refused calls cost nothing, and details the error envelope structure with specific HTTP status codes (402, 401) and their meanings. It also mentions the rate-limit headers. However, it doesn't delve into what happens on success in terms of data structure beyond 'meta block', but annotations cover safety.
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 a single dense paragraph, which is structured but lengthy. It front-loads the core action and endpoint, then explains billing, errors, and alternatives. Each sentence provides valuable information, but the density may make it less scannable. It's not overly verbose, but could be broken into shorter sentences for clarity.
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?
Given the tool's complexity (billing, authentication, error handling) and the rich output schema, the description covers critical details: billing per call, balance read via account_status, error envelope with action_url, and top-up flow. The output schema exists, so return values need not be detailed. The description is complete for an agent to call this tool correctly in various scenarios.
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 schema already documents all parameters well. The description adds extra context for the 'data_key' parameter, explaining it's only when the client cannot send an Authorization header, and clarifies the precedence when both are present. It also gives hints about 'route' and 'params' referencing get_product, but doesn't add much beyond schema. Baseline 3 is appropriate as schema does the heavy lifting.
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 clearly states that the tool fetches one data response via a GET request to a specific endpoint, with the product and route as key parameters. It distinguishes itself from siblings by mentioning account_status for balance and get_topup_link for top-up, but it doesn't explicitly differentiate from other fetch-related tools, though none are present. The verb 'fetches' and resource 'data response' are specific.
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 guidance on when to use this tool: it explains that the balance is read with account_status (not from a data response), and that get_topup_link is used for top-up. It also explains how to handle errors, such as using the action_url for top-up. This clearly excludes alternatives and provides context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one product by slug: its live catalogue entry (price, licence, lifecycle state, the specification address) together with the routes fetch_data can call and the parameters each route requires, taken from the platform's published product record. Needs no key and charges nothing. Use it before fetch_data — the route names come from here; an unknown slug answers with the slugs the catalogue serves.
| Name | Required | Description | Default |
|---|---|---|---|
| product | Yes | a product slug from list_products |
| Name | Required | Description |
|---|---|---|
| body | No | |
| fault | No | |
| usage | No | |
| record | No | |
| status | No | |
| account | No | |
| headers | No | |
| upstream | No | |
| body_text | No | |
| configure | No | |
| transport | No | |
| key_source | No | |
| request_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds non-obvious context: no API key is needed, it charges nothing, data comes from the platform's published product record, and an unknown slug returns the catalogue's served slugs. There is no contradiction with the 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?
Three sentences, with the core return value front-loaded, followed by usage guidance and an edge case. Every clause adds value: content, routing, auth/cost, or error behavior. No fluff or 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 single-parameter read-only tool with an output schema and strong annotations, the description covers output content, its relationship to fetch_data, error behavior, and authentication/cost. Nothing an agent needs to invoke 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?
The schema already documents the only parameter product at 100% coverage, including its pattern and source ('a product slug from list_products'). The description reinforces that the parameter is a slug and adds unknown-slug behavior, but it does not significantly extend the schema's parameter semantics.
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 opens with a specific verb and resource: 'Returns one product by slug' and enumerates the contained catalogue fields (price, licence, lifecycle state, specification address) plus route data for fetch_data. This clearly differentiates it from list_products and fetch_data.
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 explicitly instructs 'Use it before fetch_data' and explains that route names come from this tool. It also describes the unknown-slug fallback. It does not explicitly name list_products as an alternative, but the 'one product by slug' scope and the input schema's reference to list_products make the selection context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Opens a top-up for the account and returns the payment intent with hosted_url, the payment provider's short-lived page where a human completes the payment — no tool pays, and card details never touch the Forum. amount_minor is in cents; the platform accepts USD only and a minimum of 1000 (= $10). Pass the secret sign_up returned as the secret argument; the data key cannot open a payment. Asking again while a page is open returns the same page. Bought credits appear in account_status once the payment completes.
| Name | Required | Description | Default |
|---|---|---|---|
| secret | No | the account's secret — the string sign_up returned as secret; the data key in the client configuration cannot open a payment; when both are present the argument wins | |
| currency | No | USD is the only currency the platform accepts; the platform refuses any other | USD |
| amount_minor | Yes | the amount in the currency's minor unit (cents); the platform's minimum is 1000 = $10 and the platform checks it |
| Name | Required | Description |
|---|---|---|
| body | No | |
| fault | No | |
| usage | No | |
| record | No | |
| status | No | |
| account | No | |
| headers | No | |
| upstream | No | |
| body_text | No | |
| configure | No | |
| transport | No | |
| key_source | No | |
| request_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the tool only opens a top-up and does not execute payment, that card details never reach the Forum, that the returned hosted_url is short-lived, that repeat calls while a page is open return the same page, and that credits appear in account_status upon completion. This is exactly the behavioral context an agent needs.
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 compact and front-loaded: the core action and the most important caveat ('no tool pays') come first, and each subsequent sentence adds a distinct, necessary fact. There is no filler or redundant framing.
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?
Given the output schema and annotations, the description covers all essential operational context: authentication via the secret, currency and amount constraints, idempotent behavior, the external payment page, and the post-payment effect on account_status. An agent has everything needed to invoke the 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%, and the schema already documents the cent-based amount, the $10 minimum, USD-only acceptance, and the secret-vs-data-key restriction. The description reinforces these details but adds little beyond what the parameter descriptions already provide, so it stays at the baseline for high schema coverage.
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 action — 'Opens a top-up for the account and returns the payment intent with hosted_url' — and clearly distinguishes this from paying, noting that no tool pays and a human completes payment on the provider page. This makes it easy to tell get_topup_link apart from sign_up and account_status.
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 strong usage context: pass the secret returned by sign_up, never the data key, and understand that repeated calls while a page is open return the same page. It stops short of explicitly naming sibling alternatives and saying 'use X instead of Y,' but the when-not guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every data product the Forum serves, as the platform's own catalogue answer: slug, title, lifecycle state, price in credits per call (1 credit = $0.001; the quoted price is the charged price), licence and attribution text, and the address of the product's route specification. Needs no key and charges nothing. Call get_product next for a product's routes and required parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| body | No | |
| fault | No | |
| usage | No | |
| record | No | |
| status | No | |
| account | No | |
| headers | No | |
| upstream | No | |
| body_text | No | |
| configure | No | |
| transport | No | |
| key_source | No | |
| request_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: no authentication key needed, no cost, and the price semantics including the credit conversion and charged-price guarantee.
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, each earning its place: the main scope and output fields, the auth/cost caveat, and the routing to get_product. Front-loaded and free of filler.
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?
The description is complete for a zero-parameter, read-only tool. It covers what is returned, the access and cost profile, and the natural next step; an output schema handles the detailed return shape.
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?
The tool takes zero parameters and schema coverage is 100%, so parameter semantics are effectively moot. The baseline of 4 applies because there are no parameters to clarify.
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: 'Lists every data product the Forum serves', and enumerates the exact fields returned. The phrase 'platform's own catalogue answer' clearly distinguishes it from get_product and other siblings.
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?
Clear context is provided: it is the catalogue tool, requires no key, and charges nothing. It also directs the agent to call get_product next for routes and parameters, though it does not explicitly say when not to use list_products.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a Forum account for an email address under the Terms version currently served, and returns the account, its secret — the one string that runs the account, shown exactly once — and its first data key, shown exactly once. It grants the account no credits of its own: a new account's free calls are the daily credit account of each product that gives one, spendable on that product alone and replaced every night, and list_products states which products give one and how much. The result's configure block is the client configuration entry that sends the data key from then on; until the client reconnects, pass data_key.key as data_key on fetch_data. Keep the secret with the owner and pass it as secret on account_status and get_topup_link. An address that already has an account answers 409 email_exists with next_action login_to_link.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | the owner's email address — the account's identity; one account per address |
| Name | Required | Description |
|---|---|---|
| body | No | |
| fault | No | |
| usage | No | |
| record | No | |
| status | No | |
| account | No | |
| headers | No | |
| upstream | No | |
| body_text | No | |
| configure | No | |
| transport | No | |
| key_source | No | |
| request_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false, so the tool is a mutating, non-idempotent operation. The description adds critical behavioral details: the secret is shown exactly once and the data key is shown exactly once, the account gets no credits of its own (free calls come from daily credit accounts), and the 409 behavior on existing address. These add value beyond annotations, but the description does not fully disclose that the secret must be stored by the owner (it says 'Keep the secret with the owner' – that is guidance, not disclosure of data loss risk). There is no contradiction. Given the annotations already reveal mutation, the description adds useful but not exhaustive behavioral context, so a 3 is fair.
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 relatively dense but packs a lot of essential info. It is front-loaded with the primary action, then details the special outputs (secret, data key), the credit behavior, the configuration usage, and the error case. It could be slightly more concise but every sentence carries necessary information. No redundancy with schema. A 4 is appropriate.
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?
The tool has an output schema, which likely documents the return structure, so the description need not explain return values. Given that, the description covers all essential usage context: credential handling, secret usage, data key usage, credit behavior, and error handling. It is complete for a complex sign-up flow. The only minor gap is a explanation of the 'configure block' format, but that is likely in the output schema. A 4 is justified.
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 describes the 'email' parameter fully (owner's email, account identity, one account per address) and coverage is 100%. The description does not repeat the schema's parameter description but adds contextual meaning: it explains that the email will be the identity and that an existing address gets a 409. This adds value beyond the schema (e.g., the one-account-per-address constraint and the error case). Since schema coverage is high, baseline is 3, and the description adds extra meaning, a 4 is appropriate.
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 clearly states a specific action ('Creates a Forum account') on a specific resource (an email address), and distinguishes the result's unique aspects (secret shown once, data key shown once). It clearly differentiates from siblings by describing what this tool does and what it does not do (grants no credits), which no other sibling description does here.
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: needed for account creation for an address. It also provides clear when-not: 'An address that already has an account answers 409 email_exists with next_action login_to_link.' This guides the agent to handle this case and implies alternative action (login). It also explains how to use the returned data (configure block, data_key) and the secret for later calls (account_status, get_topup_link).
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.
account_statusfetch_dataget_productget_topup_linklist_productssign_upOpenWeather data for AI agents: list feeds, sign up, check balance, get a top-up link, fetch data.
Real-time data feeds for AI agents with USDC micropayments on Base for premium tools.
Prepaid balance for AI agents: one key, 4,900+ tools your agent can run today, caps, receipts.
140+ data APIs for agents: finance, banking validation, geo, weather, text. One API key.
Add one secure layer between your agents and this server.
