apipay

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

With no annotations provided, the description carries the full behavioral burden, and it does disclose something important: the cost is deducted automatically in prepaid credits and returned with the result. However, it says nothing about failure modes, idempotency/retry behavior, or whether a failed call still incurs cost — meaningful gaps for a paid side-effecting operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero filler; the core action and its prerequisite are front-loaded and the billing caveat is appended where it belongs. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter wrapper with no output schema, the description covers the operation, the required lookup step, and the credit-cost side effect — enough to call it correctly. It could go further on how the nested params object maps to each API's manifest and what a failure response looks like.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented (including the example slug 'web-search' and the manifest-driven params object), establishing the baseline of 3. The description's 'by slug' adds no syntax or format detail beyond what the schema supplies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Call an API from the apifare catalog') qualified by the lookup key ('by slug'), which is enough to distinguish it from the sibling search_apis that only finds slugs. An agent can identify the tool's job without reading the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The parenthetical '(find slugs with search_apis)' explicitly routes the agent to the prerequisite sibling tool, which is a genuine usage condition. It stops short of stating when not to use this tool or what happens on unknown slugs, so it is strong but not exhaustive.

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

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

No annotations are provided, so the description carries the full burden. 'Check' implies a read-only, non-mutating call and it usefully defines the credit unit (1 credit = $0.01), but it says nothing about authentication requirements, rate limits, or return shape for what is presumably a remote billing lookup.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; both the primary purpose and the conversion rate earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-param, no-output-schema utility, the description conveys what is returned (balance and a top-up link) and the unit of account. Auth/rate-limit details are the only omission, and those are minor for this tool class.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The credit-to-dollar conversion is the only parameter-like context and it is already covered.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Check') and a precise resource ('apipay prepaid credit balance'), plus a secondary output ('top-up link'). It is clearly distinguishable from the sibling topup, which performs the action rather than just returning the link, though the distinction is implied rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: inspect remaining credit and obtain the top-up link, presumably before calling topup. There is no explicit when-to-use/when-not guidance or named alternative, so it sits at minimum-viable.

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

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

With no annotations, the description carries the full burden and does well: it discloses the link is one-time, that it is the secure path for BYOK, the flat 0.1 credit cost, and that the user's provider account foots the provider bill. It omits link expiry/validity window and any auth requirement, which are the main remaining behavioral unknowns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with what the tool returns, followed by the usage rule and the cost model. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema and no annotations, the description covers purpose, usage mandate, and cost model adequately; the returned link is implied by 'get a secure one-time link.' Minor gaps remain around link expiry and how the link is delivered to the user.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already explains that provider is an API slug from search_apis with an example ('fal'). The description only says 'for a provider' and adds no format, casing, or sourcing detail beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (get) and a specific resource (a secure one-time link for saving the user's own API key), with the BYOK scope made explicit. An agent can distinguish this from call_api or vendor_call, which consume keys rather than collect them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a strong directive: 'Never ask the user to paste an API key into the chat — always use this link instead,' which tells the agent when to reach for this tool over an ad-hoc request. It does not, however, contrast with siblings like secret_generate or secret_transfer, which also deal with secrets, so routing between those is left to inference.

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

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

With no annotations, the description carries the full behavioral burden; it does disclose useful traits — the return fields (slug, params, per-call price in prepaid credits) and the fact that misses are logged so missing APIs get added. It stops short of stating auth needs, result limits, or pagination, which matters for a catalog search tool that returns an unbounded set of matches.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose, then the return shape and the logging side-effect. No filler or restatement of the name; every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter search tool with no output schema, the description covers the essential contract: what is searched, what comes back (slug, params, price), and the miss-logging behavior. It would be fully complete with a note on result volume or pagination, but it is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single query parameter is fully documented as 'What kind of API you need, in plain words.' The description adds no syntax, format, or keyword guidance beyond the schema, so the baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Search) and resource (the apifare catalog of ready-to-call APIs) and enumerates the domain (web search, scraping, weather), so the agent knows exactly what is being queried. It is distinguishable from call_api by implication, but it never names the sibling or explicitly frames this as the discovery step preceding invocation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The catalog-search framing implies it is used to find an API before calling one via call_api, and the 'every miss is logged' note hints at expected negative-result usage. However, there is no explicit when-to-use, no statement of when not to use it, and no named alternative, so the guidance remains inferred rather than stated.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses that generation and placement happen SERVER-SIDE and that the value is never surfaced to the conversation — a meaningful behavioral trait. However, it omits auth requirements, whether the secret is retrievable later, idempotency, and error behavior, which for a write-style tool are significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with zero waste, front-loading the core action and the key security property. Nothing redundant or padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nested-object tool with no output schema and no annotations, the description conveys the central security behavior but leaves too much unstated: how vendor/resource/key identify the destination, what auth is needed, and whether the generated secret can be retrieved afterward. Given the schema's opacity, more was required.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it largely does not. It references 'a vendor resource' but never explains the vendor/resource/key fields of the nested 'to' object, nor the 'bytes' length parameter (16-64). An agent cannot tell what values these accept or how they map to the placement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: generate a random secret and place it at a vendor resource. The scope is clear. It does not explicitly contrast itself with the sibling secret_transfer, so an agent must infer the distinction, keeping it below a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance. The phrase 'the value never enters this conversation' hints at a security rationale but does not tell the agent when to prefer this over secret_transfer or get_vault_link. No prerequisites or alternatives are named.

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

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

