mcp

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

Annotations already declare readOnly/non-destructive/non-open-world, and the description goes well beyond them: it discloses that completed image jobs return inline image content plus a full-resolution link, that video/music/sound-effect jobs return only a watch/listen link, and that the agent must surface links because chat UIs may not render them. This is high-value behavioral context an agent could not infer 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?

Behaviorally front-loaded: usage trigger first, then id/type semantics, then return handling and polling cadence. It is dense and slightly repetitive with the schema's type/job_id documentation, but nearly every sentence carries operative instruction.

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 explaining return values and does so completely: inline images plus links for image jobs, watch/listen links for the other media, and a bare list of running jobs when no job_id is given. Nothing an agent needs to poll and present results 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 both parameters are already documented, including the enum and the uuid/number heuristics. The description restates the numeric=image / uuid=video / type-required-for-music-and-sound-effect mapping, which is helpful reinforcement but adds little 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?

The description states a specific verb and resource (poll generation job status) and explicitly names the sibling tools it follows (generate_image, generate_video, generate_music, generate_sound_effect). It also differentiates itself from get_generation_history by describing the active-job listing behavior when job_id is omitted.

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 explicit when-to-use guidance ('Use this after calling generate_*'), interim conditions ('Call repeatedly until status is completed or failed'), and concrete polling cadences per media type (~15s for images/sound effects, 15-30s for video/music). No inference is needed.

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

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

With annotations already declaring it as a destructive write operation, the description adds important behavior beyond annotations: cost of 10 credits per post, hourly posting cap, post-publish moderation, NSFW/spam visibility impact, and no refunds for hidden posts.

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

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

The description is front-loaded with the most important constraints: public feed, explicit-request-only, cost, caps, media rules, and return value. It is dense and occasionally repeats schema-level media rules, but nearly every sentence carries 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?

There is no output schema, but the description explains that it returns the public post URL and instructs sharing it. Together with the annotations and rich schema, an agent has enough context on cost, visibility, moderation, and parameter constraints to invoke 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 100%, so the baseline is 3, but the description adds useful cross-tool context for media sources and theme_id lookup. It also restates nested media and audio-field rules already documented in the schema, so it is valuable but partly duplicative.

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: 'Publish a post to the user's PUBLIC BudgetPixel community feed.' It also clarifies public visibility and the 'via MCP' label, distinguishing this tool from generation and upload 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?

It gives explicit when-to-use and when-not-to-use guidance: 'ONLY use this when the user EXPLICITLY asks... never post proactively.' It also names supporting workflows, such as using check_generation_status links or upload_media for media, and list_my_themes for theme_id.

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 flag destructiveHint=true and openWorldHint=true, and the description corroborates and enriches that: each call is an async job that spends BudgetPixel credits, failed jobs aren't charged, the job_id must be polled via a sibling, and results arrive inline for display. That is substantial behavioral context beyond the annotation flags.

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 purpose and the prompt-vs-input_images split are front-loaded in the first sentence, and each subsequent sentence carries a distinct fact (input support, async polling, credit cost, default model). It is dense and somewhat long, with a little redundancy against the schema's own credit/cost prose, keeping it just short of 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?

With no output schema, the description carries the return-value burden and does so: it names job_id, the polling tool, typical latency, and the fact that the finished image is returned inline for display. Combined with the 11-parameter schema and the three annotation flags, an agent has everything needed to invoke and follow through 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 description coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: transparent background requires exactly one input image that is a PNG with existing transparent pixels, aspect_ratio defaults differ for flux-3-image edits, and model defaults vary by capability. These are genuine usage-relevant relationships rather than restated field docs.

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 opens with a specific verb+resource ('create or edit an AI image') and immediately enumerates the two operating modes (text-to-image via prompt, image-to-image/editing/multi-reference via input_images). This cleanly separates it from siblings such as upscale_image, search_stock_images, and generate_video without needing to open 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?

It explicitly routes the agent: use input_images for edits/restyles, omit it for text-to-image, check max_input_images via list_models per model, then call check_generation_status to poll, and call list_models for the full catalog. It also gives a when-to-be-cautious rule ('confirm with the user before choosing 4K') and when-not cases ('cannot make a transparent image from text alone').

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

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

