Popcraft

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only what data is returned (credits and plan) and notes that the alternative endpoint is 'coming soon' — useful, but no auth requirements, caching, or return-shape detail.

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

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

Two short sentences, no waste, with the primary purpose front-loaded ahead of the alternative routing. The '(coming soon)' qualifier earns its place by warning the agent that the alternative may not work yet.

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 with no output schema, the description states what comes back (credits and plan), which is the key missing piece. It falls short only on disambiguating from popcraft_show_plans_and_credits, the sibling that appears to answer a near-identical question.

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

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

The tool takes zero parameters, so the schema carries no semantics to supplement and the baseline is 4. The description correctly implies a no-argument, user-scoped read with nothing for the caller to configure.

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: getting the user's available credits and current plan. It is understandable on its own, but it does not address the closest sibling, popcraft_show_plans_and_credits, whose name suggests overlapping 'plan/credits' coverage — an agent cannot tell from the description alone which of the two to prefer.

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 routes transaction-history queries to popcraft_transactions, which is a genuine when-to-use alternative. However, it gives no guidance for the much nearer sibling popcraft_show_plans_and_credits, so usage for the overlapping case is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable context beyond that — the exact return fields and the downstream apply workflow — but says nothing about pagination, result limits, or rate 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?

Front-loads purpose, then the apply workflow, then optional filters. Slightly long but each sentence (purpose, returns, application mapping, filters) earns its place with no 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?

With no output schema, the description compensates by enumerating return fields and fully explaining the downstream application path. Nothing an agent needs to browse and then apply an effect 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 both parameters (query, category) are already documented in the schema. The description restates the filtering behavior without adding syntax or format detail beyond what the schema provides, 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 (Browse) and resource (Popcraft's curated video effects), enumerates what the effects contain (reference video + recipe prompt) and what the tool returns (ids, names, categories, previews, recipe). Clearly distinguishable from siblings like popcraft_show_elements or popcraft_models_explore.

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 apply an effect it names the sibling popcraft_generate_video and spells out the exact model/medias/prompt mapping. It also states the optional filtering conditions (category or query substring), leaving little to inference.

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

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

Annotations cover only the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), leaving the description to add the operational detail, which it does: ~1-3 min runtime, self-refreshing result card, no polling, cost preflight without submission, output format GLB vs FBX under quad, and post-generation refinement path. Strong value beyond 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?

Dense but front-loaded: the verb+resource and mode split come first, then inputs, then defaults, then runtime/polling behavior. Every sentence carries an instruction, though the paragraph runs long and packs defaults, quality tiers, and operational caveats into one block that could be split for 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?

