mcp-server

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

No annotations are provided, so the description fully carries the burden. It discloses read-only behavior, no state modification, no payment sending, no upstream API calls, and the requirement for a valid API key. This is comprehensive for a zero-parameter endpoint.

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 concise, front-loaded with 'Read-only', and every sentence serves a purpose: what it returns, auth requirement, use cases, and exclusions. No redundant or vague language.

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 simple zero-parameter, no-output-schema tool, the description is remarkably complete: it details return values (balance, spending, request count), units, authentication, usage guidance, and explicitly states what it does not do. The context is fully covered.

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 has zero parameters, so schema coverage is trivially 100%. The description correctly omits parameter details as none exist; baseline 4 for zero-parameter tools 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?

Clearly states it returns current balance, lifetime spending, and request count with specific units (microdollars and USD). Distinct from siblings by explicitly being read-only and focusing on account/usage information rather than executing calls or queries.

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 advises using before apihub_call or apihub_call_external to confirm sufficient funds and periodically for audits. Also names apihub_topup as the alternative for changing balance, providing clear when-to-use versus alternatives.

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

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

With no annotations, the description carries full burden. It discloses key behaviors: debiting credits, forwarding requests, returning a structured object, requiring API key and balance, and returning 402 on insufficient funds. It does not mention timeout/retry/upstream failure behavior, but the main side effects and error conditions are clearly stated.

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 fairly long but every sentence is informative and well-structured. It front-loads the primary purpose, then covers payment mechanics, prerequisites/errors, and alternatives. No filler or redundancy; it earns its length.

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 no output schema, the description explains the return value (upstream response body, HTTP status, credits_charged_microdollars). It covers prerequisites, error handling, alternative tools, and parameter specifics. The tool has moderate complexity, and the description is thorough enough for an agent to use 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 baseline is 3. The description adds value beyond schema by clarifying that body is ignored for GET/DELETE, forwarded verbatim with Content-Type: application/json, that method must match the endpoint declaration, and that endpoint_path includes a leading slash. This helps correct usage beyond 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 clearly states the tool's core function: calling a paid endpoint on an onboarded APIHub service, with specific mention of debiting credits and forwarding requests. It distinguishes itself from siblings by explicitly naming alternatives (apihub_call_external, apihub_read_content) and the onboarded scope.

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 provides explicit guidance on when to use this tool (for onboarded services) and when to use alternatives (apihub_call_external for arbitrary URLs, apihub_read_content for content gateways). It also covers prerequisites (API key, sufficient balance) and error handling (402 with payment requirements), including references to apihub_topup and apihub_balance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals critical behaviors: APIHub pays the provider via platform wallet, debits the user's credit balance for the exact amount, and requires no wallet or gas. This goes beyond the basic 'call' action and informs the agent of payment implications. It does not cover error conditions or response details, but for a call tool, the payment disclosure is the most important behavioral trait.

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 two sentences, each serving a distinct purpose: the first states the primary action and scope, the second explains the payment mechanism. There is no redundancy or fluff, and the key information is front-loaded with the action verb.

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 4 parameters, all documented in the schema, and no output schema. The description covers the core purpose, scope, and payment behavior, which is sufficient for an agent to invoke the tool correctly. It lacks explicit error scenarios or response format, but the 'call' semantics and the financial context are the most relevant completeness elements. The absence of output schema is mitigated by the simplicity of expecting an HTTP 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?

Because schema description coverage is 100%, the baseline is 3. The description does not repeat parameter details, but it adds contextual meaning by explaining that no wallet or gas is required and payment is handled automatically, which aligns with the schema's note about Authorization/X-PAYMENT headers. However, it does not provide additional syntax or format details for any specific parameter, so it adds minimal value beyond 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?

The description uses a specific verb 'Call' and names the resource 'external x402-protected URL', clearly distinguishing it from internal call alternatives like apihub_call. It further specifies 'any provider in the marketplace or any x402 API', making the tool's scope 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 provides clear context that this tool is for external x402-protected URLs only, implying a contrast with internal calls. It does not explicitly name alternatives or state when not to use it, but the 'external x402-protected' qualifier gives enough situational guidance for an AI agent to select it appropriately.

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

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

No annotations are provided, so the description carries the transparency burden. It states what the tool returns (endpoints, schemas, pricing), which adds useful behavioral context. However, it does not disclose potential side effects, authentication requirements, rate limits, or error conditions. Since this is a read operation, the omission of side effects might be acceptable, but the description could be richer.

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, well-structured sentence that front-loads the verb and object. It lists three concrete content categories without wasted words.

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 simplicity (one parameter, no output schema), the description sufficiently informs the agent of the return content and the need for a specific service. It could mention that the service_slug must be a valid slug, but that is implied by the schema. Overall, it is complete for a getter tool.

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%: the only parameter service_slug has a description with an example. The description does not add any additional meaning beyond the schema, so it meets the baseline of 3.

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 the verb 'Get' and the resource 'full details for a specific API service', specifically listing endpoints, schemas, and pricing. This distinguishes it from siblings like apihub_list_services, which would list services rather than retrieve a single service.

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 implies usage: you call this tool when you need full details for a particular API service. However, it does not explicitly mention alternatives or when not to use it (e.g., 'use apihub_list_services to browse services'). The context is clear but exclusions are absent.

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

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

With no annotations provided, the description carries the full behavioral burden. It explicitly states 'Read-only' and 'No authentication required', and goes further to disclose what the tool does not return, providing strong transparency about its behavior and boundaries.

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 three sentences, front-loaded with 'Read-only' and the primary action. Each sentence earns its place: the first defines scope and output, the second gives usage guidance, and the third clarifies exclusions. No redundancy or fluff.

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?