With no annotations, the description carries the full burden. It discloses one valuable trait — the transfer is SERVER-SIDE and the value never enters the conversation — but says nothing about required permissions, whether the source secret is retained or removed, idempotency, or failure behavior for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences: the action is front-loaded, the security property follows immediately, and the example earns its place by grounding the abstract vendor-to-vendor move.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a nested-parameter mutation with no annotations and no output schema, the description covers purpose and the secret-handling concern well but leaves parameter semantics and side-effect/return behavior thin. No output schema means return values need not be explained, keeping this mid-range.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the parameters are nested objects, so the description must compensate. The example loosely maps 'from' to a source key and 'to' to a destination env var, but never explains the vendor/resource/field vs vendor/resource/key structure, leaving the semantics largely undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Move a secret from one vendor to another') and clearly separates itself in meaning from sibling secret_generate. It does not explicitly name siblings, but the 'move' framing makes the distinction inferable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The Supabase-to-Vercel example implies a usage context, but there is no explicit when-to-use, when-not-to-use, or routing versus secret_generate/get_vault_link. Usage is conveyed only by example.

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

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

With no annotations, the description carries the full burden and does disclose the critical trait: this tool spends money, bounded by the owner's configured limits, and it describes both the success return (new balance) and the no-mandate fallback (payment instructions). It omits auth/permission requirements and whether charges are reversible or idempotent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the action and funding source, then the limits, then the fallback. 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.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, no-annotation tool with no output schema, the description covers the important unknowns: that a charge occurs, that it is limit-bounded, and what is returned in each branch. It could still say more about permissions and failure behavior, but nothing essential to calling it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single optional amount_usd parameter is fully documented there, including its default and clamping behavior. The description adds nothing about the parameter, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('top up the apifare balance') and precisely scopes the funding source (the owner's standing auto-refill mandate). It is clearly a write/action tool distinct from check_balance or call_api, though it never names an alternative to contrast against explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives the key precondition ('if the owner enabled one') and explains the two outcome branches depending on whether a mandate exists. It does not state when an agent should reach for this tool versus siblings such as check_balance, so the routing guidance is contextual rather than explicit.

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

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

With no annotations, the description carries the full load and does well: it discloses that the owner's root credential is injected server-side, that the token is never visible, and that whole classes of routes are blocked. It omits rate limits, error/response semantics beyond 'native', and whether the credential is scoped down, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences with the credential-injection mechanic front-loaded and no filler. The vendor list is long but functional rather than padding; slightly heavy inline enumeration is the only cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations and no output schema, the description covers auth behavior, route restrictions, and the 'native request/response' return shape, which is what an agent needs to call it safely. It could still say more about failure modes and whether the raw vendor response is passed through unmodified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3. The description adds value beyond the schema by listing the concrete set of valid vendor values (schema supplies only an example and no enum) and by clarifying the injected-credential context for the caller's path/method/body.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Call a vendor MANAGEMENT API') and enumerates the eight supported vendors, which sharply confines the scope. It is distinguishable from the generic sibling call_api by the vendor-managed credential model, though it never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides useful negative guidance by stating that destructive, billing, and member/admin routes are blocked, which tells the agent what will be rejected. It does not, however, say when to prefer this over call_api or the other vault tools, leaving the choice between siblings to inference.

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