With 15 parameters, no required fields, and no output schema, the burden of explaining returns falls on the description, and it delivers: result is a downloadable GLB (FBX when quad=true), appears on the /model-3d workspace, includes a `project` field to report, and is refinable. Nothing essential to 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 description coverage is already 100%, so the 3 baseline applies; the description still adds real meaning by naming sensible defaults (model_version tripo-v2.5, texture/pbr true, quad false, quality standard), explaining cost/quality tradeoffs for 'detailed' and tripo-p1/turbo, and giving concrete style preset ids. It stops short of covering every parameter (e.g. face_limit, negative_prompt, project_name are left to 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 (generate) and resource (3D mesh/GLB) and explicitly splits the two modes: image-to-3D via image_url and text-to-3D via prompt. It also names the sibling it hands off to (popcraft_postprocess_3d) and the discovery tool (popcraft_models_explore), so an agent can separate it from generate_image, generate_video, and postprocess_3d 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 trigger conditions ('user wants a 3D model, mesh, game asset, printable object, VTuber base'), mode selection rules, preflight guidance (get_cost:true 'always do this the first time'), anti-polling instructions with the job_display fallback, and where to list styles. Alternatives and exclusions are named explicitly.

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 cover readOnly/openWorld/idempotent/destructive; the description adds substantial context beyond them: per-second vs flat billing, speech_rate's effect on billed length, that a voice_id-less TTS call is rejected, non-determinism of seed-audio voice, recovery_tool handling, the self-refreshing result card, and the project-filing side effect. This is a genuine behavioral disclosure well above the annotation floor.

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?

Well front-loaded with the critical routing gate in the first sentence, then organized by kind/model. It is long, but the length is largely justified by 19 parameters, three generation kinds and multiple model-specific branches. A few operational instructions (job_display, no-polling) border on redundant with the result-card note.

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 return-side behavior (result card, `adjustments`, `project`, `recovery_tool`) and model/billing constraints. An agent has everything needed to invoke it correctly and to interpret the result without a 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 coverage is 100%, so baseline is 3. The description exceeds that by explaining cross-parameter interactions the schema cannot: model/voice compatibility (seed vs ElevenLabs voices), that speech_rate/emotion/stability are TTS-only and reported as ignored otherwise, seed-audio's voice_id-or-voice_description auto behavior, and that lyrics overrides prompt for Suno.

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 (generate) + resource (audio) + full scope (voices, sound effects, music) and immediately distinguishes itself from the voiceover workflow via the STOP FIRST gate. An agent can tell it apart from siblings like popcraft_generate_image/video 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 names the alternative (`popcraft_get_workflow_instructions` workflow:"voiceover") and the exact conditions that route there (narration, ad read, multi-line script, robotic voice). It also states the positive case ('One short line, a sound effect or a music bed belongs here — call it directly') and bounds sibling calls (popcraft_job_display at most once, don't poll, use popcraft_list_voices/models_explore).

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: discloses reference validation before charging, get_cost dry-run semantics, that local chat attachments cannot be read and must be uploaded, automatic result-card refresh with a no-polling directive, the recovery_tool convention, and the project-filing side effect. These are behavioral traits the readOnlyHint/openWorldHint/idempotentHint flags 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?

"STOP FIRST" front-loads the most decision-critical routing advice, and nearly every sentence carries actionable content. However it is delivered as one very long, dense block with stacked parentheticals, which costs some parseability versus a more structured layout.

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 9-parameter, high-stakes generation tool with no output schema, it covers everything an agent needs: routing, model selection, cost preview, reference handling, file-upload substitutes, polling avoidance, failure recovery, and where output lands. 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: defaults for aspect_ratio/resolution/count, the pricing-tier constraint on count, that medias must be GCS URLs with role:"reference" for conditioning, and the rationale for get_cost and project_id/project_name fallback. This meaningfully enriches usage over the raw 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 clear verb+resource ("Generate images with Popcraft") and even names the model families it targets (GPT Image 2, Seedream, Nano Banana, Midjourney). It distinguishes itself from siblings by routing thumbnail/ad/UGC work to popcraft_get_workflow_instructions and prompt-guide cases to a named workflow, so an agent can tell exactly when this tool applies.

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 when-to-use and when-NOT-to-use: multi-step branded production goes to the workflow tool, plain/illustration/single-reference work belongs here, and directed jobs on models advertising prompt_guide_workflow must load that workflow first. Names concrete alternatives (popcraft_get_workflow_instructions, popcraft_models_explore, popcraft_media_upload_widget/upload) with the conditions that select them.

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

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

Annotations only declare the generic write/openWorld/non-idempotent profile; the description adds substantial behavioral context the annotations cannot: cost-preview via get_cost, reference validation before charging, Seedance face verification with possible retry-in-5s, combined-duration caps with per-model durationToleranceSec, and the no-polling/recovery_tool contract. Minor deduction because the density of edge-case rules makes it hard to extract the safety-critical items at a glance.

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 highest-priority routing rule is correctly front-loaded, and most content is substantive. However, it runs to many dense sentences with repeated cross-references to popcraft_models_explore and nested caveats (duration tolerance, face verification, workflow routing) that could be compressed; it is bloated relative to what an agent needs to act.

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 13-parameter, open-world, non-idempotent generation tool with no output schema, the description covers routing, cost, media roles, validation, model-specific constraints, and result-card polling behavior. Nothing an agent needs in order to call 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 coverage is 100%, so the baseline is 3, but the description meaningfully extends the schema: seeded defaults (9:16, 5s, count tiers), media role semantics tied to model capabilities, reference_prompt_tokens numbering rules, and the video/audio separate-budget interaction. This is real semantic value beyond the field descriptions.

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

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

Opens with a specific verb+resource ('Generate video with Popcraft — Seedance 2.0, Veo, Kling and more — from a text prompt, optionally driven by reference images/video/audio') and explicitly distinguishes itself from the workflow sibling. An agent can tell exactly what this tool produces versus popcraft_get_workflow_instructions 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 when-to-use (plain clip, animating one image, single reference-driven shot), when-NOT (UGC/branded multi-step productions → popcraft_get_workflow_instructions; directed jobs on prompt_guide_workflow models → h3-prompting) and names the alternatives. Routing conditions are unambiguous and front-loaded.

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 openWorldHint=false, so the safety profile is covered. The description adds genuine operational context beyond that: the argument provenance (paths must come from popcraft_get_workflow_instructions) and the gating condition. It does not describe error behavior for invalid paths, which keeps it short of 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?

Three tight sentences, front-loaded with verb+resource, followed by the gating rule and a concrete call example. The trailing API docs URL is mildly extraneous but plausibly useful, keeping it just under a perfect score.

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 two-parameter, fully-documented, annotation-covered read tool with no output schema, the description supplies purpose, provenance, gating, and an example. What a reference file returns is not spelled out, but that gap is minor given the richness of the surrounding structured data.

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 both parameter descriptions already carry format and examples ('references/board-design.md', 'ugc-ad'). The description's inline example largely repeats that, adding little beyond the schema, so 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 and resource (read one bundled reference file from a Popcraft workflow) and immediately ties it to the sibling popcraft_get_workflow_instructions as the source of paths. An agent can distinguish this from the workflow-instructions and generation tools 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 states when to call it ('when the loaded workflow instructions tell you to load a reference module') and names the alternative/source tool that supplies the arguments. The condition that selects this tool is unambiguous.

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/closed-world, so safety is covered; the description adds genuinely new behavioral context beyond them — the two call modes (no-arg = catalog list, with-arg = full instructions plus a reference-file list readable via popcraft_get_workflow_bundle_file) and the sequencing/ownership contract ('the workflow owns the production recipe — model choices, reference discipline, credit-cost preview, and QA'). It stops short of describing output format, but the load-first contract is the key trait.

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 mechanics (list vs. load) before the routing rules, which is good. However, the second half is one sprawling multi-clause sentence enumerating scenarios and a long H3 clause; nearly every clause routes a real scenario, but the density and run-on structure hurt scannability, so it is efficient in content yet poor in form.

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

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

Covers both invocation modes, the companion tool for reference files, the precedence relative to generation tools, and the ownership of the production recipe. For a single-parameter guidance tool with no output schema, nothing an agent needs to call 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 coverage is 100% and the single `workflow` param is already fully described in the schema (name from catalog, omit to list). The description's parallel explanation ('Call with { workflow } to load...') adds corroboration and links the parameter to its effect, but no new syntax or constraint beyond the schema. 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 ('Discover and load Popcraft's multi-step production workflows') and immediately defines what a workflow is ('a bundled instruction set that orchestrates the popcraft_* tools into a finished deliverable'). It is clearly distinguishable from the popcraft_generate_* siblings it directs the agent away from.

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 conditions (UGC ad, vertical TikTok/Reels ad, thumbnail/cover, voiceover, Hailuo 3 non-trivial jobs), names the alternatives it takes precedence over (popcraft_generate_image/video/audio directly), and even cites the specific failure trigger ('voice came back sounding robotic, flat or rushed'). The precedence rule 'load BEFORE calling...' is unambiguous.

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 readOnlyHint/openWorldHint, but the description adds real behavioral context: the three return states (in_progress/completed with result URLs/failed with error), the instruction to render URLs, and the auto-refresh/no-polling constraint. This is well beyond what the structured fields provide.

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 purpose, then return states, then usage rules; every sentence earns its place. Slightly dense in the parenthetical fallback guidance, but 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?

No output schema exists, so the description carries the return-value burden and does so fully by enumerating the three states and their payloads. Combined with the polling constraints, an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100% and there is a single parameter, so the schema already documents job_id. The description only restates its provenance, adding no syntax or format detail beyond what the schema says. 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 ('Check the status of a Popcraft job') and ties the job_id origin to the generate tools and popcraft_show_generations. However, it never differentiates itself from the near-identical sibling `popcraft_job_status`, leaving an agent unsure which of the two status tools to pick.

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 when-to-use (user asks about a job; plain-text fallback in clients that don't render cards), explicit when-not (do NOT loop; call at most once per job), and it even tells you how to behave in the fallback case. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious context the annotations cannot convey: the caller is the widget's own result card, not the agent, and repeated polling is an anti-pattern. It stops short of describing return payload or refresh cadence, so not a full 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 short sentences, front-loaded with the identity of the tool and immediately followed by the routing instruction and the anti-pattern. 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?

Although there is no output schema, the description gives the agent everything it needs for the actual decision here: this tool is not for the agent, and popcraft_job_display is the correct substitute. No behavioral or routing information 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% with a single documented job_id parameter, so the schema already carries the semantics. The description adds no format, source, or naming detail beyond it; 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 ('job status poll') and scopes it precisely as 'widget-internal', which immediately separates it from the agent-facing siblings. It also names popcraft_job_display as the tool to use instead, so the agent can route 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?

Explicit when-not guidance: 'Do not call it yourself', plus the named alternative (popcraft_job_display) and a concrete prohibition ('never poll in a loop'). Nothing about usage is left to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds real behavior the agent could not infer — an interactive picker appears in widget-capable clients and the chosen voice_id returns as the next user message, whereas text-only clients must relay the list with preview links. It also discloses the provider/model compatibility constraint, which prevents a wrong downstream 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?

Dense but well front-loaded: purpose and provider semantics come first, widget/text-client behavior and the voice_id handoff follow. Every sentence carries information, though the passage runs long for a list tool and could be tightened.

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 covers the return shape relevant to the agent (list carries preview links) and the widget handoff path for voice_id. Combined with annotations covering the safety profile, nothing needed to invoke or route this tool 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 goes further by explaining provider semantics (a voice only works on its own provider's models), the seed-tts vs seed-audio distinction, and that gender/language/limit are optional filters. It adds genuine meaning beyond the schema, though it does not extend the schema's filter syntax examples.

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

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

States a specific verb and resource (list TTS voices for popcraft_generate_audio), and immediately scopes it with the kind:"tts" constraint and provider split, which no sibling tool covers. An agent can distinguish this from popcraft_models_explore or popcraft_generate_audio 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 names the consumer tool (pass voice_id to popcraft_generate_audio), gives an exclusion (model:"seed-audio" needs no voice), and adds a temporal rule ('call once per voice-selection conversation — do not re-list unless the user asks for different filters'). This is when/when-not guidance in the strongest form.

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 structurally. The description adds real context: that the check verifies the object exists and is non-empty in GCS. It does not say what happens on failure (error vs. false return), leaving one behavioral 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?

Two tight sentences with zero filler, front-loading the action and its timing constraint. 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?

There is no output schema, so the description carries some burden for the return behavior; it states what is checked (existence and non-emptiness) but not how success/failure surfaces to the caller. For a one-parameter verification tool this is nearly complete, with only the result semantics left implicit.

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 single media_id parameter is already fully documented by the schema ('returned by popcraft_media_upload'). The description reinforces the upload linkage but adds no syntax or format detail beyond 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 (verify/confirm) and resource (a file PUT to a popcraft_media_upload upload_url landing in GCS). It ties itself to the exact sibling that produces the input (popcraft_media_upload) and names the artifact involved (media_id), so an agent can distinguish it from the surrounding media 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 states the condition under which to use it: after a PUT to upload_url and 'before using its media_id elsewhere.' This gives clear context but does not name a when-not or any alternative verification path, so it falls short of the 5 threshold.

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 context beyond annotations: idempotent pass-through of already-issued media_ids, re-hosting of arbitrary URLs, and SSRF blocking of private/internal addresses. Annotations cover the safety profile, and the description enriches it with real operational 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?

Purpose and return value are front-loaded, and most sentences earn their place by conveying routing or behavioral detail. It is dense and slightly long, with a trailing docs URL that is marginally extraneous.

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 two-param import tool with no output schema, the description fully explains the return (a stable media_id / GCS https URL) and its downstream usage, leaving nothing an agent needs 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 schema already documents both parameters (baseline 3). The description adds meaning by clarifying pass-through semantics for gs:// URLs and how the returned media_id is consumed downstream.

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 (mirror a web media URL into Popcraft-owned GCS storage) plus the return value (media_id). Clearly distinguishes itself from the upload/upload_inline siblings by focusing on externally-hosted URLs.

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 states when to use it ('whenever a generation needs to reference media that lives outside Popcraft') with concrete examples, and names the alternative condition ('If the media is a LOCAL file with no public URL, use popcraft_media_upload_inline instead'). Routing to siblings is fully specified.

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 (readOnlyHint=false, idempotentHint=false, openWorldHint=false) only mark this as a non-read, non-idempotent write; the description adds substantial context the annotations cannot: per-type size caps, a 28 MB transport request cap, the two distinct upload hosts, a caution that platform-mediated clients may not have reachable egress, and the required follow-up confirm step.

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 and the video/20 MB trigger before any of the branching fallbacks. It is long and ALL-CAPS-heavy, but the length is driven by real branch complexity (two hosts, chunked recipe, egress probe, three fallbacks), so most sentences earn their 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?

Despite no output schema, it names the return values (proxy_upload_url, upload_url, media_id), explains how to use each, and closes the loop through popcraft_media_confirm and medias[].value for the generate tools. An agent has everything needed to call it and act on the result.

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 a semantic not in the schema: the 28 MB per-request transport cap that forces chunked uploads above it, which directly affects how size_bytes should be interpreted. It otherwise largely restates the caps already documented per-parameter.

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 upload URLs for a local file that has no public URL) and explicitly names the siblings it is not (popcraft_media_import_url, popcraft_media_upload_inline, popcraft_media_upload_widget). An agent can pick it apart from its nearest neighbors 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 when-to-use conditions (local file with no public URL, video, files over 20 MB), when-not (import_url when a shareable link exists, inline only for small files, widget when client renders widgets), plus an egress-probe prerequisite and a fallback chain. Nothing is left to inference.

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

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

Annotations only state the mutation/idempotency profile; the description adds real behavioral context the annotations cannot convey: the bytes travel over MCP so no host/shell access is needed, the return `media_id` is immediately usable with no `popcraft_media_confirm` step, truncated payloads are rejected, and there is a practical ceiling (a few hundred KB) versus a hard 20 MB limit.

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 core action and the returned `media_id`, then sequences mechanics, the video exclusion, and the redirect to the shell-based alternative. Despite its length, every sentence carries a distinct decision-relevant fact.

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 explains the return value (`media_id` ready immediately, passable as `medias[].value` to the generate tools) and covers limits, integrity verification, and the fallback path. Nothing needed to call 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%, and the schema already documents base64 format, the `data:` URI alternative, sha256 verification, cosmetic filename, and the accepted MIME list, so the description's per-parameter contribution is minimal. The throughput/limit guidance is capacity-oriented rather than parameter syntax, so the baseline 3 holds.

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

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

States a specific verb and resource ('Upload a SMALL local file ... by sending its bytes as base64 in this call') and explicitly differentiates scope (small inline files) from the sibling `popcraft_media_upload` used for larger/video data. An agent can identify this tool's niche without opening another 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 (icons, thumbnails, screenshots, short audio), when-not-to-use ('NOT FOR VIDEO', any file you would not type out in full), and names the concrete alternative (`popcraft_media_upload` plus its shell recipes). The routing decision is fully specified.

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 declare only the safety profile (not read-only, not destructive, not idempotent); the description goes well beyond by explaining that uploads run from the user's browser, work even when shell egress is blocked, and that the tool drives signed URL/PUT/confirm end-to-end. It also discloses the unusual return path: the `media_id` comes back as the next user message.

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 is front-loaded in the first clause and the routing guidance follows logically. It is on the long side with several clauses packed together, but each sentence carries distinct information (routing, alternative, behavioral notes, parameter advice).

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 widget-based upload tool with no output schema, the description covers everything an agent needs: when to use it, the zero-click alternative, egress/rendering constraints, and how the resulting media_id is delivered and consumed downstream.

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 usage guidance beyond the schema: restrict via `type` and pass a specific `label` naming the exact file expected, which clarifies intent rather than just repeating the 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?

States a specific verb and resource ('open an interactive file-picker widget for the user to upload an image/video/audio file') and explicitly distinguishes itself from sibling `popcraft_media_upload` and `popcraft_media_import_url`. An agent can route correctly without opening any schema.

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

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

Gives explicit selection conditions: use this instead of `popcraft_media_upload` when the client renders MCP Apps widgets or when the shell's egress is blocked. It also names the zero-click alternative (`popcraft_media_import_url`) and the condition that selects it (file exists online), plus a pre-open check.

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 readOnlyHint=true and openWorldHint=false, yet the description adds substantial behavioral context the agent could not otherwise know: the per_second billing RATE semantics, the real_person_verification auto-verification step for Seedance 2.0, and plan-based requires_upgrade annotation of recommended rows.

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?

Dense but well front-loaded: the model list and row-shape fields come first, followed by the critical cost warning and per-action semantics. The CAPS emphasis (HEED, NEVER) is loud but functional for an agent; length is justified by real payload, though a browse tool carries more prose than strictly necessary.

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 full burden of explaining return values and does so thoroughly — reference_limits, modes, credit_cost_unit, per-model reference-input envelopes, and plan annotations. Nothing an agent needs to call or interpret this tool 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 beyond the schema — how type and query combine for filtering, what action:'get' returns (input modalities, aspect ratios, reference envelope), and the practical 'prefer rows without requires_upgrade' guidance.

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 ('Browse Popcraft AI models') and immediately names the concrete catalog contents (GPT Image 2, Seedream, Nano Banana, etc.). It is unmistakably the catalog-browsing tool, clearly separable from the generate_* and show_* 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 routing: 'Consult these BEFORE attaching medias', 'Unsure which model to use? Call recommend first', and the critical directive to call the matching generate tool with get_cost:true rather than quoting creditCost. Alternatives and preconditions are named, not 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 only mark it non-readonly/non-idempotent; the description adds that refine/stylize/completion/lowpoly are variable-cost and reconcile to Tripo's usage, that the result card self-refreshes, that output is a new lineage-linked asset, and a communication constraint about never quoting generation time. Far beyond the annotation set.

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 dense single paragraph that is front-loaded with purpose and operation meanings, followed by source, params, cost, polling, and output notes. Nearly every clause earns its place, though it is long enough that some operation detail could be trimmed.

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 explains the return (an interactive result card plus a downloadable new 3D asset), cost semantics, filing behavior, and polling behavior. An agent has everything needed 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 real meaning: concrete per-op param examples (fbx_preset 'blender', style/block_size), the fact that params can be omitted for defaults, and precise source/project_id/project_name filing behavior.

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 ('Run a Tripo3D post-process on an existing Popcraft 3D model') and enumerates all seven operations with what each does. It clearly distinguishes itself from siblings like popcraft_generate_3d (which produces the source) and popcraft_upscale_image/video.

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

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

Explicit when-to-use per operation (e.g., convert_model is 'the cheap way to get a Blender-friendly FBX'), an explicit when-NOT constraint ('only Tripo-generated models can be post-processed'), a preflight path (get_cost:true), and a polling rule ('do NOT poll; call popcraft_job_display at most once').

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 mark this as non-readOnly/non-destructive/non-idempotent, which is ambiguous for a dual list/create tool; the description resolves that by stating list is the default read and create is the mutating branch that returns a project_id. It further discloses auto-filing behavior and that a missing project_name is silently created — real behavioral context beyond 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 action semantics are front-loaded and every clause carries information (returned fields, filing behavior, cross-tool routing). It runs long in a single dense block, but no sentence is filler and the ordering follows the agent's decision sequence.

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: list returns id, title, asset count and the active project; create returns project_id. Nothing critical 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 description coverage is 100%, with both the action enum and the title requirement already documented in the schema. The description restates the create/title dependency rather than adding format or validation detail, so 3 is the appropriate baseline 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 concrete verb pair and resource ('List or create the user's Popcraft projects — the folders their generations are organized into'), and the gloss clarifies the entity precisely against siblings like popcraft_show_generations and popcraft_show_medias. An agent can tell what this tool owns 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?

Ends with explicit routing ('Use this tool when the user asks to see, organize into, or start a new project') and names the downstream alternatives (popcraft_generate_image/video/audio) plus the condition that selects them. It also documents the fallback that a non-existent project_name is auto-created, removing a common inference gap.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds non-obvious behavior the annotations cannot convey: in widget-capable clients an interactive grid renders and a picked element arrives as the next user message. It stops short of describing pagination or the full element payload shape.

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 is front-loaded in the first clause, followed by the highest-value instruction (how to actually use an element in a generation). The middle how-to-use block is dense but earns its place by linking to sibling tools; the widget note at the end is slightly tangential but short.

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 burden and does describe elements as backed by a reference image with an image_url, plus the widget-pick return path. It is nearly complete for a 3-param, read-only browse tool, though pagination and the full field list are left implicit.

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 restates the type values and the substring-search semantics that the schema already documents, and never mentions limit or its 1-50/default-24 bounds. It adds usage framing but little parameter meaning 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 (Browse) and resource (reusable Popcraft Elements: saved characters, objects, backgrounds, styles, each backed by a reference image), which cleanly separates it from siblings like popcraft_show_medias and popcraft_show_generations. An agent knows exactly what this returns 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?

Explicit trigger: 'Call it when the user asks about their elements/characters or wants consistent subjects across generations.' It also names the downstream alternatives (popcraft_generate_image, popcraft_generate_video) and the exact role values to use with each, so the agent knows both when to call this and what to do with the result.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value beyond that: it discloses that each item carries its full original params (model, aspect_ratio, prompt, credits) and result URLs, and explains the reuse path via medias[].value in a popcraft_generate_* call. It does not mention pagination behavior or result-count limits beyond the cap, which keeps it short of 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?

Purpose and scope are front-loaded in the first sentence, followed by filtering, the reuse workflow, and the routing guidance. It is a dense paragraph with no filler, though it is long enough that the polling caveat and the job_display pointer could be tightened into one sentence.

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 return-shape burden and does so by describing item contents (original params and result URLs) and ordering. Combined with the usage routing and annotation-covered safety profile, an agent has everything needed 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 schema already documents both parameters, including the enum and the 1-50 range. The description's restatement of type filtering and the limit default/max adds no syntax or semantics beyond the structured fields, 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 ('List the current user's recent Popcraft generation jobs'), the resource subtypes (image/video/audio), and the ordering ('most recent first'). It also implicitly distinguishes itself from popcraft_job_display and popcraft_job_status by describing the history-browsing scope rather than live status.

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

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

Gives concrete use cases ('find a job_id from an earlier session', 'show the user their generation history'), an explicit negative ('do NOT call it repeatedly as a post-generation poll step'), and names the sibling to use instead for live status ('popcraft_job_display'). This is exactly the when/when-not/alternative pattern.

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 readOnlyHint/openWorldHint; the description adds ordering (most recent first), scope exclusion (personal library only, no workspace/shared assets), and the behavioral trait that each item carries a reusable url. This cross-tool reuse semantic is context the structured fields do not provide.

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, then filters, then the high-value reuse tip, then sibling differentiation — each sentence earns its place. It is dense and runs long for a single paragraph, but there is 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?

For a read-only filtered-list tool with no output schema, the description covers scope, ordering, filters, pagination, and even the practical downstream use of the returned url. Combined with readOnly annotations, an agent has everything needed 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 reinforces the defaults (limit default 20, max 50) and clarifies source semantics. It goes beyond the schema by explaining what the returned url field enables, though the four input parameters themselves are already fully documented in the schema.

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

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

States a specific verb and resource ('browse the current user's saved Popcraft media library') plus scope details (uploaded/imported vs generated outputs, sorted most recent first). It also explicitly contrasts itself with the sibling 'popcraft_show_generations' (job history vs persisted asset library), so an agent can disambiguate 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 explicit when-to-use ('find media the user already has rather than asking them to re-upload') and when-to-use-the-other ('For the history of generation JOBS ... use popcraft_show_generations'). It also documents the filter conditions (type/source) and pagination controls, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds critical behavioral context the annotations cannot carry: the output is ready-made user-facing copy with Markdown links that must be relayed verbatim, with explicit prohibitions on summarizing, reordering, or dropping links. That is exactly the kind of non-obvious trait 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?

It is a dense single block, but it is front-loaded with the core purpose and every clause earns its place (trigger conditions, intent semantics, relay instructions). Slightly long, though nothing is redundant with structured fields.

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 burden of describing the return value — and it does ('ready-made, user-facing copy whose Markdown links point at the exact purchase pages'), plus how to present it. For a zero-required-param read tool this is fully sufficient.

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 the enum values are already documented, so the baseline is 3. The description adds value by explaining the consequence of each intent — topup/upgrade change how the response is 'ordered for that purchase path' — which the schema only hints at.

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 ('Show the user their current credit balance and plan') and immediately scopes it beyond a bare balance call by adding 'live plan/credit-pack pricing and direct purchase links'. This lets an agent distinguish it from siblings like popcraft_balance or popcraft_transactions without opening their schemas.

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 triggers: 'use this as the recovery step after a `popcraft_generate_*` call fails with insufficient credits, or whenever the user asks about pricing/plans/credits.' It further routes between parameter choices (topup for out-of-credits, upgrade for model-locked). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds useful behavioral detail beyond that: newest-first ordering and the set of transaction types returned. It does not discuss pagination or the maximum result window (limit cap of 50), which is the only notable omission.

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: purpose and ordering first, then the disambiguating alternatives. Every clause earns its place and nothing is repeated from the schema or annotations.

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

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

For a simple read-only listing with no output schema, the description supplies scope, ordering, and transaction categories, which is nearly everything an agent needs. It stops short of describing the per-transaction fields (amount, timestamp, source) an agent might present to a user.

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 on the single `limit` parameter, the schema already carries the semantics (1-50, default 10). The description adds nothing about result count or truncation, so the baseline of 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 and resource ('List the user's recent credit transactions') and enumerates the transaction kinds (spend/refund/grant) plus ordering. It explicitly names the sibling tools that cover adjacent needs, so an agent can distinguish it without opening any schema.

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

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

Gives explicit triggers ('where their credits went', 'spending history', 'verify a charge/refund') and routes the alternative cases to `popcraft_balance` for current balance and `popcraft_show_plans_and_credits` for plans/top-ups. 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?

Despite annotations covering safety, the description adds substantial behavioral context: cost model (~1.2x a straight 1080p render, billed on top of the draft), a 7-day validity window with refusal after expiry, idempotent double-call behavior that charges nothing the second time, and a no-polling contract. These go well beyond idempotentHint/openWorldHint.

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 core action in the first clause, then layers billing, validity, idempotency, and polling rules. It is long but every sentence is actionable and nothing is redundant filler, which is appropriate given the billing and workflow complexity.

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 return behavior (interactive self-refreshing result card), error/expiry behavior (7-day refusal), and side effects (charges, no re-roll). An agent has everything needed to call this correctly and to instruct the user.

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 both parameters (generation_id, get_cost) are already fully documented in the schema, including the get_cost non-submitting semantics. The description restates the generation_id source and the quote-without-submitting behavior but adds no syntax, format, or edge-case detail beyond 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 and resource ('Render the 1080p final from a ... DRAFT') and pins its scope as 'the second and last step of draft mode.' It implicitly distinguishes itself from popcraft_generate_video and popcraft_upscale_video by naming the draft workflow, and explicitly says it does NOT re-roll the clip.

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

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

Gives an explicit precondition ('only take this step once the user has SEEN and approved the preview'), an explicit alternative for progress checks ('call popcraft_job_display at most once, and only if no card rendered'), and a when-not (never quote generation time). Routing is unambiguous.

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: pricing is measured from the real file so width/height hints don't affect cost, the tool ignores prompt/count, get_cost preflights without submitting, a result card self-refreshes so the agent must not poll, and the result carries the target project. It also handles the async flow explicitly ('call popcraft_job_display at most once if no card is visible') and forbids quoting generation-time estimates, 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?

Dense but front-loaded: purpose and trigger come first, then parameter guidance, then pricing, then async/polling rules. Nearly every sentence carries operational weight, though the mode enumeration and the polling/result-card instructions make it long enough that the paragraph could be segmented for faster scanning.

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 an 8-parameter, async job tool with no output schema, it covers a lot an agent needs: input source, pricing semantics, preflight flag, project filing, and the result-card lifecycle. It is not fully complete because one third of the mode enum values are unexplained, and the mode description in the schema points back to a description that never defines 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 100%, so baseline is 3, but the description genuinely adds meaning: it maps modes to content types (faces, degraded portraits, illustrations/logos, 3D renders, screenshots/documents, re-imagine) and explains that width/height are advisory hints that do not affect cost. It is docked one point because the schema enum exposes nine modes (high-fidelity-mode, low-res-mode, standard-max are absent) while the description only explains six, leaving a gap that the schema's own text delegates back to the description.

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

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

States a specific verb + resource + scope: 'Upscale and enhance an existing image to 2x or 4x with Topaz.' The image resource immediately separates it from the sibling popcraft_upscale_video and popcraft_upgrade_video, and the 2x/4x constraint tells the agent what the tool can and cannot produce.

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

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

Gives an explicit trigger ('use when the user asks to upscale, enhance, sharpen, or increase the resolution of an image') and an operational precondition ('pass the source image as a GCS URL ... from a prior generation result or popcraft_media_import_url'). It does not explicitly name the image-vs-video alternative or state when NOT to use it, 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?

Goes well beyond the annotations by disclosing cost behavior (fps above 30 roughly doubles cost), the get_cost preflight pattern, that no prompt/count is used, that the result card auto-refreshes so polling is forbidden, and project-filing consequences. This is rich operational context an agent cannot get from readOnlyHint/idempotentHint alone.

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 purpose, then layers cost, mode, and result-handling guidance efficiently. It is dense and lengthy, but nearly every sentence carries actionable information; minor trimming of the card/polling advice could tighten it further.

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?

Despite no output schema, the description explains what the result contains (interactive card, `project` value) and how to handle it, plus cost and routing behavior. An agent has everything needed to invoke and follow up correctly on this 10-parameter mutation 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% (baseline 3), and the description adds real meaning beyond it: width/height/duration are non-authoritative hints that do not affect pricing because the server measures the file, plus glosses for the Topaz mode values. It stops short of full per-parameter documentation but meaningfully enriches the enum and hint semantics.

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 ('Upscale and enhance an existing video to 2x or 4x with Topaz'), naming the engine and factors. It is clearly distinguishable from siblings like popcraft_upscale_image and popcraft_upgrade_video without opening their schemas.

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 explicit trigger conditions ('use when the user asks to upscale, enhance, sharpen, denoise, or convert...'), mode-selection guidance, and a get_cost preflight workflow. It does not explicitly contrast against the sibling popcraft_upgrade_video or upscale_image, but the when-to-use context is strong.

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