Despite having no output schema, the description lists the exact fields returned (slug, name, description, category, provider, endpoint count, lowest price). With only one optional parameter and clear exclusions, the tool is simple enough that this description fully covers its context and behavior.

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 description coverage is 100%, with the single 'limit' parameter fully documented in the schema (default, minimum, hard cap, clamping behavior). The tool description adds no additional parameter context beyond what the schema already provides, so the baseline of 3 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 the tool 'lists onboarded APIHub services alphabetically' and enumerates the specific fields returned. It explicitly distinguishes from siblings by noting exclusions ('does not include external x402 APIs', 'does not return endpoint-level details') and points to alternative tools, making its purpose 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?

Provides explicit when-to-use guidance: 'Use this to browse the full onboarded catalog when you don't have a specific capability in mind'. It also names alternatives for filtering (apihub_search), external APIs (apihub_search_external), and endpoint details (apihub_get_service), giving clear usage boundaries.

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

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

With no annotations, the description carries the full burden. It discloses that the gateway is paid and that output is clean structured text, but lacks details on cost consumption, error handling, or authentication requirements.

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 two sentences, front-loaded with the main verb and resource. Every word earns its place, with no redundancy or fluff.

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 covers the tool's purpose, output format, and intended service type. Given the absence of an output schema, it appropriately describes return values. It lacks edge-case behavior but is adequate for a simple two-parameter tool.

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 parameters are well-documented. The description adds the service_type context but does not provide additional parameter-level meaning beyond 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?

The description clearly states the tool reads web content through a paid content gateway and returns clean, structured text. It distinguishes itself from sibling tools by specifying it is for content services (service_type = 'content').

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 explicitly says to use this tool for content services, providing clear context. It does not name alternatives or exclusions, but the guidance is sufficiently specific for selection.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the operation is read-only, requires no authentication, returns up to 10 matches with detailed fields, ranks by uptime and endpoint count, and explicitly states it does not call any upstream API or debit credits. This exceeds what annotations would typically provide.

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 appropriately sized at about five sentences, each earning its place: read-only status, purpose, return format, auth requirement, usage guidance, and side-effect disclosure. It is front-loaded with the most critical info and contains no filler or redundancy.

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 search tool with no output schema. It covers purpose, filters, result count and ranking, return fields, auth, alternatives, and side effects (no upstream call/no credits). The absence of an output schema is compensated by explicitly listing the fields included in each match, making the tool fully self-contained.

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 per guidelines. The description adds minimal extra meaning beyond the schema—it mentions 'free-text query' and 'optional category, price, and type filters' but does not provide new syntax or semantics. The schema already fully documents each parameter, including valid values and units, so the description adds marginal value.

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 uses a specific verb ('Searches') and resource ('onboarded APIHub services'), clearly distinguishing it from siblings. It explicitly names alternatives (apihub_list_services, apihub_search_external, apihub_get_service) and states the scope of the search, making the tool's purpose 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 provides explicit when-to-use guidance: 'Use this when you need to find an API by capability' and then lists alternatives with their specific use cases (browse without a query, include external catalog, already know a slug). This directly tells the agent when to choose this tool over siblings.

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

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

With no annotations, the description partially discloses behavior by stating it returns listings with endpoint counts, prices, and on-chain activity, and that APIs are callable via credits. However, it does not mention whether credits are consumed per search, authentication requirements, rate limits, or any side effects. The read-only nature is implied by 'search' and 'returns listings' but not explicit.

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?

Two sentences, the first states the action and scope, the second summarizes return payload. Every word adds value, no redundancy.

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 explains the search scope (external APIs), cost context (credits), and return fields (endpoint counts, prices, on-chain activity). With no output schema, this return summary is helpful. However, it could mention that limit/query/category are optional filters, though those are in the schema. Overall adequate for a search tool with no required parameters.

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?

All three parameters (limit, query, category) are fully described in the schema with descriptions. The tool description does not add any parameter semantics beyond the schema, so baseline 3 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?

Description clearly states the tool searches external x402-protected APIs, specifying that these are not operated by APIHub and callable via credits. This distinguishes it from apihub_search which likely searches APIHub-owned services.

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?

Provides clear context that this is for external APIs and consumes credits, implying use when searching third-party APIs rather than internal ones. However, it does not explicitly name apihub_search as an alternative or state when not to use it.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns payment instructions in three formats (web URL, CLI command, raw x402 requirements) and that credits are added after on-chain payment confirmation. This is strong transparency, though it does not cover error handling or prerequisites like wallet configuration.

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 concise and front-loaded, with the main purpose first, followed by return details and confirmation behavior. Each sentence earns its place with no redundancy.

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 simple one-parameter tool with no output schema, the description covers the purpose, return format, and post-payment behavior. It is adequately complete, though it does not elaborate on edge cases or prerequisites beyond what is in the schema.

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%; the schema already details the parameter with minimums, maximums, and an example. The description itself adds no extra semantics beyond the schema, so the baseline score of 3 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 the tool's purpose: 'Purchase APIHub credits via x402'. It uses a specific verb ('Purchase') and identifies the resource ('APIHub credits'), and also specifies the payment method (USDC on Base). It distinguishes itself from sibling tools by describing unique output (payment instructions).

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 implies usage for topping up credits but does not explicitly mention when to use this tool versus alternatives like checking balance or making calls. There is no mention of alternative tools or exclusions, so the guidance is only implied by the purpose.

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