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

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds real value beyond them: it states the call is free and discloses a hard limitation (API keys cannot read the account balance) that no annotation covers.

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 is returned, then cost, then the limitation and fallback. The dashboard URL earns its place by telling the agent what to tell a user who needs the account balance.

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?

There is no output schema, so the description must carry the return-value burden, and it names the two returned concepts (spent amount and limit). It is slightly vague on what happens in the no-limit case (null vs. absent) but is otherwise complete for a zero-argument read.

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 the baseline is 4. Nothing in the description misrepresents the input surface, and the absence of arguments is consistent with a simple key-scoped lookup.

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: shows what the API key has spent and its own spending limit. It also scopes the answer precisely by ruling out the account balance, which is the main ambiguity for a balance-checking tool. Sibling names are unrelated resources, so sibling differentiation is not a meaningful test here.

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

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

Provides clear context for when the result is sufficient versus insufficient: keys without a limit draw on the account balance, which this tool cannot read, with a URL where the user can see it. That is a genuine conditional routing instruction, though it stops short of explicit 'use this when' phrasing.

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?

Goes well beyond the readOnly/idempotent annotations: it declares the call is free, that nothing is submitted, and enumerates the four status outcomes with a strong instruction never to present token_billed or unknown as a price. That is exactly the behavioral context the annotations cannot carry.

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?

Four sentences, front-loaded with purpose, then the status semantics, then the approval gate. Every clause carries operational weight; nothing is padding.

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?

There is no output schema, and the description compensates by explaining what each returned status means and how to present the result. Combined with the mutation-adjacent workflow (approval before generation), an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 67% and the description reinforces the key semantic that 'input' is the model request fields without model/async, plus it flags reference_video_seconds as the typical missing field behind needs_input. It does not add much about the 'model' parameter, but that parameter is self-evident.

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 pair and resource: validate a planned input and quote list price, explicitly 'without submitting anything'. This distinguishes it cleanly from the sibling generation tools (generate_image, generate_video) and from get_model.

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 explicit when-to-use (before calling generate_image or generate_video), a required protocol step (show model, input and estimate, then wait for explicit approval), and a when-not-to-use implication (it does not submit). No alternative 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?

Annotations give readOnlyHint=false and openWorldHint=true, but the description adds the crucial non-obvious traits: it is billable against the user's balance, input is validated against the model schema before any charge, execution is async with a bounded wait, and re-invocation is not the progress-check path. These are behaviors an agent could not infer 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.

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

The billing warning is front-loaded and every sentence carries an operative rule, but the paragraph is dense and stacks approval, routing, validation, async, and polling rules into one block. Slight structural cost, no wasted 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 billable, async, branchy tool with six parameters, nested input, no output schema, and non-idempotent annotations, the description covers the spend guardrails, execution mode, wait/poll handoff, and duplicate-charge avoidance. Nothing an agent needs in order to call it safely 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema only implies: input.images as the switch that routes to the edit endpoint, and wait_seconds as the boundary after which the agent must switch to get_task. The billing implications of model and max_cost_usd are reinforced by the 'approved model and cost' precondition.

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 (creates a paid image task) and further specifies the two modes: edit when input.images is present, generate otherwise, with the underlying endpoints named. This separates it cleanly from estimate_cost, get_task, and generate_video in the sibling list.

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

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

Explicit preconditions (call only after estimate_cost on the same input and explicit user approval of model and cost), explicit edit-vs-generate branch, and an explicit exclusion: 'Never call again to check progress' with get_task named as the polling alternative.

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 only declare the generic profile (not read-only, open-world, non-idempotent); the description adds the operational facts an agent cannot infer: async semantics (returns task_id at once, minutes-long runtime), per-second billing including extra billed seconds for reference videos, and the approval gate. The client_request_id dedup note is consistent with idempotentHint=false rather than contradicting it.

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?

Five short sentences, front-loaded with BILLABLE and the endpoint, then the precondition, then the async/polling behavior. No filler and no repetition of the schema.

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 7-param, nested-object, billable async tool with no output schema, the description covers cost model, approval prerequisite, return shape (task_id), and the correct follow-up tool. An agent has everything needed to call it safely once.

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

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

Schema coverage is 100%, so the baseline is 3. The description still contributes cross-parameter semantics – that reference videos 'add billed seconds' and that model/duration/resolution/cost must have been approved – which links max_cost_usd and reference_video_seconds to the billing decision rather than restating their schema text.

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?

Opens with a specific verb+resource ('creates a paid video task') plus the endpoint (POST /v1/videos) and the billing basis (charged per second). The word 'video' plus the cost framing separates it cleanly from generate_image and the read-only 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?

