Zelnum

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

Adds a great deal beyond the annotations: the call is billable, approval is mandatory before confirmed=true, and the gateway owns idempotency keys with a rule never to retry with modified parameters and to repeat the identical call after an ambiguous timeout. These are exactly the mutation-safety facts an agent needs. Minor gap: no indication of what the final (non-quote) response contains, e.g. whether it returns a task id for get_task_status/get_task_result.

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

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

Front-loads cost and scope in the first clause, then a compact flow, then idempotency guidance. Every sentence carries distinct, actionable information with no repetition of schema or annotations.

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 billed, confirmation-gated tool with no output schema, the price/approval/idempotency contract is well covered, and the quote payload contents (products, estimated_cost) are named. What is missing is the shape of the post-confirmation result and how it links to get_task_status/get_task_result, which would complete the picture.

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 only 43%, and the description compensates for the confirmation parameters by tying confirmed=true to the approval/quote payload and implicitly grounding quote_token and quoted_total. However it says nothing about series, country, identifier, or product_ids semantics beyond the flow, so half the parameters remain undocumented in both places.

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 ('Billable single-identifier detection') plus the billing subject (the authenticated account's API key). Combined with the flow reference to quote_realtime_check and the contrast with bulk sibling create_bulk_task, an agent can tell it apart from siblings without opening a schema.

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

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

Gives an explicit ordered flow: quote, show user products/estimated_cost, get explicit approval, re-call with confirmed=true. It also names the alternative (quote_realtime_check) for the pre-approval step, so the when-to-use-which decision is fully resolved.

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?

Beyond the annotations, the description discloses important behavioral traits: the call is billable, charged to the authenticated account, asynchronous, and accepts no file uploads. It also gives valuable idempotency guidance, telling the agent to repeat the exact same call after an ambiguous timeout because the gateway manages idempotency keys.

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

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

The description is four tight sentences, front-loaded with what the tool does and followed by the critical confirmation rule, upload constraint, and idempotency retry guidance. Every sentence adds operational value with no waste.

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 billable async mutation with no output schema, it covers the critical operational context: billing, confirmation prerequisite, inline input, and safe retry behavior. It is slightly incomplete because it does not say what the agent should do with the resulting task handle or how to poll via the status/result siblings.

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 only 50%, so the description should compensate more than it does. It clarifies that phones is an inline array and ties product/count/estimated cost to the confirmation step, but it says nothing about country, product format, or quote_token behavior beyond what the schema already documents.

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

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

The description states a specific verb and resource: it creates a billable, asynchronous bulk detection task and accepts an inline array rather than file uploads. It is clearly distinguishable from status/result/read-only siblings by implication, but it does not explicitly name or contrast with any sibling tool.

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 a strong usage condition: submit only after confirming product, count, and estimated cost with the user. That clearly frames it as a post-confirmation step, but it does not explicitly name the quote or realtime-check sibling as the preceding tool or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds genuinely new context by resolving which account is read (the API key of this connection) and reassuring that the call never charges. It stops short of describing the returned balance format or units, but that is a modest gap given annotations.

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

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

Two short sentences with zero filler; the account scoping is front-loaded and the no-charge reassurance follows immediately. 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 zero-parameter read tool with annotations and no output schema, the description covers what it does and on whose behalf. The only missing detail is what the balance value looks like (currency/units), which the absent output schema leaves undocumented.

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 and the baseline applies. The description correctly implies no inputs are needed.

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 (read) and resource (current balance) and scopes it to the authenticated ZelNum account identified by this connection's API key. That scoping distinguishes it from sibling tools like check_realtime or list_products without opening either 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?

Usage is implied by 'current balance' and the read-only framing, but the description never states when to prefer this over siblings such as check_realtime, nor any conditions for calling it. An agent must infer its place in the toolset.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: the response includes an authenticated download URL, results are only available post-completion, and the agent must not expose or guess foreign task IDs — a real access-control constraint beyond structured data.

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 short sentences, zero filler, with the output content front-loaded before the security constraint. Every clause carries information the agent needs.

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

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

With no output schema, the description carries the return-value burden and does name the two returned elements. It is thin on edge behavior — what happens if the task is still running, whether the URL expires, or how errors surface — which keeps it short of a 5.

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 single task_id parameter is undocumented structurally. The description partially compensates by implying the ID must be one the caller legitimately holds ('do not expose or guess another task ID'), but it never states where the ID comes from (create_bulk_task) or its format.

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

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

The description gives a specific verb ('Return') and a concrete resource ('result metadata and the authenticated download URL'), scoped by the precondition 'after a task completes'. That implicitly separates it from the sibling get_task_status, but it never names that sibling the way a 5 would.

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 phrase 'after a task completes' implies the usage context, but the agent must infer that get_task_status is the tool to poll first. There is no explicit when-not or named alternative, so usage is only implied.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: results are scoped to tasks 'owned by the authenticated account' and the payload contains progress plus billing counters, which tells the agent what it will get back. It omits behavior for unknown/expired task_id or polling cadence.

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

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

One sentence with zero filler and the resource is front-loaded after the verb. It is efficient but borders on terse given the missing usage and parameter detail.

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

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

For a simple one-parameter read with annotations and no output schema, the description covers purpose and return contents. It leaves gaps on how the task_id is obtained, error behavior for invalid/completed tasks, and whether polling is expected.

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 single task_id parameter has no description anywhere. The description only implies the ID identifies a bulk task, giving no format, source, or validity constraints beyond the schema's length limits.

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 ('Read') and a precise resource ('progress and billing counters for a bulk task'), which distinguishes it from get_task_result and check_realtime by scope. It stops short of explicitly naming how it differs from those siblings.

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

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

Usage is only implied: 'progress' suggests polling a running task while get_task_result is presumably for finished output, but no when-to-use condition or alternative is stated. An agent must infer the routing decision from sibling names alone.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered structurally. The description adds real context beyond that: only ACTIVE products are returned, and the payload carries IDs, slugs and series. It does not mention ordering or result-set size, which is the only missing behavioral detail.

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, zero filler, with the core action and the critical ordering prerequisite front-loaded. Every sentence carries a distinct instruction (what it returns, when to call it, where to get prices).

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

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

With no parameters and no output schema, the description carries the burden of describing return shape, and it does name the returned fields. It stops short of saying how large the list is or whether it is paginated, a minor gap for an otherwise trivial closed-world lookup.

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 no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies the call is unfiltered and returns the full active catalog.

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 (List) and resource (active products) plus the exact fields returned (IDs, slugs, series). It also distinguishes itself from the quote siblings by pointing price lookups elsewhere, so an agent can separate it from quote_realtime_check without opening any schema.

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

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

Gives an explicit precondition ('Always call this before selecting product_ids'), an explicit prohibition ('never invent IDs'), and names the alternative for a related need ('Use a quote tool for authoritative prices'). This is exactly the when/when-not/alternative structure.

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?

Adds real context beyond readOnlyHint/openWorldHint: the call is free, the returned price is authoritative, and the caller must retain quote_token plus total for a later call. 'Never compute prices yourself' is a useful guardrail. It stops short of saying what happens if the token expires or whether the quote is time-limited.

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, no filler, with the cost/authority guarantee front-loaded and the retention requirement immediately after. Nothing is redundant with the name or title.

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

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

With no output schema, the description usefully names the return fields (quote_token, total). But for a 4-parameter tool with zero schema coverage it leaves series and country undefined and does not clarify the handoff to the confirming tool.

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

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

Schema description coverage is 0% across 4 parameters, so the description carries the burden. It clarifies identifier and product_ids only; the 'series' enum (phone/email) and the 'country' ISO-3166 pattern go entirely unexplained in both schema and description.

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: a quote for one identifier against product_ids. The phrase 'for the confirmed call' hints that this is a preview step distinct from the commit path, but it never names the sibling check_realtime, so the boundary is inferred 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?

'Show its total to the user and preserve quote_token plus total for the confirmed call' implies a quote-then-confirm workflow, but no explicit when-to-use, when-not, or which sibling performs the confirmed call. The agent must guess that check_realtime is the follow-up.

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