StockCake

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

Adds substantial context beyond the annotations: pricing is per second of output, a plan is required, an account sign-in will be prompted by the host, and the call is typically asynchronous (>45 s, expect pending and poll get_job). The annotations only give the generic write/open-world/idempotency profile; the description supplies the operational reality.

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, zero filler, front-loaded with what is produced before the cost, latency, and auth consequences. Every clause carries information an agent needs before calling.

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 10-parameter paid, async, account-gated generation tool with an output schema, the description covers the missing pieces an agent must know: cost model, plan/account requirement, async polling expectation, and where to get valid model ids. Return values are rightly 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?

Schema description coverage is 90%, so the schema already documents tier, model, prompt, aspect_ratio, duration, and even the conversation_id protocol. The description only confirms the prompt-or-start-image relationship and points at list_models for model ids; with the schema doing the heavy lifting, 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+resource ("Generate a short video") plus the inputs it accepts ("from a prompt and/or a start image") and the provider scope (StockCake's video models). This clearly separates it from the sibling generate_image, which is the nearest ambiguous alternative.

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 to list_models for model/tier selection and to get_job for polling, and states the prerequisites (paid plan, free StockCake account). It never says when NOT to use this tool (e.g. when the user wants a still image instead), so it stops short of a 5.

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

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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful caveat that total_results counts only similar results on the page, not catalog-wide, but does not extend to pagination limits, auth, or other 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?

Two tight sentences, front-loaded with the core action and followed by the one semantic caveat an agent could otherwise misread. Nothing is wasted.

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, rich annotations, and 100% schema description coverage, the description does not need to re-explain parameters or returns. It is complete for its role, only lacking explicit alternative routing that would lift it further.

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%, with each of the 7 parameters (page limits, locale, context, conversation_id mechanics) fully documented in the schema itself. The description adds no parameter syntax or meaning 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?

The description states a specific verb+resource+scope: 'find images visually similar to a given StockCake image id'. Referencing '(from search_images results)' ties it to the sibling that produces the input, implicitly separating it from text search. It is clear, though it never explicitly names an alternative tool it is not.

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?

Tagging the id as coming 'from search_images results' implies the workflow (search first, then find similar), but there is no explicit when-to-use/when-not guidance or named alternatives. Usage is implied 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: it discloses the credit cost model, that free credits cover free models, the 45 s wait with a job_id fallback for async retrieval, that reference images are plan-capped, and that a StockCake account/sign-in is required. These are exactly the auth, cost, and latency traits an agent needs and that readOnlyHint/idempotentHint 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?

Four tightly packed sentences with the core action front-loaded and no filler; each clause carries a distinct fact (models, cost, latency, auth). It is dense to the point that the parenthetical tool references crowd the prose slightly, keeping it just under a 5.

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 need not be explained, and the description already covers cost, latency, async continuation via job_id, reference-image constraints, and authentication. For an 8-parameter generative tool this leaves nothing material for the agent to guess.

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 schema itself documents tier, model, aspect_ratio, conversation_id, and the analytics-only llm_model well. The description adds useful semantics on top: model ids come from list_models, and reference_images are constrained by plan. It does not touch tier or aspect_ratio, but the schema carries those adequately.

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?

Specific verb (Generate) plus resource (a new image) plus the mechanism (from a prompt with one of StockCake's AI models). It routes the agent to list_models for model selection, and the 'new image' framing implicitly separates it from search_images/find_similar_images, which return existing images.

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?

Clearly states the operating context: use list_models to pick a model, get_job when the call returns pending, and that an account is required with the host prompting sign-in. It stops short of an explicit when-not/alternative statement (e.g. 'use search_images to find existing images'), leaving that to inference from siblings.

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 value with the authentication requirement and the note that the host will prompt to sign in, which is exactly the kind of context annotations cannot express. It does not cover rate limits or failure modes, 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 sentences with no filler; the returned data is front-loaded and the account prerequisite follows. The 'free / subscription / purchased' parenthetical earns its place by enumerating credit types, but the sentence is somewhat dense rather than optimally structured.

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 rich annotations, a 100%-covered schema and an output schema that carries the return shape, the description only needs to frame purpose and prerequisites, which it does. Nothing critical for invoking the tool is missing, though guidance against the adjacent get_license_info would make it fully complete.

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 all three parameters (context, llm_model, conversation_id) carry detailed inline descriptions, including the conversation_id continuity rule. The description adds nothing about parameters, 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?

The description names a specific resource (the signed-in user's plan, credit balance, reset dates, download quality and output formats), which unambiguously separates it from the image/video generation and search siblings. It never explicitly contrasts itself with the nearest sibling, get_license_info, so it falls short of a 5.

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

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

It states a prerequisite (a free StockCake account, with the host prompting sign-in), which is useful context, but it never says when to reach for this tool versus get_license_info or list_models. Usage is only implied by the data it returns.

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 and open-world, so the safety profile is covered. The description adds real behavioral context beyond them: the response includes a model-visible inline preview whose token cost can be avoided via include_preview=false, and that edited-image ids require an authenticated account. It stops short of describing failure behavior for unknown ids.

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 with no filler, front-loaded with the return payload an agent most needs to decide whether to call it, followed by the id-space clarification. 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?

With a full annotation set, 100% schema coverage and an output schema, the description is nearly complete for a read-by-id tool: it covers return contents, accepted id forms, and the preview toggle. The only missing piece is explicit routing against sibling retrieval/download tools, which is a guidance rather than completeness gap.

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 meaning: it explains that the preview is inline and model-visible (why include_preview matters) and maps the id space to its sources, including the ≥10000000000 edited-image range. This reinforces and contextualizes the schema rather than merely repeating 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 and resource ('Fetch one image with full metadata') and enumerates exactly what comes back: inline preview, pixel dimensions, AI provenance, license details, attribution snippets. It also distinguishes this tool from the generation siblings by clarifying that edited-image ids are the ones returned by generate_image, resize_image and upscale_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?

Usage is implied rather than stated: the mention that ids come 'from search results' or from generate/resize/upscale results tells the agent where a valid id originates, and names those siblings. But there is no explicit when-to-use-this-vs-alternative guidance (e.g., get_image vs download_image vs find_similar_images), and no exclusions or prerequisites beyond the parenthetical about needing a signed-in account.

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?

Annotations mark this as a non-read-only, non-idempotent, open-world mutation, and the description adds substantial context beyond them: it charges credits, the output is the model's native ~1.5 MP size regardless of source, it waits up to 45 s before returning a job_id for get_job, and it requires a free StockCake account. This is exactly the async/billing/auth detail annotations cannot 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?

Front-loads the operation and its subject-preservation guarantee, then layers cost, output-size behavior, the async fallback, and auth prerequisites in tight, non-redundant sentences. No sentence is 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 6-parameter, credit-charging async tool with an output schema, the description covers the essentials an agent must know to call it correctly: cost, expected output resolution, the 45 s wait/job_id path, and the sign-in requirement. Nothing material 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 every parameter (including the non-obvious llm_model and conversation_id conventions) is already documented in the schema. The description adds no parameter-level guidance beyond what the schema provides, 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 and resource ("Change an image's aspect ratio by extending the canvas") and immediately clarifies the mechanism and preservation semantics ("the subject is kept, new area is generated"). It is clearly distinguishable from sibling generate_image (no source image) and upscale_image (which is named for the larger-output case).

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 a sibling when needed: "For print or larger web use, run upscale_image on the result." It also names the required account and the sign-in prompt. It stops short of stating when NOT to use this tool (e.g. when the user wants a from-scratch image via generate_image), so it is clear context without full exclusion 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine beyond-schema context: total_results is a catalog-wide count, and refinements mood/style are hard filters where small counts mean few matches. It does not discuss rate limits or pagination limits (page max 5), keeping it from 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?

Four front-loaded sentences, each carrying information: search scope, two output-field clarifications, and query strategy. No filler or repetition, though the output-field sentences sit slightly ahead of more actionable query guidance.

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 12-parameter search tool with an output schema already present, the description covers the non-obvious behavioral contract (count semantics, hard-filter facets, retry strategy). Return values needn't be explained given the output schema. Minor gap: no mention of the page 1-5 ceiling or result-set interplay with limit.

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 carries most parameter meaning (facet semantics, locale, limits, conversation_id protocol). The description's added text explains output fields (total_results, refinements) rather than parameters, so it adds little parameter-level meaning beyond the 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?

States a specific verb and resource ('Natural-language search over StockCake's catalog'), which is clear on its own. It does not name or distinguish against potential sibling confusion such as find_similar_images or generate_image, 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?

Provides real usage guidance for query crafting and retrying ('Start with a short query; when total_results is small or off-target, retry with fewer keywords'), which is better than nothing. However it never says when to choose this tool over siblings like find_similar_images or generate_image, so routing guidance is implied at best.

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 cover readOnly/idempotent/non-destructive, so the safety profile is handled, and the description adds the crucial behavioral fact that this records feedback without adding or changing tools, plus a PII/sensitive-content prohibition. It does not mention whether feedback is reviewed, rate limits, or what happens after submission, but for a fire-and-forget reporting tool that is a minor gap.

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 tight sentences that front-load the primary instruction (report missing capabilities whenever no tool fits) before the secondary cases and the important constraints. Every sentence carries non-redundant information, including the PII warning placed last as a guardrail.

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 feedback-reporting tool with no output schema and full schema description coverage, the description supplies exactly the missing pieces: the priority ordering of feedback types, the fact that nothing is added or changed, and the content restriction. Nothing an agent needs in order to call it correctly is 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 coverage is 100%, so the schema already documents all ten parameters thoroughly, including enum values, examples, and edge-case instructions (conversation_id must be passed unchanged and never invented, llm_model must be 'unknown' rather than guessed). The description adds no parameter meaning beyond what is in the schema, so the baseline 3 is correct and 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 (send feedback to developers) with an unusually clear statement of primary purpose, weights the missing_capability case explicitly, and distinguishes itself from every sibling (all image/video tools) by being the only meta/reporting 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?

Explicitly names when to use it (report missing capability whenever no tool fits, even with a workaround) and enumerates the other cases (failed tool, confusing error, praise, other) with feedback_type values attached. Conditions are attached to categories, so the agent knows which type to pick.

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 (readOnly=false, openWorld=true, idempotent=false): it discloses lossless PNG output, plan quality caps and credit charges, a 45 s wait before falling back to an async job_id handled by get_job, and a required free StockCake account with a host sign-in prompt. That is exactly the operational context an agent needs before committing to a non-idempotent, possibly billed call.

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 tightly packed sentences, front-loaded with the action and scale options, then cost/cap behavior, then async and auth requirements. 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?

For a non-idempotent, credit-consuming, potentially asynchronous tool it covers billing, timing, continuation via get_job and the auth prerequisite, and an output schema exists so return values need no explanation. The only gap is the absence of any routing hint versus resize_image for the agent deciding between them.

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 80%, so the schema already documents image sources, the scale consts, context, llm_model and conversation_id in detail. The description reinforces accepted image sources and the 2x/4x/8x scale values but adds no syntax or semantics the schema lacks, 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) and resource (StockCake or edited image), plus the exact multipliers 2x/4x/8x and lossless PNG output. It does not differentiate from the sibling resize_image, which also transforms image dimensions, so an agent must infer the boundary itself.

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 rather than stated: it tells you the tool upscales existing images and that plan caps/billing apply, but never says when to choose it over resize_image or generate_image, nor what happens if the plan cap blocks the request beyond 'charges credits otherwise'.

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