StockCake

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

Annotations declare non-read-only, open-world, non-idempotent behavior, and the description adds substantial context beyond them: per-second pricing, plan/account requirements, the >45s latency expectation, the pending-then-poll lifecycle, and the host sign-in prompt. This is exactly the operational behavior an agent needs before invoking an expensive async generation.

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 compact sentences, front-loaded with the core action and cost/latency caveats, with no filler. Slightly dense but every sentence carries information about cost, prerequisites, and the async lifecycle.

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

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

Given a 10-parameter schema with 90% coverage, an output schema, and rich annotations, the description supplies the remaining critical context: prerequisites, cost model, latency expectation, and the required get_job polling step. Nothing an agent needs 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 description coverage is 90%, so the schema already documents nearly every parameter (including the prompt/start_image exclusivity and duration constraints). The description only restates 'prompt and/or a start image' and adds no syntax or format detail beyond the schema, so the 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+resource ('Generate a short video') and the two input modes (prompt and/or start image), and names the sibling list_models as the source of model choices. It is clearly distinguishable from generate_image and other 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?

Explicitly routes the agent to list_models for model/tier selection, states prerequisites (needs a plan, requires a free StockCake account with a host sign-in prompt), and gives the follow-up pattern (expect a pending result and poll get_job). When-to-use is fully covered with no inference required.

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, and non-destructive, so the bar is lower. The description adds real behavioral context beyond them: it is unmetered/no-credit, requires sign-in, and explains png fallback behavior. It does not cover pagination or response shape, but the output schema exists.

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 core purpose, then cost, then format/auth caveats. No filler or repetition; it is tight though slightly dense.

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 read-only download tool with full schema coverage and an output schema, the description covers auth, billing, and format behavior adequately. Nothing essential is missing, though return/download mechanics are left to the output schema.

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

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

With 100% schema description coverage the baseline is 3, and the description meaningfully exceeds it by explaining the 'format' parameter semantics: png returns the lossless sibling when one exists and falls back to jpg. That is genuine meaning the schema's one-line 'Default jpg' does not convey.

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 ('Full-resolution download link for a StockCake image... or one of your edited images') and scopes it to full-resolution CC0/edited assets, which implicitly separates it from get_image, resize_image, and upscale_image. It does not explicitly name a sibling to contrast against, so it stops 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.

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

It supplies useful context ('Unmetered — no credits') and a prerequisite ('Requires a free StockCake account'), but gives no explicit when-to-use/when-not guidance or alternative routing versus the sibling tools. Usage 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.

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 a genuine behavioral clarification that 'total_results' is per-page rather than catalog-wide, preventing a common misread; it stops short of describing pagination limits or tie-breaking.

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 tightly packed sentences with no filler; the scoping rule and the total_results caveat are both front-loaded and each 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?

With annotations covering safety and an output schema covering returns, the description only needed to clarify the ambiguous counter — which it does. It says nothing about the required context/llm_model/conversation_id protocol, but those are heavily documented in the schema itself.

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 schema already documents id provenance, page/limit bounds, locale, and the analytics/context fields, so the description's only parameter-adjacent content just restates schema facts. 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+resource ('find images visually similar to a given StockCake image id') and anchors the input's provenance to a sibling tool ('from search_images results'), so an agent can distinguish it from search_images 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.

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

The parenthetical sourcing rule ('from search_images results') tells the agent when this tool is applicable — after a search — but it does not explicitly state exclusions or contrast with other related tools like get_image.

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 write/openWorld/non-idempotent profile; the description adds substantial behavior beyond that: it charges credits, the 45 s wait window, that a pending result carries a job_id to feed get_job, that reference images are plan-capped, and that a signed-in account is required. This is exactly the extra context an agent needs for a paid, network-reaching mutation.

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-loaded with the core action, then each subsequent clause carries a distinct, load-bearing fact (cost, latency, fallback, reference constraint, auth). No filler sentences.

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 an output schema present, return values needn't be described, and the description still covers cost, latency, the job_id fallback, and the auth requirement. Nothing material for correct invocation 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 high (75%), so the baseline is 3, but the description adds genuinely new meaning: reference images are optional and plan-capped, and model/tier selection is sourced from list_models. It does not elaborate on prompt/context/conversation_id beyond the schema.

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

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

States a specific verb+resource ('Generate a new image from a prompt') and scopes it to StockCake's AI models, which cleanly separates it from create_video and the search/edit siblings. An agent can identify the operation 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.

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