Annotations already declare readOnly=false, openWorld=true, destructive=true, but the description adds substantial context the annotations cannot: it submits an async job returning a numeric job_id, takes 'a minute or three', must be polled via check_generation_status with type "music" every 15–30s, is charged on success only, starts a new paid job each call, and returns a listen/download link that chat cannot embed. This is exactly the extra behavior an agent needs.

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 purpose, but it is one dense wall of text mixing model selection, pricing, video-to-music and async/polling flow, with notable repetition of what the schema param descriptions already state. Given the 10-param, 4-model complexity some length is justified, but structure (bullets/sections) would have improved scannability.

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 high-complexity tool with no output schema, the description covers everything an agent needs: cost model, async submission and polling contract, the exact follow-up tool and cadence, and how to deliver the result to the user. No obvious gap remains for correct invocation.

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

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

Schema description coverage is 100% and the schema already documents model pricing, video constraints, duration billing and per-model parameter applicability in detail; the description largely restates this (model prices, per-second billing, lyrics behavior). It adds cross-parameter interaction (passing a video auto-selects sonilo-video-music), but that is also mirrored in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('create an AI music track') and immediately scopes it (full songs with vocals, or instrumentals), clearly separating it from sibling generators like generate_image, generate_video and generate_sound_effect. The four-model breakdown further pins down exactly what this tool produces.

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 routing rules: which model to pick for songs vs exact lyrics vs instrumental, when to pass a `video` URL for video-to-music (with upload_media as the prerequisite for local files), and when to use the duration-based Sonilo path. It even points to list_models for deeper detail and names the follow-up tool for polling.

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 flag a destructive, paid, open-world write, and the description goes well beyond them: per-second pricing with worked examples, 3-second minimum, charged-on-success-only semantics, async job behavior, expected completion times (~15s text, minutes for video), and the required polling cadence/interaction with check_generation_status. That is exactly the context an agent needs before spending credits.

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 mode split and scoping exclusion, then pricing, then the async/polling workflow. Dense but each clause carries operational weight (cost, timing, routing). Parenthetical pricing examples add length, though they also carry real value.

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, yet the description covers the return contract (numeric job_id, finished link(s), and the caveat that chat can't embed players) plus the polling follow-up with the correct type argument. For a paid async tool with 5 optional params, nothing an agent needs to call and follow up 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 is 3, but the description adds meaning the schema doesn't: the model default-selection logic (sonilo-sfx for text, sonilo-video-sfx auto-selected with video), that duration is billed per second with a 3-second floor, and that duration is ignored in video mode. These are cost-relevant semantics beyond field documentation.

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 (create sound effects) and immediately scopes it with '(NOT music)', explicitly naming the sibling generate_music as the alternative. An agent can distinguish this from generate_music and the other generation tools without opening a schema.

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

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

Gives explicit mode selection rules (TEXT vs VIDEO), the prerequisite for video mode (upload_media first), the routing rule for songs/background music (use generate_music), and operational guidance for long clips ('confirm cost for long videos'). Both when-to-use and when-to-use-something-else are covered.

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 (destructive, non-read-only, open-world) only flag that this is a paid mutation; the description adds the real behavioral substance — per-second billing, charge-on-success-only, async job with a job_id, minute-scale latency, and the polling loop. This is materially more than the structured fields 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-loaded with the modes and the cost warning; every sentence carries actionable content. It is long, and the pricing figures restated in the body overlap with the schema descriptions, but nothing is padded or boilerplate.

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 14-parameter, high-cost, async generation tool with no output schema, the description covers input modes, mutually exclusive combinations, cost, async lifecycle, polling target, and model alternatives. An agent has everything needed to invoke and follow up 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 description coverage is 100% and the per-parameter descriptions are already rich, so the schema carries the bulk of parameter meaning. The description adds defaults (seedance-2.5, 720p) and a worked cost example, but most of its pricing/model detail duplicates the schema. 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 and enumerates the four distinct modes (text-to-video, image-to-video, reference-to-video, video-to-video editing) with the exact parameter that selects each. An agent can distinguish this from generate_image/generate_music/generate_sound_effect 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?

Explicitly routes the agent: use upload_media for local files, call list_models for other models and prices, poll check_generation_status every 15-30s, and confirm expensive combos with the user first. When-to-use, prerequisites and alternatives are all named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. Because there is no output schema, the description's enumeration of returned fields (monthly balance, extra credits, total available, plan name) adds real value beyond the structured data, though it says nothing about auth requirements or account scoping.

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, zero waste: the trigger is front-loaded and the return contents follow. Every clause earns its place.

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

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

For a zero-parameter, read-only tool with no output schema, the description supplies both the invocation trigger and the shape of the response, which is exactly what is missing from the structured fields. Nothing an agent needs 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?

The tool takes zero parameters, which is the baseline-4 case. The description correctly implies a no-argument, context-derived lookup, so nothing further is needed.

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

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

The description names a specific resource (credit balance, extra credits, total available, plan name) and a retrieval verb, and no sibling tool (generation, media, assets, themes) overlaps this billing/account scope, so it is trivially distinguishable.

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?

"Use this when the user asks about their remaining credits, subscription plan, or usage" gives explicit trigger conditions tied to user intent. No alternatives or exclusions are named, but none of the siblings address billing, so the gap is minor.

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

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

Beyond the readOnly/destructive annotations, the description discloses important behaviors: outputs are kept only ~24 hours, never saved to asset storage unless save_to_assets is called, expired rows show with no link, and result links are reusable in other tools. This is rich, non-obvious behavior that an agent needs to know.

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

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

The description is long but every sentence earns its place: purpose, type options, retention behavior, return fields, reuse semantics, and sibling routing. It is front-loaded with the core purpose and then layers necessary details without redundancy.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It does so thoroughly: prompts, models, status, result links, and the variations by type. It also covers expiration, job_id usage, save_to_assets interaction, and the website-gallery exclusion, leaving no major gap for a read-only listing tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantics for the type parameter by explaining the default ('images by default') and what each result-link type enables (e.g., image URLs reusable via generate_image, music/sound-effect links via create_social_post). Limit/offset are not elaborated, but the schema already describes them clearly.

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 opens with a specific verb and resource ('Get the user's recent generations made through this connector or the developer API') and clearly differentiates from siblings by excluding website gallery generations and by noting that each row's job_id works with check_generation_status and save_to_assets. This makes the tool's scope unmistakable.

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 explicitly names related tools and when they apply: job_id can be used with check_generation_status (with the type caveat for music/sound effects) and save_to_assets. It also tells users where to find generations made on the BudgetPixel website ('in their gallery, not here'), providing an explicit when-not-to-use condition.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds substantive context beyond that: featured-first ordering, per-size pricing for image models, per-second-by-resolution video pricing, flat per-track music, and 3-second minimum for sound effects.

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 what is listed, then compactly enumerates the pricing rules by modality. Each pricing sentence carries distinct, non-redundant information; no 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 no input parameters and no output schema, the description carries the full burden of describing the return content, and it does so: categories, ordering, featured hints, and the price model per modality. An agent knows what to expect from the response.

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?

Zero parameters, so the baseline is 4. The description also clarifies that the 'resolution' you pass to generation tools sets the price, which is useful cross-tool semantic context even though this tool takes no input.

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

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

States a specific verb (List) and resource (AI image, video, music, and sound-effect models) with scope: standard credit prices and capabilities. It is clearly distinguishable from siblings like generate_image or get_generation_history, which are action/history tools rather than a catalog.

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: an agent can infer this is the discovery step before calling generate_* tools, and the 'one-line role hint (when to pick each)' helps model selection. However, it never explicitly says when to call this versus alternatives or what prerequisitives exist, so guidance stays implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds useful behavioral context: it is free, it only returns live themes, and it excludes themes that haven't started or have ended. It also discloses the metadata included per theme, which helps the agent understand the result shape before calling. There is no contradiction with 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 description is two sentences, front-loads the scope and returned fields, then gives the exact usage condition and follow-up integration. Every clause earns its place by adding either selection guidance or behavioral detail. There is no filler or repetition.

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

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

For a zero-parameter, read-only list tool with no output schema, the description covers what is listed, what fields come back, when to use it, and how to chain it into create_social_post. Nothing essential for correct invocation is missing. The annotations already cover the safety profile, so the description's added behavioral and output context completes the picture.

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

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

The tool has zero input parameters, so the schema carries no parameter semantics to document. The description appropriately focuses on the output-related value of the chosen theme id for create_social_post, but there are no parameters whose meaning needs further explanation. Baseline for zero-param tools is 4.

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

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

The description states a specific verb and resource: it lists the live clan themes the user can post to, scoped to clans they own, moderate, or have joined. It also specifies exactly what each item contains: the user's role, the theme's brief, and when entries close. This distinguishes it from sibling tools like create_social_post by making it the discovery 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?

It gives explicit usage conditions: use when the user wants to post into a theme, enter a theme, or share to their clan. It also names the follow-up action and parameter: pass the chosen theme's id as create_social_post's theme_id. The exclusion of themes that haven't started or have ended clarifies when results are available.

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?

The description discloses important behavior beyond annotations: outputs expire in ~24 hours by default, saving counts against storage, and calling twice is safe because it 'reports already_saved.' This aligns with the idempotentHint annotation and adds concrete consequences that an agent needs to know before invoking the 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?

The description is front-loaded with the core purpose, then provides context, usage triggers, parameter guidance, and idempotency—all in a compact set of sentences. Every sentence earns its place; there is no filler or redundant restating of the tool name.

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 the tool has three parameters, no output schema, and moderate complexity, the description is complete. It explains why the tool exists (expiring outputs), when to use it, the storage side effect, the idempotent behavior, and the one parameter nuance worth flagging. Nothing essential is missing for an agent to call 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 description coverage is 100%, so the baseline is 3. The description adds a small parameter hint—'Pass the job_id (and type for video / music / sound_effect)'—but this largely repeats the schema's type enum and job_id explanation. No significant extra parameter semantics beyond what the schema already provides.

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 opens with a specific verb and resource: 'Keep a generation permanently' and 'it copies the output into their assets.' It clearly distinguishes this from sibling generation and status-checking tools by explaining the connector's default 24-hour expiration and the act of persisting to assets. No ambiguity about what the tool does.

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 explicitly states when to call it: 'Call this when the user wants to keep, reuse later, or find a result in their gallery / workshops.' It does not explicitly name alternatives or state when not to use it, but the trigger conditions are clear and tied to the tool's purpose, which is a strong guideline.

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 are unusually harsh here (readOnlyHint=false, destructiveHint=true, openWorldHint=false), and the description explains exactly why: every search consumes 10 credits irreversibly, even with zero matches. It further discloses content guarantees (AI-generated, reviewed, no real people/logos/text), the CC BY 4.0 commercial licence, and the obligation to reproduce the returned credit line and download rather than hotlink. This is real behavioral context, not a restatement of the hints.

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 selection condition in the first sentence, then cost, then licence obligations — a sensible priority order for an agent that must decide, call, and then comply. It is long but every sentence carries a distinct, actionable fact with no 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?

With no output schema, the description still names the return fields that matter (attribution, attribution_html, URLs) and explains the post-call obligation attached to them. Cost, content policy, licence, and the no-result fallback are all covered, leaving nothing an agent needs in order to call this 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 100% and five params carry enums, so the structured fields already do the heavy lifting (baseline 3). The description adds value on top: it tells the agent to prefer one specific query over many vague ones, and clarifies the pricing consequence of offset ('Each page is a new 10-credit search') that the schema states only as a bare numeric range.

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 ('Searches BudgetPixel's stock image library') and explicitly contrasts the scope with generation ('rather than a newly generated image'), which cleanly separates it from the generate_image sibling. The opening clause names the user intent (existing stock photo, illustration, background, wallpaper, texture) so an agent can route to it 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?

Gives explicit when-to-use ('the user needs an existing stock photo...') and when-not ('It never generates: if nothing fits, say so'), plus a direct steering instruction to write one specific query instead of many vague ones. It also states the cost condition that governs repeated calls (10 credits per search, charged even when nothing matches).

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?

The description reveals key behavioral details beyond the annotations: the returned URL expires in ~24h, uploads are not charged, files are capped at 50MB, and video/audio uploads are required for generate_video. These are meaningful operational semantics not present in the schema or 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 description is dense but well organized, front-loading the core purpose and immediate usage guidance, then adding constraints and alternatives. Every sentence contributes necessary information without redundancy.

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

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

For a single-parameter upload tool with no output schema, the description covers the input format, size limits, accepted file types, output lifetime, cost implications, and integration with sibling tools. An agent has everything needed to call it correctly and choose it over alternatives.

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 adds extra context by explaining how to obtain the 'file' parameter (read local file) and how the returned URL will be consumed by generate_image/generate_video. This goes beyond the schema's literal parameter description.

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

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

The description clearly states the tool's function: upload a local image, video, or audio file and receive a short-lived URL for generation input. It specifies the resource, the action, and how the result is used, making it distinct from sibling generation tools.

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 says to use when the user has a LOCAL file, and tells the agent to read the file and pass base64. It also gives the alternative: if the user already has a public URL, pass it directly to the generate tool. This provides clear when-to-use and when-not-to-use 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true), the description discloses billing behavior ('Charged on success only'), latency ('results in seconds' vs '~60 seconds'), synchronous behavior ('waits for the result'), the return value ('returns the upscaled image's URL'), and a persistence side effect ('also saved to the user's BudgetPixel library'). That is substantial context an agent cannot get 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?

Purpose and defaults are front-loaded, and the ordering (what it does → models/pricing → input formats → billing → return) is logical. However, the pricing table and model descriptions are duplicated almost verbatim from the schema, adding length without new 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 7-parameter tool with no output schema, the description supplies everything needed: input format options, model choice and cost/latency trade-offs, billing semantics, and the shape of the returned result plus its side effect. Nothing material is left 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 description coverage is 100%, so the schema already documents every parameter, including model trade-offs, target pricing, and clarity-upscaler-only fields. The description largely restates the same pricing and model facts rather than adding syntax or format details beyond the schema, 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 opening sentence states a specific verb and resource ('upscale an image to a higher resolution'), which cleanly separates it from the sibling upscale_video and from generation tools. An agent can identify the tool's function 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?

It gives explicit model-selection guidance: the fast, resolution-priced p-image-upscale default versus clarity-upscaler for 'creative detail enhancement (steer with prompt/creativity)' at a flat 30 credits. It also specifies accepted input forms (URL, upload_media, data URI, base64). It stops short of stating when NOT to upscale or how it relates to 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?

Goes well beyond the annotations (destructive/openWorld/readOnly) by disclosing pricing per input second, that billing happens on success only, the 20s input cap, multi-minute async latency, and that output lands in the user's BudgetPixel library. The polling contract is the key behavioral fact an agent needs and it is spelled out.

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 purpose and pricing, then the async workflow, then storage. Dense and largely waste-free, though the credit table appears in both prose and the target_resolution/target_fps schema descriptions, making it slightly redundant.

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, so the description carries the return-value burden and does: it explains that the call returns a job_id and that a later call returns the finished video URL. With the cost, limits, and async contract covered, nothing an agent needs to invoke 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 already 100%, but the description adds meaning beyond it: the cost-per-second mapping tied to fps and resolution, the worked 10s example, and the mutual-exclusivity rule that job_id is passed alone. It repeats some pricing already in target_resolution's schema text, so not a full 5.

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 ('upscale a video'), names the engine, and enumerates the exact output space (1080p/4K at 30/60fps). An agent can immediately distinguish this from upscale_image and generate_video without opening a schema.

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

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

Explicit routing: pass a URL directly, use upload_media for local files, confirm cost with the user before 4K, and a full polling recipe (call again with just job_id every 30-60s). Names the alternative tool and the condition that selects it.

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