Explicit preconditions: 'Only call after estimate_cost on the same input and the user's explicit approval of the model, duration, resolution and cost.' It also names the alternative for the follow-up step ('poll with get_task') and states a negative rule ('Never call again to check progress').

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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuine beyond-schema context: the call is 'Free' (no billing impact) and the returned input_schema is authoritative for what other tools accept — a real behavioral constraint, though error behavior for a bad model id is unstated.

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 dense sentences, zero filler. The payload enumeration comes first and the downstream routing instruction second, which is the right order for an agent deciding whether to call it.

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?

There is no output schema, so the description must describe returns — it does so field-by-field (request fields, endpoints, async/sync, price tiers), which is sufficient. Missing only failure-mode detail, e.g. what happens when the model id doesn't resolve.

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?

Only one parameter and schema description coverage is 100% — the schema already says 'Exact model id from search_models'. The description adds nothing about the model id format or how to recover from an invalid id, so it sits at the high-coverage baseline of 3.

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

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

States a specific verb and resource ('Read one model's ...') and enumerates the payload precisely (input_schema types/enums/defaults/required, endpoints, async/sync modes, price tiers), so the agent knows exactly what comes back. The singular 'one model' implicitly separates it from the sibling search_models list tool, but no sibling is named outright.

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

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

Clear workflow context: 'Send only fields from input_schema to estimate_cost and the generate tools' tells the agent this is the prerequisite lookup step for the cost and generation siblings. It never states when *not* to call it or names search_models as the alternative for discovery, so the exclusion side is missing.

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?

Goes well past the annotations (readOnlyHint, idempotentHint), which only establish that this is a safe repeatable read. The description adds cost ('Free'), failure handling ('Failed tasks are refunded automatically'), and a 24-hour retention limit on result links — exactly the operational facts an agent needs beyond the schema.

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?

Five short sentences with no filler. The return payload is front-loaded, followed by cost, polling semantics, failure/refund behavior, and link expiry — each sentence carries distinct, actionable 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?

With no output schema, the description carries the burden of describing return values, and it does so explicitly (status states, progress, result_urls, fail_reason). Combined with the timeout and link-expiry behavior, an agent can call and interpret this tool correctly with nothing 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 coverage is only 50%, and the undocumented parameter is wait_seconds; the description fully compensates by supplying the semantic range (0-45), the default (30), and the behavior (keeps polling until finished or timeout). It also frames task_id's provenance ('returned by generate_image or generate_video') via the schema.

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

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

States a specific verb and resource ('Read an image or video task') and enumerates exactly what is returned (status, progress, result_urls, fail_reason). This is plainly distinct from the sibling generators (generate_image/generate_video) and account tools (check_balance) without ambiguity.

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 clear operating context: the tool is free, pollable via wait_seconds, and result links expire after 24 hours, which tells the agent it must fetch results promptly. It stops short of explicitly saying 'call this after generate_image/generate_video' or naming when-not-to-call, so it is strong context rather than full routing guidance.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-redundant context: the results are scoped to the calling API key, the call is free, and text models are not invocable through this server. It stops short of describing result ordering or pagination behavior.

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, and the highest-value instruction ('use it before get_model') is front-loaded alongside the purpose. Every clause carries information the agent acts on.

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?

No output schema exists, and the description compensates by naming the returned fields (category, list prices, generation modes). Combined with annotations covering safety, an agent has enough to call this correctly; only minor operational details like result ordering or total-count behavior are absent.

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%: limit, query and category are all documented, including the category enum and defaults. The description only echoes the category values ('image / video / chat') and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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 (list APIKO models usable by this API key) and enumerates the returned fields: category, list prices, generation modes. It is clearly distinguished from sibling get_model, which the description explicitly positions as the follow-up step.

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 explicit sequencing ('Use it before get_model; never guess model ids') and an explicit exclusion (text models are listed for reference only and must be called via the OpenAI-compatible API, not this server). That is exactly the when/when-not/alternative coverage an agent needs.

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 substantial behavior beyond the annotations: per-key rate limits (60/min, 1,000/day), public visibility of the uploaded copy, 72-hour automatic deletion, and the user-consent constraint. These are exactly the side effects an agent needs to judge before calling a non-idempotent write.

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?

Four dense sentences, front-loaded with capability and return value, then constraints, then cost/limits, then safety caveat. No filler and nothing repeated from the schema.

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?

Covers formats, size limit, return value (compensating for the absent output schema), the either/or input rule, rate limits, retention, and privacy. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds the mutual-exclusion rule (exactly one of path or url) that the schema cannot express given zero required parameters and no oneOf. The parenthetical 'a local file the user named' also adds consent semantics to path.

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 (upload an image), names accepted formats and the 10 MB cap, and specifies the output (a public https://img.apiko.app URL). It also names the destination reference fields, which clearly separates it from siblings like generate_image or generate_video.

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 concrete conditions: supply exactly one of path or url, and only upload files the user explicitly asked to use. It implies the context (populating reference fields) but never names an alternative tool such as generate_image, so the when-not is only partially covered.

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