Routes the agent to list_models for model selection and to get_job when a result is pending, and states the account prerequisite. It stops short of explicitly contrasting with alternatives like search_images or create_video, so it is clear context rather than full when/when-not 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 cover the read-only/idempotent/non-destructive safety profile, so the bar is lower, yet the description adds genuinely useful behavioral context: it requires a free StockCake account and that the host will prompt the user to sign in. That auth-behavior disclosure is exactly the kind of thing annotations cannot convey. It does not mention rate limits or caching, so not 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?

Two tight sentences with zero filler; the returned-data list is front-loaded and the auth caveat follows. Efficient, though the field enumeration is slightly list-like rather than prose.

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 an output schema present, the description is not required to explain return values and still does so usefully. The auth prerequisite is disclosed, which is the main non-obvious operational fact. Adequate for an agent to invoke correctly, minor gap in routing versus get_license_info.

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 baseline is 3. The description adds nothing about the three params (context, llm_model, conversation_id) — it never mentions the conversation_id continuity requirement that the schema documents, nor does it need to since the schema carries it.

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 the specific resource (the signed-in user's account) and enumerates what it returns: plan, credit balance breakdown, next resets, download quality, output formats. That is far more concrete than a tautology. It does not explicitly distinguish itself from the sibling get_license_info, which is the only nearby concept, so it stops 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.

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

There is no statement of when to call this versus alternatives such as get_license_info or list_models, nor any exclusions. The only contextual hint is the auth requirement, which describes cost of use rather than when it is appropriate to use.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the inline preview is model-visible and costs tokens, and can be suppressed with include_preview=false. It stops short of auth or rate-limit notes, but the preview/token tradeoff is the useful non-obvious behavior for a read 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?

Front-loaded with the verb and resource, and the metadata inventory is packed into a single tight sentence with no filler. Dense but every clause earns its place; only the parenthetical preview caveat is a slight interruption.

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 a full output schema, rich annotations, and 100% parameter coverage, the description only needs to frame what kind of image record is returned, which it does by listing dimensions, provenance, license, and attribution. Nothing an agent needs to invoke it correctly is missing from the combined definition.

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% across all 6 parameters, so the schema already documents id formats, locale enum semantics, context, llm_model, and conversation_id handling. The description only echoes include_preview's effect ('unless include_preview is false'), adding nothing beyond what the schema states. Baseline 3 is correct.

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 ('Fetch') and resource ('one image') and enumerates the metadata returned, which clearly separates it from lookalikes such as search_images or download_image. It does not name a sibling explicitly, but the singular 'one image by id' scope is unambiguous.

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

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

Usage is implied by the id-based fetch and the metadata list, but the description never states when to prefer this over download_image (get the file) or search_images (find by query), nor any prerequisite such as needing an id from search results. No explicit alternatives or exclusions.

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 cover readOnly/idempotent/openWorld/non-destructive, so the bar is lower; the description adds real value by disclosing the account/auth requirement ('requires a free StockCake account, host will prompt to sign in') and the possible outcome states including an error with refund state, which the annotations do not convey.

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 tightly packed sentences, front-loaded with purpose and scoped to the originating tools, with the auth caveat following. No filler; 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?

An output schema exists so return values needn't be described, yet the description still summarizes outcome states, and it covers the auth prerequisite. The only minor gap is not stating where job_id originates, though 'job you started' implicitly ties it to the creator tools.

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 75%, and the description adds no syntax or source detail for job_id beyond 'job you started'; context, llm_model, and conversation_id are documented in the schema itself. Baseline 3 applies since the schema does the heavy lifting and the description does not extend it.

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 (get job status and result) and names the exact sibling tools whose jobs it tracks (generate_image, upscale_image, resize_image, create_video). An agent can distinguish it from those creators and from get_image/get_account 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?

Strongly implies the when-to-use ('a ... job you started'), i.e. poll after kicking off one of the named async tools. It doesn't explicitly state when not to use it or name a polling alternative, but there is no competing status tool among the siblings, so context is clear.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real substance by stating the license is site-wide CC0/public domain, but says nothing about auth needs, rate limits, or scope boundaries.

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

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

A single tight sentence with the key term (CC0 / public domain) front-loaded in parentheses. Zero filler.

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 read-only informational tool whose safety profile is fully covered by annotations, the description adequately conveys what is returned (license and usage terms). Minor gap: it doesn't state the response shape or whether terms vary per image, though the 'site-wide' wording implies uniformity.

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 context, llm_model, and conversation_id are fully documented in the schema, including edge cases ('pass unknown — never guess'). The description adds no parameter meaning, so the 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?

Clearly states the resource ('License and usage terms for all StockCake images') and scopes it ('site-wide CC0 / public domain'). It reads distinctly from the image-manipulation siblings, though it never explicitly names a differentiating sibling, which keeps it just 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.

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the eleven siblings. An agent can infer it is for license questions, but nothing routes it explicitly against e.g. get_image or search_images.

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, idempotentHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: an auth requirement (free StockCake account, host prompts sign-in) and pricing semantics (video billed per second, free-credit models flagged).

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, front-loaded with what the tool returns and followed by pricing and auth caveats. No filler, nothing restated from the 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 an output schema present, return-value documentation is unnecessary, and the description covers the auth prerequisite and pricing model. It could have been slightly more explicit about when to call it relative to the generation tools, but nothing needed to invoke it 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 description coverage is 100%, so the parameters are fully documented in the schema and the baseline is 3. The description corroborates that the result is split into image and video catalogs and explains pricing units, but adds no syntax or usage detail beyond what the schema already 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?

The description states exactly what is returned: image and video models with per-tier credit prices, free-credit flags, and per-second video pricing, and ties the catalog to the sibling tools that consume it (generate_image / create_video). It is clear which resource is being enumerated, though the listing verb itself is only implied by the name/title.

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

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

The description implies the catalog is consulted before calling generate_image or create_video, and the kind parameter narrows it to one catalog, but there is no explicit 'call this when…' guidance or statement of when to skip it. Usage is inferable 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?

Goes well beyond the annotations by disclosing cost ('charges credits'), latency ('waits up to 45 s'), the async job_id return pattern, and an auth prerequisite (free StockCake account, host sign-in prompt). These are exactly the traits annotations do not capture.

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 short sentences with zero filler, and the core action is front-loaded ahead of cost, latency, and auth details. Dense but each clause carries distinct operational 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 paid, async, auth-gated mutation tool, the description covers cost, wait time, return contract, follow-up tool, and account requirement; the output schema handles return values. Nothing an agent needs to invoke it 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 description coverage is 100%, so parameters like image, prompt, context, llm_model, aspect_ratio, and conversation_id are already documented in the schema. The description adds no parameter-level detail beyond what the schema and its enum provide, 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 (change aspect ratio by extending the canvas), names the mechanism (AI outpainting, GPT Image 2.5), and clarifies the subject is preserved. This clearly distinguishes it from siblings like upscale_image and generate_image.

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?

Explains the scenario (aspect-ratio change via outpainting) and routes the agent forward, saying the returned job_id is used with get_job. It does not explicitly contrast with upscale_image or generate_image, so an agent must infer which sibling to prefer.

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, open-world and non-destructive, so the safety profile is covered. The description usefully adds that total_results spans the whole catalog rather than the page, and that refinements enumerates valid mood/style facet values for the query — behavior not visible in 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?

Three front-loaded sentences with no filler; the catalog-scope clarification and refinement strategy come first. Slightly terse on the retry triggers but every sentence 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?

With an output schema present the description needn't restate return values, and it correctly clarifies the one ambiguous field (total_results scope). For a 12-parameter tool with a required conversation_id handshake documented in-schema, coverage is adequate.

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 83%, so the schema already documents most parameters, including mood/style refinements, query length, limit and the conversation_id protocol. The description's query-refinement advice largely echoes the query field's own description, adding little beyond the schema baseline.

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 first sentence states a specific verb (search) and resource (StockCake image catalog) with the natural-language modality. It doesn't distinguish itself from the close sibling find_similar_images, but the purpose itself is unambiguous.

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

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

It gives concrete query-refinement strategy ('start short; when total_results is small or off-target, retry with fewer keywords or different phrasing'), which is real operational guidance. It does not, however, say when to prefer this over find_similar_images or generate_image.

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 (which only say non-read-only, non-idempotent, open-world): the 45 s wait before falling back to a job_id, credit charging, plan quality caps, and an authentication requirement with a host sign-in prompt. These are exactly the operational facts an agent needs and cannot get from structured fields.

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 compact passage, front-loaded with the operation and its output, then the cost/limit, then the async fallback and the auth prerequisite. Every clause carries information; 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?

With an output schema present, return values need no explanation, and the description covers cost, limits, async behavior and auth. Minor gap: it does not say what happens if the job is still pending or how the job_id should be consumed beyond naming get_job.

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 80%, so the schema already documents image sources, scale, context, llm_model and conversation_id. The description reiterates the allowed scales and the image source types but adds no syntax or format detail beyond that, so the 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 (upscale), the accepted resource types (StockCake images or your own edited images), the exact multiplier set (2x/4x/8x) and the output format (lossless PNG). This is clearly distinguishable from the sibling 'resize_image' purely on the verb, 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?

Gives real operating conditions: plan quality caps apply and credits are charged otherwise, and it names the follow-up tool (get_job) for the async path. It stops short of an explicit when-to-use-this-versus-resize_image or generate_image rule, so it is clear 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.