Apiosk MCP Server
Server Quality Checklist
Latest release: v1.8.0
- Disambiguation2/5
Several tool families have almost identical names: apiosk_wallet_list/apiosk_list_wallets, apiosk_wallet_create/apiosk_create_wallet, and apiosk_wallet_update/apiosk_update_wallet are only distinguishable by reading descriptions to see local vs managed. apiosk_search/discover/explore and apiosk_execute/fetch_paid also have overlapping boundaries, so an agent can easily misselect.
Naming Consistency2/5Most tools use apiosk_<verb>_<noun>, but local wallet tools reverse this to apiosk_wallet_<verb>, and x402 route tools drop the apiosk_ prefix entirely (publish_x402_route, unpublish_x402_route). Even within wallet naming, apiosk_wallet_list vs apiosk_list_wallets use different word order for the same resource.
Tool Count2/542 tools is far above the 25-tool threshold for a single platform and the surface feels padded with onboarding/helper tools and parallel local/managed wallet stacks. A more focused set around discovery, payment, and publishing would be easier to navigate.
Completeness4/5The set covers the core lifecycle well: discover, inspect, pay/execute, publish/update/deactivate APIs and x402 routes, and manage wallets/API keys. Minor gaps like a direct balance check and a hard delete for x402 routes are workable-around, so it earns a 4 rather than 5.
Average 3.8/5 across 42 of 42 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 118 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal this is a non-read-only, non-idempotent write operation, and the description's 'Create' is consistent with that. The description adds minimal context beyond the structured fields, notably failing to disclose that setting revoke_existing could invalidate current keys—a significant behavioral side effect. No contradiction with annotations, but the description does little to enrich the behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with the verb first and zero filler words. It is efficiently structured, though for a 5-parameter tool with side-effect potential, the brevity edges toward under-specification rather than disciplined conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a 5-parameter mutation tool with a possible revocation side effect, low schema coverage, and a confusingly similar sibling (create_wallet_connect_string). The output schema covers return values, but the one-sentence description leaves out prerequisites, side-effect conditions, and selection context. For the tool's complexity, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only private_key has a description), so the description carries a heavy burden to explain the parameters. It does not clarify the meaning of name, expiration_days, or revoke_existing, nor how they interact. The phrase 'API key / connect token' vaguely hints at what is created but adds no usable parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Create') and resource ('API key / connect token') scoped to 'a managed wallet,' which clearly conveys the operation. However, it does not explicitly differentiate from the closely named sibling apiosk_create_wallet_connect_string, and the 'API key / connect token' phrasing slightly blurs that boundary. Still, the verb-resource pairing is strong enough to distinguish from the list/update/delete api_key siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as apiosk_create_wallet_connect_string or apiosk_create_wallet. There are also no prerequisites stated (e.g., the wallet must already exist), and no mention of when one would choose revoke_existing behavior. The agent is left to infer the context entirely from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation nature is disclosed without needing the description. The description adds only the ownership scoping ('signed-in user's'), which is useful context beyond the schema and is not contradicted by any annotation. It does not disclose consequences such as irreversibility or effects on associated API keys/secrets, but with destructiveHint present the safety bar is already met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single eight-word sentence, front-loaded with the action verb 'Delete'. Every word carries meaning and there is no fluff or repetition of schema/annotation content. It is efficiently brief, though its brevity sacrifices useful context that is penalized in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required parameter, output schema present) and the annotations cover the destructive/idempotent profile, which lowers the bar. However, two critical pieces are missing: how to distinguish it from apiosk_wallet_delete, and where the caller obtains wallet_id. The description is not complete enough for reliable selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented wallet_id parameter, but it does not. The phrase 'one of the signed-in user's wallets' weakly implies the ID must reference the user's own wallet, yet it never explains how to obtain the ID or its format. This is a substantial gap given the complete lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete'), a resource ('wallets'), and an ownership scope ('signed-in user's'), which clearly identifies the operation. However, it does not distinguish itself from the near-identical sibling apiosk_wallet_delete, so an agent cannot tell which of the two to invoke. Clear, but lacking sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. Given the sibling list contains apiosk_wallet_delete — an apparent near-duplicate — plus create/update wallet tools, there is no routing information whatsoever. This is a no-guidance case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The phrase 'with signed wallet auth' adds a concrete behavioral requirement not present in the annotations. The description does not contradict the annotations (readOnlyHint=false, idempotentHint=true), but it leaves unspecified whether the update is partial or full and what side effects occur on the published API.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that leads with the action verb. It wastes no words, though it may be too sparse to fully support the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with seven optional parameters, no schema descriptions, and several sibling tools with overlapping API-management concerns, this description is not complete. It lacks information about update semantics, return values, and how 'signed wallet auth' is supplied, making it difficult for an agent to use correctly without additional investigation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description needed to compensate, but it only mentions 'signed wallet auth' and gives no detail on parameters like slug, active, price_usd, or listing_metadata. The parameter names are self-descriptive to a degree, but the interaction between them and the update semantics are left entirely to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Update' and the resource 'a published Apiosk API', which clearly identifies this as a modification operation distinct from wallet-management siblings like apiosk_update_wallet. It does not enumerate what fields can be updated, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus closely related siblings such as apiosk_publish_api or apiosk_configure. It also omits any prerequisites like needing an existing slug or wallet authentication setup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as non-read-only, idempotent, and non-destructive, so the description does not need to restate those traits. It adds a light hint about modification scope, but it does not explain side effects such as whether pausing or revoking a wallet disables it, or whether the update is partial or a full replacement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It is concise and efficient, though its brevity comes at the cost of needed detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema and annotations cover some ground, but the tool has 7 undocumented parameters and an ambiguous sibling relationship. Missing update semantics, status implications, and parameter details make the description incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero property descriptions across 7 parameters, so the description carries a heavy burden. It only groups a few parameters semantically ('display metadata', 'spending limits') and leaves units, value constraints, and relationships between fields unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('update') and resource ('wallet'), and enumerates the update surface: label, status, display metadata, and spending limits. It does not differentiate from the similarly named sibling apiosk_wallet_update, but the scope is still concrete enough to orient an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives, and no mention of exclusions or prerequisites. This is especially problematic because apiosk_wallet_update is a sibling with nearly the same name, leaving selection ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful context by saying the wallet is 'managed' and 'for the signed-in user,' and it does not contradict the annotations. However, it does not disclose side effects beyond creation/import, such as whether a secret is generated or stored, or how imported secrets are handled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. The core action and scope are front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Annotations and the output schema cover some burden, but the description omits usage-selection guidance and parameter semantics. For a tool with 5 parameters and many wallet-related siblings, this is too sparse to confidently guide correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, and the description provides no parameter-level explanation. It does not clarify the mode enum values, the requirement for label, or the meaning of daily_limit_usdc and per_tx_limit_usdc, so the agent gets little help beyond the bare parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('create or import') and a specific resource ('managed Apiosk wallet') scoped to the signed-in user. This largely distinguishes it from wallet listing, deletion, and secret-reveal tools, though it does not explicitly differentiate it from the similarly named apiosk_wallet_create sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to choose this tool over alternatives such as apiosk_wallet_create, apiosk_wallet_save_secret, or apiosk_create_wallet_connect_string. The description only names the operation and gives no prerequisites, exclusions, or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds minimal context by scoping the deletion to a 'local wallet' in the 'MCP keystore', but it does not mention permanence, impact on associated secrets, or confirmation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It immediately communicates the action and the target resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive operation with an output schema and annotations, the description is minimally adequate. However, the lack of usage guidance and parameter semantics leaves an agent with some ambiguity about when and how to invoke it correctly, especially given the large sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for wallet_id, and schema description coverage is 0%. The tool description does not explain what wallet_id refers to, how to obtain it, or whether it is a local identifier or a global wallet ID. The parameter name is self-explanatory to some degree, but the description adds no meaningful semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a local wallet from the MCP keystore'). It is specific enough to understand the tool's basic function, though it does not distinguish itself from similarly named siblings like apiosk_delete_wallet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as apiosk_wallet_create, apiosk_wallet_update, or apiosk_delete_wallet. It does not state prerequisites, side effects, or cases where another tool should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description's burden is lower. It adds the 'local' qualifier, which clarifies scope, but does not disclose side effects such as whether setting a wallet active deactivates others, or whether label changes are persisted. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler. It front-loads the primary action (rename) followed by the secondary action (mark active). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has annotations, and an output schema, which reduces the need for return-value explanations. However, the description lacks usage context, especially regarding the many sibling wallet tools and the similarly named apiosk_update_wallet. It is barely adequate for safe selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must compensate, but it only implicitly maps 'rename' to label and 'mark active' to set_active. It does not explain the required wallet_id, the effect of omitting label or set_active, or whether both can be provided together. This is insufficient for full parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's actions: 'Rename a local wallet or mark it active.' This provides a specific verb and resource, distinguishing it from list/create/delete wallet tools. However, it does not differentiate from the similarly named sibling 'apiosk_update_wallet', which could confuse an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description neither mentions exclusions nor points to sibling tools like apiosk_wallet_create, apiosk_wallet_delete, or apiosk_update_wallet. An agent must infer usage solely from the operation names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructivHint=false), so the bar is lower. The description adds the conditional 'QR code output when available' and the menu structure, but leaves 'actions' vague and does not clarify whether the menu itself can trigger mutating workflows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. The slash-delimited 'wallet/pay/publish/data actions' is compact and slightly vague, but the structure is clear and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation is not required, and annotations cover side-effect behavior. Still, the description does not state a default section, whether a wallet must already exist, or what the 'actions' do, so an agent has to infer several invocation details from schema enums alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, so the description must compensate. It partially does: 'funding instructions' and 'QR code output when available' give context to funding_provider and include_qr_data_url, and 'wallet/pay/publish/data actions' maps to section values. However, wallet_id and the relationship between section and funding_provider remain implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') and a clear resource ('structured Apiosk control menu for a wallet'), and it enumerates main contents: funding instructions, QR code output, and wallet/pay/publish/data actions. It does not explicitly differentiate itself from overlapping siblings like apiosk_help or apiosk_show_wallet_funding, so it stops short of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for presenting a wallet control menu, but it provides no when-to-use guidance and no alternatives or exclusions. With many sibling tools including apiosk_help, apiosk_payment_guide, and apiosk_show_wallet_funding, an agent is not told when apiosk_configure is the better choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false; the description confirms non-mutating browse behavior and adds that it works one group at a time. It doesn't describe pagination, response shape, or limits, but the read-only safety profile is already covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is compact and front-loaded with the core browsing intent, but it is underspecified for a 6-parameter tool with weak schema coverage. It has no wasted words, yet it is not appropriately sized because it omits crucial parameter and usage clues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and annotations that cover safety, the description leaves the agent unsure how to select a group, how pagination and sorting behave, and how this tool differs from the similarly browse-oriented apiosk_discover. It only communicates a high-level exploration intent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, so the description needs to compensate. It loosely implies a 'listing_type' grouping with 'one group at a time' but never names it, and sort, limit, order, and offset are left completely unexplained. This is insufficient for an agent to know how to parameterize the call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (Browse/explore) against a resource (Apiosk listing groups) and positions it relative to search ('before narrowing with search'). It is less crisp on what 'one group at a time' means and does not name the sibling search tool explicitly, so it is not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies the intended sequence: explore first, then narrow with search, which is a clear use context. It doesn't explicitly name apiosk_search as the alternative or state when not to use this tool, so it loses a point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is a non-destructive read-only call, and the description is consistent. It adds a useful outline of the returned explanation content but does not disclose deeper behavior such as whether the help is static, rate-limited, or dependent on auth state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with listing but no redundancy. It efficiently enumerates what the tool explains, though the long list of topics makes it slightly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the optional single parameter, the schema's enum documentation, and the presence of an output schema, the description is mosely sufficient for a help tool. The main gap is its relationship to closely related sibling help tools, which context does not clarify.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single optional 'topic' parameter is 100%, and the enum values are self-descriptive, so the description does not need to add much. It provides a light mapping of topics (auth, payments, workflow) but relies on the schema for detailed parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's job with a verb ('Explain') and a distinct resource (Apiosk MCP), listing specific areas: connection, auth, USDC/x402 payments, and workflow. It does not explicitly differentiate from overlapping siblings like apiosk_get_started or apiosk_payment_guide, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is a general help/educational entry point, but it never states when to prefer it over sibling tools. The schema's topic enum partially compensates by directing the agent to use 'discovery' and 'rails' for specific learning goals, so there is some contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior, and the description's 'List' is consistent. It adds useful auth context (active local wallet vs APIOSK_PRIVATE_KEY) but does not explain what happens when neither is available or how a provided wallet_id changes behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with a front-loaded verb and no filler. Every word contributes to the tool's meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read-only list with an output schema and rich annotations, purpose and auth source are covered. However, the unexplained wallet_id parameter and lack of expected behavior for missing wallet/key leave a functional gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one optional wallet_id parameter with 0% description coverage, and the description never mentions it. An agent cannot determine whether wallet_id overrides the active wallet, filters results, or is needed for listing a specific wallet.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific operation ('List') and resource ('APIs owned by the active local wallet or APIOSK_PRIVATE_KEY'). This clearly distinguishes it from single-API retrieval (apiosk_get_api) and broad discovery tools (apiosk_explore/search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The ownership scope implies this is for listing the caller's own APIs, but it never explicitly says when to use it versus alternatives. There is no exclusion guidance or reference to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations provide little behavioral signal since all hints are false. The description adds that the tool returns a new connect string and uses the word 'rotate,' which suggests existing tokens may be replaced, but it does not disclose whether revoke_existing invalidates current connect strings or what happens to previously issued tokens.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the core action, and no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters, one required parameter, and subtle behaviors around rotation and revocation, the description is too thin. It omits the effect of revoke_existing, the conditions under which private_key is needed, and any prerequisites about the managed wallet. The output schema helps, but the behavioral context is still incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%: only private_key has an explanation. The description does not clarify wallet_id, token_name, or revoke_existing beyond their names, and it only weakly implies that revoke_existing relates to rotation. It does not compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Rotate or create a connect token') and a specific resource ('managed wallet'), and states the output ('return the new connect string'). This clearly differentiates it from the generic wallet create/update/delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: use this tool when you need to rotate or create a wallet connect string. However, there is no explicit guidance about when to choose this over related siblings such as apiosk_wallet_create, apiosk_wallet_update, or apiosk_wallet_save_secret.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds the core behavior of writing private key material to disk while bypassing the dashboard, consistent with those annotations. No contradiction. Still, for a tool that persists sensitive secret material, a security-relevant note (e.g., plaintext on disk, file permissions) would add meaningful transparency beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single 15-word sentence that front-loads the verb and target ('Save a local wallet's private key to a file') and appends the qualifier ('without going through the dashboard') at the end. Every word earns its place with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema covers return values and annotations cover the safety profile, so those need no elaboration. For a security-sensitive export operation among roughly 40 siblings with a very close counterpart (apiosk_wallet_reveal_secret), the description is adequate but incomplete: it omits a security caution about writing a private key to disk and gives no routing hint relative to reveal_secret.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, with only 'path' documented (default ~/.apiosk/exports). The description partially compensates by establishing that wallet_id refers to a local wallet and that the output contains a private key, which gives interpretive context for two parameters. However, it says nothing about the format enum (json vs txt) or what each output serialization contains, leaving a real semantic gap at low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Save') with a well-defined resource ('a local wallet's private key to a file') and adds scope with 'without going through the dashboard.' The action and target are unambiguous and the tool is clearly distinct from unrelated siblings, though it does not explicitly contrast with the closely related apiosk_wallet_reveal_secret.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Without going through the dashboard' implies a headless/direct-export use case, which gives some situational context. However, there is no explicit when-to-use guidance, no exclusions, and no mention of choosing this over the closest sibling apiosk_wallet_reveal_secret for viewing a secret versus persisting it to disk.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry destructiveHint=true, readOnly=false, and idempotentHint=true; the description adds the requirement of wallet-signed auth but does not clarify whether deletion is permanent, whether deactivation is reversible, or what signed auth payload is needed. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that states the action, target resource, and auth requirement with no filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive two-parameter tool, the key facts are present (ownership, auth, action), and the output schema reduces the need to describe return values. However, the ambiguity between 'delete' and 'deactivate' and the absence of parameter-level guidance leave meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the parameters. It hints that slug identifies a published API and wallet_id relates to signing, but it never names or maps the parameters, nor does it provide enough detail to compensate for the bare string schemas. This is only slightly more useful than the field names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with specific verbs ('Delete or deactivate') and names the exact resource ('your published Apiosk APIs'), which clearly distinguishes this from siblings like apiosk_update_api, publish_api, and list_my_apis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies the tool is for removing/deactivating one of the user's own published APIs, but it does not explicitly say when to choose this over similar siblings such as unpublish_x402_route or state any exclusions. The usage context is clear, but alternatives are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already marks the operation as destructive, and the description reinforces this with 'permanently,' clearly signaling irreversibility to the agent. This adds useful context beyond the raw destructiveHint flag, though it does not mention authorization requirements or cascading effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It expresses the operation, the resource, and an important qualifier ('permanently') efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter destructive operation, the description plus annotations and output schema provide adequate calling context. It lacks usage guidance and parameter details, but the simplicity of the tool reduces the impact of those omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain wallet_id or key_id at all. The parameter names are somewhat self-explanatory, but the description fails to compensate for the absence of any schema-level documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Delete') and a specific resource ('managed wallet API key') with the qualifier 'permanently.' It clearly distinguishes this tool from sibling list/create/update API-key tools by naming the delete operation explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as apiosk_list_wallet_api_keys, apiosk_create_wallet_api_key, or apiosk_update_wallet_api_key. No exclusions, prerequisites, or alternative routing are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds useful scope context ('full listing detail and agent metadata') but does not disclose additional behavioral traits such as authentication needs or result filtering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action and target, with not filler or restatement of the tool name. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only lookup with both input and output schemas present, this description is sufficient. Missing details about response shape are covered by the output schema, and safety is covered by annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'slug', is fully documented in the input schema at 100% coverage, including an example. The description only repeats the idea of a slug, adding no new parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('Fetch') and resource ('full listing detail and agent metadata') scoped by slug. It clearly indicates this is a detail lookup for a single API, distinguishing it from list/search/explore siblings, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'for aspecific Apiosk API slug' clause conveys an implied use case: call when you already have a slug and need full details rather than browsing or searching. It does not explicitly explain when to prefer sibling tools like apiosk_search or apiosk_explore.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context beyond 'recent', but it does not disclose pagination behavior, ordering details, or any wallet-state constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to identifying the action and resource, and it avoids repeating schema or annotation details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description only needs to clarify scope and usage, which it largely does. The main omission is pagination parameter semantics, but page and limit are conventional optional fields and their names are reasonably self-explanatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It clarifies wallet_id scope and implies recency, but it says nothing about page or limit semantics, pagination defaults, or how filtering/ordering works. This is a meaningful gap for a low-coverage schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch'), a clear resource ('recent transactions and activity'), and a bounded scope ('one managed wallet'). This clearly distinguishes it from sibling tools like apiosk_list_wallets or apiosk_show_wallet_funding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for one managed wallet' implies this is for activity on a single wallet, but there is no explicit guidance about when to prefer it over alternatives such as apiosk_show_wallet_funding or apiosk_list_wallets. No exclusionary or alternative-usage hints are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate that this is a mutating, idempotent, non-destructive operation. The description adds the concrete actions (rename, revoke, extend) but does not elaborate on side effects like what revoking actually does to existing credentials or whether changes are reversible. It's consistent with annotations and adds modest behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. It conveys the core purpose immediately and avoids redundant repetition of the tool name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for selecting the tool, but with five undocumented parameters and no explicit alternatives or parameter guidance, it leaves room for invocation ambiguity (especially expiration_days semantics). The presence of an output schema helps, but the overall description is minimal for a mutating API key management operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It implicitly maps 'rename' to name, 'revoke' to revoke, and 'extend' to expiration_days, but it does not clarify semantics like how expiration_days is relative to or whether key_id/wallet_id have special constraints. Partial compensation, but not enough to fully document five parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Rename, revoke, or extend') with a clear resource ('existing managed wallet API key'). This distinguishes it from sibling tools like create_wallet_api_key, delete_wallet_api_key, and list_wallet_api_keys, making the tool's purpose immediately identifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing managed wallet API key' implies the tool is for updating existing keys, not creating or deleting them. However, it does not explicitly state when to use this tool instead of apiosk_create_wallet_api_key or apiosk_delete_wallet_api_key, so the guidance remains implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful context about local storage scope and the active-wallet selection behavior, going beyond what annotations provide, though edge cases like an empty wallet store are not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with a clear verb and no filler. It efficiently conveys the operation, the resource scope, and the distinguishing active-wallet detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema present, the description is largely sufficient for invoking the tool. The only notable gap is the lack of disambiguation from the similarly named sibling apiosk_list_wallets, which could cause incorrect tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema description coverage, so the baseline is 4. The description usefully clarifies what the output represents (wallets plus the active one), adding semantic value beyond the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'List locally stored Apiosk wallets' and adds the specific behavior of showing which one is active for autonomous pay and publish. However, it does not differentiate itself from the closely named sibling 'apiosk_list_wallets', so an agent could confuse the two.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as apiosk_list_wallets or apiosk_wallet_select. Multiple wallet-related siblings exist, and the description does not state any exclusionary conditions or context-based recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false, destuctiveHint=true, and openWorldHint=true, so the destructive/open-ended nature is encoded. The description adds no extra behavioral detail such as auth requirements, side-effect scope, or rate limits, but it also does not contradict the annotations. Given the annotation coverage, a neutral 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with no filler. It states the action and scope immediately, making it easy for an agent to parse the tool's purpose at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high schema coverage, presence of an output schema, and strong safety annotations, the description is minimally sufficient: it identifies the object ('any Apiosk API'), the identifier ('slug'), and the contract ('/execute'). It does not explain the envelope semantics, but those are documented in the parameter descriptions, so the overall definition is reasonably complete for a generic pass-through tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are already described in the schema with 100% coverage, including the default vs envelope distinction for input, operation, query, and path_params. The description adds no parameter-level meaning beyond naming the 'execute contract', so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Execute any Apiosk API by slug') and names the transport contract ('/execute'). This clearly distinguishes it from management/exploration siblings like apiosk_get_api or apiosk_explore, even though it doesn't enumerate alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It conveys the core use case – invoke an arbitrary Apiosk API by slug – but gives no explicit when-to/when-not guidance or alternatives. With siblings like apiosk_fetch_paid and test_x402_route, the absence of exclusions is a gap; use is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so no contradiction exists. The description adds context by scoping to managed wallets and noting 'connect tokens' as equivalent to API keys, but it does not describe pagination, ordering, or other behavioral details beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It front-loads the action and resource, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and the presence of annotations and an output schema, the description is nearly complete for a simple read-only list operation. The only minor gap is that 'managed wallet' is not defined, but this is unlikely to block correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented wallet_id parameter. It partially does by indicating the parameter refers to a managed wallet, but it does not explain the expected format or how the ID is obtained. The single self-named parameter and the phrase 'managed wallet' provide only minimal additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), a clear resource ('API keys / connect tokens'), and a scope ('for a managed wallet'). This distinguishes it from sibling tools like create/update/delete wallet API keys without needing to inspect their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: call this when you need to list existing API keys or connect tokens for a wallet. However, it does not explicitly mention when not to use it or which sibling tool to choose for creating, updating, or deleting keys, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds useful behavioral context beyond that by stating the auth requirement and limiting results to 'the signed-in user's managed' wallets. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, purposeful sentences. The core function is front-loaded in the first sentence, and the auth requirement in the second is valuable. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list tool with annotations covering safety and an output schema covering return shape, the description is largely complete, providing the key auth prerequisite. The only substantial gap is the lack of differentiation from the similarly named sibling apiosk_wallet_list, which could leave an agent uncertain about which tool to invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema has 100% description coverage, so there is essentially nothing for the description to add. The baseline for a zero-parameter tool is 4, and the description adds no extraneous parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List the signed-in user's managed Apiosk wallets') and clearly states scope ('managed' and 'signed-in user's'). However, it does not differentiate from the near-identically named sibling tool apiosk_wallet_list, so an agent could confuse the two.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite ('Requires an Apiosk dashboard session from local env auth or hosted MCP authorization'), which gives some usage context. But it gives no guidance on when to use this tool instead of the similarly named apiosk_wallet_list or other wallet-related siblings, so alternatives are not addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a non-read-only, non-idempotent operation, and the description adds useful behavioral context: publishing is performed via the active local wallet or APIOSK_PRIVATE_KEY and requires no dashboard. This exposes an important auth/execution path beyond the annotations. It does not contradict 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every phrase adds value: the action, the resource, the platform, the auth mechanism, and the no-dashboard context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema existing, the description is too sparse for a 9-parameter publish operation with an 11% schema description coverage. It omits guidance on how required fields should be chosen, what listing_group options imply, how listing_metadata is used, and what prerequisites besides the wallet/private key may exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 11%, so the description needs to compensate for 9 under-documented parameters. It adds some meaning around wallet/private-key authentication, but it does not explain the core required fields such as name, slug, endpoint_url, price_usd, description, or the optional listing_group and listing_metadata semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Publish a new API on Apiosk.' It clearly indicates the action is creating/publishing, not updating or deleting, and the platform is named. The phrase 'new API' also distinguishes this from update/delete siblings and from publish_project or publish_x402_route.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about when to use this tool: when the user wants to publish an API without using a dashboard, using the active local wallet or APIOSK_PRIVATE_KEY. However, it does not explicitly state when not to use it or name alternatives such as apiosk_update_api or publish_x402_route.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a mutating, non-idempotent operation (readOnlyHint=false, idempotentHint=false). The description adds a meaningful side effect beyond annotations: it saves the returned dashboard session token locally when available, which matters for state and security. No contradiction with annotations; more detail on duplicate-account behavior would push it higher.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler. Purpose is front-loaded, followed by the operational constraint and the side effect. Every clause earns its place, and nothing is redundantly restated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation. The description covers purpose, environment constraint, and the local token side effect. The minor gap is that it doesn't state how the saved session token feeds into subsequent authenticated calls, though an agent can reasonably infer this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, so the burden falls on the description, but email and password are conventional self-explanatory account-creation fields. The description does reinforce the save_session parameter by stating the token is saved locally 'when available,' and 'credits-based payments' adds account-type context. Still, the two required parameters receive no semantic elaboration beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb ('Create') with a specific resource ('Apiosk dashboard account') and adds a purpose qualifier ('for credits-based payments'). The action is inherently distinct from the sibling apiosk_sign_in, so an agent can tell this is the registration path without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives one explicit invocation constraint ('Local stdio only'), which is genuinely useful placement/usage guidance. However, it never names alternatives such as apiosk_sign_in for existing users, and gives no when-not-to-use conditions. Usage context is mostly implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a mutating, non-idempotent operation but do not describe side effects. The description adds concrete behavioral detail by stating the active wallet is mirrored to ~/.apiosk/wallet.json and ~/.apiosk/wallet.txt, which helps the agent anticipate filesystem writes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler: the first states the tool's purpose and the second discloses a key side effect. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the parameter schema covers most fields, the description is largely sufficient. It captures the core operation and the most important persistence behavior, though it could mention overwrite or security implications of wallet file mirroring.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 78% and most parameters already have descriptions, so the description need not restate them. However, it adds no parameter-level semantics itself, leaving label and a few options to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs 'Create or import' and identifies the resource as 'a local wallet', with a clear purpose ('autonomous Apiosk payments and publishing'). It distinguishes the tool from wallet list/update/delete siblings, but does not differentiate it from the similarly named apiosk_create_wallet sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when creating or importing a wallet for autonomous Apiosk payments and publishing. It does not explicitly state when-not to use it or name alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the tool creates a hosted artifact with a public URL and requires an Apiosk provider token. This adds useful auth and output context without contradicting the idempotent/destructively-safe hints from 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The core action, scope, output, and auth requirement are all front-loaded and each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with output schema and annotations, the description covers action, input scope, return value, and authorization enough to select and invoke it. The minor ambiguity around title/version parameter semantics is the only noticeable gap, but it does not make the description incomplete for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 25% schema description coverage, the description partially compensates by linking the operation to a 'route's API listing' (helping route_id) and implying OpenAPI 3.1 semantics for title/version. However, it does not explicitly describe the title or version parameters, and endpoints is only covered by the schema's own description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Generate'), a concrete resource ('a hosted OpenAPI 3.1 spec for a route's API listing'), and the expected output ('return its public URL'). This clearly distinguishes it from sibling tools like apiosk_get_api or apiosk_publish_api, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies the usage context: generate a hosted OpenAPI spec for a route and mentions a required precondition ('Requires an Apiosk provider token'). However, it does not explicitly state when to prefer this tool over alternatives or when not to use it, so selection guidance is mostly left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses that the call creates a gateway listing plus one paid x402 route per route entry, and that an operator token is required. It doesn't detail every external side effect, but openWorldHint/idempotentHint already cover part of the safety profile, and nothing contradicts annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two clean sentences with no filler. The first front-loads the core action, the second specifies the side effects and the auth requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The high-level behavior is complete enough to select the tool, and an output schema exists so return values need not be described. But for a 7-parameter batch operation with sparse schema descriptions, the definition leaves important invocation details (network defaults, settlement_address semantics, price format, idempotent repeat behavior) to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 14% (only base_url has a description), yet the description adds no parameter-level guidance for project_name, settlement_address, network, tags, or route.price/method semantics. The names are somewhat self-explanatory, but the description does not compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Publish'), a clear resource ('multiple API routes from one project'), and explains the per-entry side effect. It is easily distinguishable from the sibling publish_x402_route, which handles only a single route.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly frames the tool as the batch path for publishing a whole project's routes in one call and gives a required precondition (Apiosk provider token). It does not explicitly list alternatives or when-not-to-use, but the context against publish_x402_route is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the request is unpaid, that the expected result is a 402 with a valid accepts[] offer, and that a provider token is required. This adds meaningful behavioral context beyond the readOnlyHint and openWorldHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence front-loads the verb, target, and expected behavior, and the second states the prerequisite clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter test tool with annotations and an output schema, the description is mostly complete: it covers the request type, expected result, and auth requirement. It could add what to do when the route does not return 402, but this is not essential given the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents test_payload's GET/POST behavior and route_id is self-explanatory, but the description adds little parameter-specific meaning. With only 50% schema coverage, the description could have explained how route_id and test_payload relate to the expected 402 response.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Send an unpaid test request to a route's paid URL') and a precise expected outcome (402 Payment Required with a valid accepts[] payment offer). This clearly distinguishes it from sibling route-management and execution tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context (testing x402 behavior, requires an Apiosk provider token) but does not explicitly state when to prefer this tool over alternatives such as execute or apiosk_fetch_paid. Usage is implied rather than contrasted with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a meaningful side effect beyond the annotations: it saves the session token locally. This is important behavioral context that neither idempotentHint nor destructiveHint conveys. It also clarifies that it signs into an existing account rather than creating one.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-structured sentence with no filler. It front-loads the action, specifies the target, and explains the purpose of the side effect in one compact statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values are already covered. The description explains the purpose, side effect, and connection to other tool categories, which is sufficient context for a simple authentication tool. The main gap is parameter-level guidance, but the tool's simplicity reduces the impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (save_session is described, but email and password are not). The description does not compensate for the gap: it never explains what save_session controls beyond the general 'save the session token locally' behavior, leaving ambiguity about the false case. Email and password are intuitively obvious, but the description adds no parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (sign in), the target resource (existing Apiosk dashboard account), and the key side effect (save session token locally). It effectively distinguishes itself from apiosk_create_account by specifying 'existing' account.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a prerequisite step for credits and managed-wallet tools by mentioning the session token is saved 'for' those tools. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to infer when sign-in is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it non-read-only, non-idempotent, and non-destructive; the description adds the actual workflow, including importing credentials, wallet creation/selection, a discovery probe, and a test call. It does not spell out persistence details such as where secrets are stored, but the main behavioral surface is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence front-loads the purpose and then lists the phases in order. There is no filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 12 optional parameters, the description gives a complete high-level execution model, and the output schema plus per-parameter schema descriptions cover the remaining details. It could mention explicit default behavior when no arguments are supplied, but the create_wallet schema description already handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented; the tool description need not repeat them. It only loosely maps the connect-string/wallet/test parameters to the setup workflow, without adding semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific goal ('Set up local Apiosk access') and enumerates the concrete steps: import a connect string or create/select a wallet, then run a discovery probe and a test call. This differentiates it from the many sibling wallet/API tools by framing it as a multi-step onboarding helper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this is for initial local Apiosk setup and validation, before normal API work. It does not explicitly name alternative tools for already-configured users, so it stops short of giving when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true and non-destructive, and the description aligns (explain + return guides, no contradiction). It adds useful behaviorl context beyond annotations: output is split into buyer/provider guides, is tailored to current auth, and slug scopes guidance to one listing's price and payment steps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the primary purpose, each earning its place: purpose, deliverable structure, then parameter guidance. The parentheticals are dense but justified because they specify the exact content of each guide rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-param guide tool with an output schema and read-only annotations, the description covers purpose, deliverable structure, and parameter effects. Minor gaps remain: how output is structured when role defaults to 'both', and how auth-tailoring behaves without an authenticated session — but the output schema carries return-value detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — both role and slug are already documented in the schema, so the baseline is 3. The description restates their effects ('Pass slug to scope... role to pick a side') but adds no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Explain') and resource ('how to pay through the Apiosk gateway'), then scopes it to two concrete deliverables: a buyer guide for settling paid API calls over USDC/x402 and a provider guide for publishing an API and getting paid. This distinguishes it from generic sibling help tools like apiosk_help and apiosk_get_started by naming the exact payment mechanics covered.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context for use is clear — an agent needing to learn how to settle a paid call, or a provider wanting to publish and get paid — and the description explains how to tailor output via role and slug. However, it never explicitly names alternatives or states when not to use this tool versus apiosk_help or apiosk_get_started.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as an idempotent, non-destructive mutation. The description adds behavioral context by specifying that the selection sets the active local wallet and affects downstream operations. It does not describe persistence/scope, but annotations cover the key safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler; the action and scope are front-loaded and every word adds meaning. It is appropriately sized for a simple selection tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple two-parameter tool with an output schema, the description covers what the tool does, what it affects, and which tools depend on it. The main missing detail is explicit wallet_id semantics, but the low complexity and inferability from the name make this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%: wallet_id has no schema description. The description does not explicitly explain that wallet_id identifies the wallet to activate or where to obtain it, so it only partially compensates. include_qr_data_url carries its own schema description, so the main gap is the required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('select'), identifies the resource ('active local wallet'), and names the consumers (apiosk_execute, dynamic API tools, publish tools). This distinguishes it from sibling wallet management tools such as list/create/update/delete and makes the operation unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context by stating that this wallet is the one used by execute, dynamic API tools, and publish tools, so agents know to call it before those workflows. It does not explicitly list alternative tools or when-not-to-use scenarios, but the context is sufficient for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It adds a meaningful behavioral constraint beyond annotations: an Apiosk provider token is required. The safety profile is already covered by readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description does not need to restate those. It stops short of describing post-update review or side effects beyond the status enum's note.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that immediately names the operation, resource, and key editable fields, followed by the auth requirement. Every words carries information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 12 parameters, the description plus existing schema status note and annotations provide enough operational context: what can be changed, that a token is required, and that status toggling can affect review. It does not explain every edge case, but is reasonably complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 8%, the description compensates partially by listing most but not all updatable fields (price, description, upstream URL, schemas, settlement address, status) and implying route_id. However, name, path, tags, and method are omitted, and field formats such as price or settlement_address remain unexplained, so some ambiguity remains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Update') on a specific resource ('published x402 route') and enumerates the editable fields, which clearly distinguishes it from publish, unpublish, list, and test siblings. It is directly informative rather than a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended context clear: use this to modify an existing published x402 route. It also notes the provider-token requirement. It does not explicitly name alternatives, but the update/publish/unpublish distinction is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details beyond that: it shows a QR code, defaults to the first managed wallet, and always reminds the buyer about the USDC Base mainnet requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused sentences, each earning its place: the core behavior, the defaulting rule, and the required user reminder. No filler or redundant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a tool with one optional parameter and an output schema. It explains what the buyer sees, why it exists, how the wallet is selected, and the network requirement—everything needed to invoke and present the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the wallet_id parameter is already fully documented. The description repeats the defaulting behavior but adds no new parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states a specific action: show the buyer's wallet address with a scannable QR code for manual funding. It includes the network (Base mainnet) and asset (USDC), which fully differentiates it from sibling wallet tools like listing or selecting wallets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: use this when the buyer needs to fund the wallet manually from another wallet or exchange. It doesn't explicitly name alternative tools or exclusion conditions, but the manual-funding purpose is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true; the description aligns with that. It adds a meaningful behavioral detail beyond annotations by requiring an Apiosk provider token and by specifying that results include paid URLs, prices, and live status. No pagination or error behavior is described, but for a simple list tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with no filler. The core purpose, scope, returned data, and auth requirement are all covered in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only listing operation with one optional parameter, a good input schema, and an output schema present. The description provides the essential context: what is listed, for whom, and what auth is required. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the only parameter ('status') with an enum and a clear description, so schema coverage is 100%. The description doesn't add any extra meaning to the status parameter, but it doesn't need to; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource type ('x402 routes') and scope ('published by the authenticated provider'). It also lists the key returned data (paid URLs, prices, live status), which distinguishes it from broader listing tools like apiosk_list_my_apis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the context: listing routes for the authenticated provider, and it mentions a required provider token. It does not explicitly name alternatives or when-not-to-use, but the sibling set (publish_x402_route, update_x402_route, unpublish_x402_route) makes the intended use obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses important runtime behavior beyond annotations: the URL returns 402 until paid in USDC, then forwards to the upstream; routes begin as pending_review and go live on approval; and a provider token is required. This does not contradict the readOnly/idempotent/destructive hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, and each earns its place: purpose, payment behavior, moderation lifecycle, and authentication. The most decision-relevant information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Together with the rich schema and annotations, the description covers the core publish flow, auth requirement, and review state. The only notable omission is the purpose of the optional nested schema parameters, which prevents a perfect completeness score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover 9 of 13 parameters, including defaults and examples, so the description does not need to repeat them. It reinforces the payment and upstream concepts but leaves the four undocumented optional fields (tags, description, input_schema, output_schema) unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action and resource: publish an API endpoint as a paid x402 route on the Apiosk gateway. It also distinguishes this from update/unpublish/test siblings by describing the create-and-submit lifecycle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is clear: you publish a new endpoint as a paid x402 route and it enters review; this context is enough for an agent to select it over read or mutation siblings. It does not explicitly name alternatives like update_x402_route, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already mark destructiveHint=true and idempotentHint=true, the description adds meaningful behavioral detail: the gateway listing stops serving, the operation is reversible via update_x402_route, and an Apiosk provider token is required. These details go beyond the annotations and help the agent understand consequences and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load the core action and effect, then add the reversal path and auth requirement. Every sentence earns its place with no filler or unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter disabling operation with an output schema and annotations covering destructiveness and idempotency, the description covers the essential context: what happens, how to reverse it, and what credential is required. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and route_id is a bare string with no schema description. The tool description does not explicitly state that route_id is the identifier of the route to disable, nor how to obtain it or what format it takes. The name and the phrase 'a paid x402 route' imply some semantics, but the description fails to compensate for the total absence of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb 'Disable' and the exact resource, 'a paid x402 route,' and further clarifies the operational effect: 'its gateway listing stops serving.' This clearly distinguishes it from publish_x402_route and update_x402_route while naming the relevant reversal sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool: to disable a paid x402 route. It also names the alternative for reversing the action: update_x402_route {status: 'active'}. It stops short of explicitly giving 'when not to use' guidance, but the context is strong enough to guide an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and non-destructive, so the bar is lower. The description adds useful behavioral context by clarifying that this tool is for catalog browsing/filtering, not for retrieving live paid data, which implies a meaningful functional boundary beyond what the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The main purpose is stated first, followed immediately by the alternative routing. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a rich input schema, full parameter descriptions, an output schema, and safety annotations. The description completes the picture by defining when this tool is the right choice and when to use apiosk_discover, leaving no material gap for an agent deciding whether to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 six parameters. The description adds some orientation by mentioning 'capability, price, or category,' which maps to search, sort, and category, but it doesn't need to compensate for schema gaps. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: 'Search and browse the Apiosk catalog.' It further specifies the dimensions ('by capability, price, or category') and explicitly distinguishes this tool from apiosk_discover, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool ('For browsing/filtering the catalog') and when not to ('When the goal is to fulfil a user request with real paid data... prefer apiosk_discover'), naming the alternative tool and the selection condition. This is exemplary routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, non-destructive, and idempotent behavior. The description adds a valuable behavioral guardrail about explicit user consent, which is not inferable from the annotations. It also clarifies the scope ('local wallet') rather than remote or cloud wallets, though it does not elaborate on the sensitivity/security implications of exposing a private key.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The primary action is stated first, followed by a critical usage restriction. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter, read-only tool with an output schema and clear sibling context, the description covers the essential information: what the tool does, what wallet scope it applies to, and when it is appropriate to call it. 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for wallet_id, and the tool description does not explicitly define the parameter. However, the phrase 'local wallet's private key' and the tool name make it clear that wallet_id identifies the local wallet whose secret should be revealed. This is sufficient for a single, self-explanatory parameter, but the description still relies on inference rather than explicit documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('reveal') and resource ('a local wallet's private key'), making the tool's function immediately clear. It also distinguishes itself from the sibling wallet tools, particularly apiosk_wallet_save_secret, by focusing on reading/exposing the secret rather than storing it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit condition for use: 'Only call this when the user explicitly asks to see the secret key.' This gives the agent a clear gatekeeping rule and implicitly warns against calling it in other contexts, which is especially important for a sensitive secret-revealing operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark read-only/idempotent/non-destructive, and the description goes further: discovery never spends automatically, paid sources are opt-in, and wellknown probing is limited to named probe_hosts with no speculative crawling. This adds safety and side-effect transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with no filler: capability discovery, decomposition instruction, return/routing behavior, and alternative choice. Front-loads the core purpose; every sentence carries distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full output schema and complete schema parameter descriptions, the description covers the workflow, alternatives, safety behavior, and downstream routing. Nothing necessary for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters (query, sources, segments, max_results, probe_hosts, max_price_usdc), so the description doesn't need to explain them; it adds only workflow context around segments and routing. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Find'), a precise object ('best paid x402 API for a data capability'), and explicitly differentiates from apiosk_search with a concrete condition. It also identifies the discovery sources and outcome (normalized ranked list). The distinction from siblings is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to decompose request into capability segments and call once per capability; names alternative apiosk_search and states when to use this instead ('get real paid data for X' vs browsing). It also explains routing via executable_via to downstream tools, which is actionable selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds meaningful behavioral detail beyond those flags: the gateway refuses if the live price exceeds confirmed_price_usdc, it enforces wallet per-tx/daily spend limits, and only Base + USDC are supported. This gives an agent a realistic model of the tool's constraints and failure conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three dense sentences with no filler: purpose, routing/alternative, required precondition, and payment limits. Each clause earns its place, and the most operationally critical guidance is clearly marked with 'REQUIRED.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paid external fetch tool with 8 parameters, an output schema, and rich annotations, the description covers the essential operational context: when to use it, what prerequisite must be satisfied, how pricing is enforced, and what networks/tokens are allowed. Remaining details like request body, query, method, and idempotency are fully documented in the input schema, so the description does not need to repeat them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds extra semantic value by explaining that confirmed_price_usdc must come from apiosk_inspect_x402 and that the gateway rejects prices above that amount, and that the url must be an external discovery result. This is crucial context beyond the plain schema property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair: 'Pay an EXTERNAL x402 endpoint ... and return its data.' It also explicitly contrasts with apiosk_execute, so an agent can distinguish the two tools solely from the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance: 'Use this only for external results from apiosk_discover (executable_via="apiosk_fetch_paid")' and 'for Apiosk catalog listings use apiosk_execute.' It also mandates the prerequisite apiosk_inspect_x402 call and confirms the price beforehand.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds valuable behavioral detail: it makes one unauthenticated request, parses the 402 offer, returns the exact amount, and never spends funds. This directly addresses the safety-critical concern of accidental payment.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: what it does, when to use it, and what it doesn't do. Key safety information is front-loaded ('WITHOUT paying') and no redundant wording appears.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and annotations cover the safety profile, the description fully equips an agent to invoke the tool correctly: it explains the input source, the single unauthenticated request behavior, and the explicit exclusion of apiosk_execute. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning by clarifying that the `url` should come from an external apiosk_discover result and that the `method` is the HTTP method the resource charges on. This goes slightly beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Read an arbitrary URL's x402 payment terms') and names the exact data it returns (price, asset, network, payTo). It also distinguishes itself from apiosk_execute, making the tool's unique role clear among the many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use it: on an external result's `url` from apiosk_discover before paying. It also says when not to use it: apiosk_execute does not need this for Apiosk catalog listings. This gives an agent both positive and negative usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md: