Create, animate and export mascots from your coding agent, as Lottie, SVG or transparent clips.
Scored across 21 tools
The tools mostly target distinct resources and actions, and descriptions explicitly cross-reference alternatives such as add_prop vs set_props vs edit_mascot, and animate_mascot vs create_clip. A few boundaries still require reading carefully because motion addition splits by mascot type, and appearance changes span add_prop, edit_mascot, recolor_mascot, and switch_look.
All names use snake_case verb_noun patterns with consistent prefixes such as create_, list_, get_, export_, and set_. Minor noun phrases like set_clip_kind and get_embed_code remain predictable and readable.
21 tools falls in the heavy 16–25 range for an agent-facing server, even though the domain is broad and many tools serve distinct mascot types or workflows. Consolidating some appearance, export, and job operations could make the set easier to navigate.
The surface covers creation, retrieval, editing, animation, props/looks, scenes, canvas, export, embedding, and job waiting. The main lifecycle gap is deletion: there is no delete_mascot or delete_clip, and there is no explicit way to list all animations for rigged mascots.
Draw something the mascot holds or wears as a part of its own ('a small frying pan in the right paw', 'a golden crown'), shown, so it can be switched off later with set_props and the mascot is as it was. A paid edit; every animation keeps working.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | No | Short label, e.g. 'Crown' (made from the description when left out) | |
| description | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose two genuinely useful traits: the operation costs money ('A paid edit') and it is non-destructive to animation ('every animation keeps working'), plus reversibility via set_props. It does not say whether the result is immediate or a queued job (siblings list_jobs/wait_for_job suggest async work), nor what is returned or what permission level is required.
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 essentially one dense sentence plus a short cost note, front-loading the core action and examples before the set_props caveat. The clause 'shown, so it can be switched off later with set_props and the mascot is as it was' is grammatically tangled and costs readability.
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 three-parameter, annotation-free mutation with no output schema, the description covers cost, reversibility, and expected input style, which is reasonable. It still leaves the required id field undefined and does not say whether the edit is synchronous or returns a job handle, which matters given the list_jobs/wait_for_job siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, so the description must compensate. The quoted phrases ('a small frying pan in the right paw', 'a golden crown') usefully illustrate the style expected for the required description parameter, but the required id parameter is unexplained in both schema and description, and there is no guidance on the 300-character limit or how name is derived.
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 concrete verb and resource: draw a prop the mascot holds or wears as part of itself, with two illustrative examples ('a small frying pan in the right paw', 'a golden crown'). It also implicitly separates itself from set_props, the tool that removes the prop, so an agent can place it among its siblings, though the wording of that relationship ('shown, so it can be switched off later') is slightly muddled.
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 prescribed: the agent learns to call it when adding a held/worn item and that set_props later removes it. There is no explicit statement of when not to use it, no prerequisite checks (e.g. mascot existence or plan/credit availability) beyond the passing note that it is 'a paid edit'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads a website and proposes three mascot concepts that fit the brand (each with a ready-to-use prompt and style for create_mascot).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and network access are covered upstream. The description adds valuable behavioral detail that the annotations do not carry: it returns exactly three concepts, each with a prompt and a style. It says nothing about fetch failures, page depth, latency, or whether the site content is cached, which is where remaining risk lies for an open-world read.
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?
One front-loaded sentence that states the action, the exact output cardinality, and the downstream consumer, with no filler. 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 one-parameter read-only tool with no output schema, the description covers what it does, what it returns (three concepts with prompts and styles), and how the result is used next. It leaves minor gaps only around input expectations and failure behavior.
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 0%, so the single url parameter is documented nowhere but implicitly by 'reads a website'. The description conveys that the value is a site address but not the expected form (absolute URI with scheme, homepage vs. deep link), leaving format details to the schema's bare format: uri constraint.
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 uses specific verbs (reads, proposes) and a concrete output (three mascot concepts tied to the brand), and it names the downstream sibling create_mascot that consumes the result. An agent can distinguish this idea-generation step from create_mascot or edit_mascot 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?
It makes the workflow context explicit: run this before create_mascot to get prompts and styles, which is a clear when-to-use signal. It stops short of naming exclusions or alternatives (e.g., when to skip website analysis and call create_mascot directly), so it does not reach a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add an animation. Use preset for instant, free motions (idle, wave, nod, shake, bounce, celebrate, jump, talk, sad, surprised, dance, think, working, listen, sleep, fly, walk), prompt to describe any custom motion ('does a little moonwalk then waves'; takes ~30–90s), or a reference video (video_url) for the mascot to perform.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| arm | No | Wave preset: which arm waves, from the viewer's side; both waves both arms | |
| name | No | ||
| preset | No | ||
| prompt | No | ||
| duration | No | Seconds | |
| intensity | No | Presets: 0.5 subtle, 1 normal, 1.5 big | |
| video_url | No | MP4/MOV/WebM of someone (or something) performing the motion |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full behavioral burden, and it does disclose valuable non-schema traits: presets are "instant, free" while prompt generation takes ~30–90s and is presumably metered. However, it never says whether the added animation replaces or appends to existing animation, whether the call is synchronous or returns a job to poll (relevant given the wait_for_job and list_jobs siblings), or what a failed generation does to 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?
A single dense sentence, front-loaded with the action and then enumerating the three modes with their tradeoffs. It is efficient and scannable. The one waste is listing all 17 preset values inline, which is a pure duplication of the schema enum and consumes most of the character budget.
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 mutation tool with no annotations and no output schema, the description leaves important gaps: no mention of the return value or whether a job must be polled, no explanation of `id` vs `name`, and no statement about how a new animation composes with existing ones. The three-mode framing is the essential part and it is present, so this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, and the description mostly mirrors what the schema already encodes: the preset enum is repeated verbatim, adding no meaning beyond the enum itself. It does add real value for `prompt` via the worked example and latency note, and frames video_url as a performance reference. It says nothing about `id` (presumably the mascot to animate) or `name`, leaving two parameters undocumented in both places.
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 ("Add an animation") and immediately splits the tool into its three input modes: preset, prompt, and video_url reference. An agent can tell what the tool produces without reading the schema. It stops short of naming a sibling (e.g. suggest_animations) as the alternative path, so the differentiation is implicit rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear routing among the three mutually exclusive input modes: presets for instant/free canned motions, prompt for custom motion at a stated cost (~30–90s), video_url for performance reference. That is genuine when-to-use guidance for selecting parameters, which is the main decision this tool requires. It omits guidance on when to call suggest_animations first, and never states that only one of preset/prompt/video_url should be supplied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a state machine that drives the mascot from app events. Templates: chatbot (inputs listening/thinking/talking booleans + greet trigger), ai_agent (status number: 0 idle, 1 working, 2 waiting, 3 done, 4 failed), onboarding (hello/success/error triggers). Or pass a custom graph. Works on clip mascots too: states play its clips (a template's working → think, listen → idle); if the canvas plays clips the character doesn't have, the error names them, make them with create_clip (60 credits each) and try again.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | Yes | ||
| graph | No | ||
| template | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full load, and it does disclose real behavior: how template states map to clips on clip mascots (working to think, listen to idle), that a validation error names missing clips, and the cost (60 credits) of the remediation tool. It does not say whether creation is idempotent, what happens if the id already exists, or what the call returns, which leaves meaningful gaps for a creation 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?
Dense but purposeful: purpose first, then templates, then the clip-mascot mapping and error recovery. Parenthetical template details are compact and informative. The final credit-cost/retry sentence is long and slightly run-on but still earns its place as actionable recovery guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter creation tool with zero schema descriptions, no annotations, and no output schema, the description covers templates and clip-state behavior well but leaves 'id' and 'name' undefined and the custom graph structure entirely unspecified. An agent could pick a template confidently but would be guessing when supplying id, name, or a hand-written graph.
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 0%, so the description must compensate. It does a good job on 'template' (all three enum values with their input semantics) and acknowledges 'graph' as the custom alternative, but never explains the shape of a custom graph (the schema types it as an empty object) and says nothing about the required 'id' and 'name' parameters.
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 and resource: 'Create a state machine that drives the mascot from app events.' That phrasing clearly distinguishes it from sibling creation tools like create_clip, create_mascot, and create_scene by naming the artifact (a state machine/canvas) and its event-driven role.
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 guidance on which template to pick and what trigger/input contract each one expects (chatbot booleans + greet, ai_agent 0-4 status codes, onboarding triggers), plus the alternative of passing a custom graph. It also tells the agent what to do after a failure: create missing clips with create_clip and retry. What's missing is any explicit comparison against sibling tools like animate_mascot for agents deciding whether a canvas is the right approach at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a motion to a clip mascot (an uploaded mascot animated as video): a preset motion, or a prompt describing the motion ('hides behind the bandana, then peeks out'). 60 credits, refunded if the clip fails our checks after one retry. Set regenerate to make a new take of an existing clip instead (also 60 credits). Takes 2–5 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | No | ||
| motion | No | ||
| prompt | No | ||
| regenerate | No | An existing clip's name or id: make a new take of it | |
| max_credits | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the lone openWorldHint annotation, it discloses the 60-credit charge, the refund condition, the single retry, the equal cost of regeneration, and the 2–5 minute processing time. These are concrete operational details that materially affect invocation decisions.
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 compact and front-loaded with the operation and input choices, followed by cost, failure handling, regeneration, and latency. The example is useful, and there is no filler or repeated wording.
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?
It covers the central workflow and unusually useful operational behavior, but important invocation gaps remain for a six-parameter tool with no output schema. In particular, it does not document the required identifier, several parameters, or whether the 2–5 minute operation returns a job that should be monitored with wait_for_job or list_jobs.
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 prompt example and the distinction between initial creation and `regenerate` compensate somewhat for the schema's 17% description coverage. However, the required `id` is not explicitly identified as a mascot or clip identifier, and `name` and `max_credits` receive no semantic explanation.
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 action and resource: adding a motion to a clip mascot, clarified as an uploaded mascot animated as video. It also explains the new-take use case, but does not explicitly distinguish the tool from siblings such as animate_mascot or create_mascot.
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 actionable guidance to supply either a preset `motion` or a descriptive `prompt`, and explicitly says to set `regenerate` when making a new take of an existing clip instead. It does not explain when to prefer this tool over sibling animation tools or when a preset is preferable to a prompt.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Design a new mascot from a description (a rigged vector), or bring an existing mascot image: it is animated as video clips of the exact art (engine "clips": wave to start, 60 credits a motion, the idle is free) or redrawn as a rigged vector (engine "rebuild"); choose one. Provide prompt for a new design, or image_url for your own. Style "realistic" (a photo-real person, animal or product, "no cartoon") draws a photo-real picture and animates it as video instead of rigging it: it breathes free at once, then add motions with create_clip. Waits for the result (1–5 min) and returns a preview.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Hints for rebuilding an upload (e.g. 'the thing in its hand is a phone') | |
| style | No | Visual style for new designs (default polished). realistic: photo-real, animated as video clips (no rig) | |
| engine | No | Required for images: clips (the exact art as video) or rebuild (a rigged vector redraw) | |
| prompt | No | Who the mascot is: species/object, personality, brand context, notable details | |
| image_url | No | Existing mascot image to rebuild | |
| max_credits | No | The most credits this job may charge: stopped and refunded if it would need more |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only openWorldHint in annotations, the description adds substantial behavior: it waits 1–5 minutes, returns a preview, charges 60 credits per motion with idle free, and explains how clips versus rebuild work. It also notes that realistic style animates as video and breathes free immediately. It does not cover failure handling, cancellation, or auth requirements, so it is strong but not exhaustive.
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 front-loads the core choice between new design and existing image, but it is a dense paragraph with nested parentheses, semicolons, and quoted engine names. The information is useful, yet the structure makes it harder to parse than necessary. It is concise in length but not well organized.
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?
The description covers the main creation modes, costs, wait time, and preview return, which is important for a tool with no output schema. However, it does not explain what the preview contains, whether a job ID is returned, how to retrieve the final asset, or what happens if both prompt and image_url are supplied. Given the tool's complexity and minimal annotations, these are meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all six parameters. The description still adds meaning beyond the schema by explaining prompt versus image_url, the consequence of engine clips versus rebuild, and the realistic style exception. It does not add much for notes or max_credits beyond what the schema already says.
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: design a new mascot from a prompt or bring an existing mascot image. It also distinguishes the two engines, clips versus rebuild, and the special realistic style. It does not explicitly differentiate create_mascot from close siblings such as animate_mascot or edit_mascot, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear selection guidance: use prompt for a new design or image_url for an existing image, and choose engine clips or rebuild. It also routes realistic-style motion additions to create_clip. It does not give explicit when-not-to-use guidance or name the other sibling tools for editing or animating existing mascots.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Place the mascot in an illustrated, fully vector scene (hero banner, empty state, social card). Returns SVG + PNG.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| size | No | wide | |
| prompt | Yes | The setting, mood, and purpose, e.g. 'cozy desk at night for an empty inbox state, leave the left half calm for copy' | |
| animation | No | Pose the mascot from this animation (name or preset) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it does usefully disclose the return artifacts ('Returns SVG + PNG'), which is the main behavioral fact an agent needs. But it says nothing about whether the mascot referenced by id must already exist, whether generation is synchronous or a job requiring wait_for_job (a sibling that hints at async flows), or what happens on failure.
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, action and output, with the artifact returned front-loaded second where an agent will read it. There is no filler, hedging, or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter generation tool with no annotations and no output schema, the definition covers the essentials of what it makes and what it returns. It still leaves material gaps: the meaning of the required id, whether the mascot must exist first, and whether output arrives directly or via a job are all unaddressed.
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 50%: prompt and animation are documented in the schema, while id is entirely undocumented and size only carries an enum plus default. The description adds no parameter-level meaning at all—it never explains what id refers to, how animation interacts with the scene prompt, or what the size options produce—so it does not compensate for the coverage gap, but the enum and default keep it at the minimum-viable baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Place the mascot in an illustrated, fully vector scene') and names concrete deliverables (hero banner, empty state, social card), which tells an agent this produces composed scene layouts rather than a bare mascot. It does not explicitly distinguish itself from siblings like create_canvas or create_clip, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical examples (hero banner, empty state, social card) imply the situations the tool is for, which is more than nothing. However, there is no explicit when-to-use versus when-not, and no mention of the alternatives (create_canvas, animate_mascot, add_prop) that an agent must choose between in this crowded sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a mascot's design with an instruction ('make the ears bigger', 'give it a tiny top hat'). For a separate look that keeps all animations working and leaves the current one as it is (outfits, seasonal), set variant_name: it becomes a new look, switched with switch_look. For something held or worn that should be switchable on and off, prefer add_prop. For pure color changes prefer recolor_mascot (instant).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| instruction | Yes | ||
| variant_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose real behavior: variant_name creates a new look, keeps all animations working, and leaves the current look untouched, which tells the agent the operation is additive rather than destructive. Gaps remain around whether the default in-place edit is reversible, what the call returns (a job id?), and whether it is long-running, which matters given list_jobs/wait_for_job siblings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, tightly packed, with the primary behavior front-loaded and the disambiguation clauses following in order of likely confusion. No filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter mutation tool with no output schema and no annotations, it covers purpose, alternatives, and the variant side effect well. It is slightly incomplete on the return value and whether edits are asynchronous or reversible, which an agent needs before firing the call.
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 0%, so the description must supply semantics, and it does for the two required/optional fields that matter: instruction gets example phrasing and variant_name gets full effect semantics. Only id is left unexplained, though it is inferable as a mascot identifier from the sibling set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Change a mascot's design") and immediately characterizes the input as a natural-language instruction with two concrete examples. It is clearly separable from sibling mutators like add_prop and recolor_mascot, which it names and contrasts.
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 three alternative intents: separate look via variant_name, worn/held items via add_prop, pure color changes via recolor_mascot. It also states the follow-up mechanism (switch_look), so the agent knows the full workflow, not just this step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a clip mascot's clip (clip 'idle' or 'breathing': the free breathing idle; clip 'sequence' with clips [..]: idle → those clips → idle in one file, for Slack, email or slides): webm (VP9 alpha), hevc (alpha MOV for Safari/Apple), webp (animated, transparent), gif (matte colour optional), mp4 (on a background colour), stacked-mp4 (colour over alpha, for apps and games), apng, frames (PNG sequence zip), sprite (sheet + JSON zip), png (rest frame). Cached; no credits on Maker and Studio, on Free the first clip downloaded of a character is free, and anything else of it costs 50 credits once and unlocks all its clips. Returns a download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| clip | Yes | Clip name or id | |
| part | No | States (talk, think…): the full motion or only the held loop | |
| size | No | ||
| clips | No | Sequence only (clip "sequence"): clip names in play order | |
| matte | No | ||
| format | Yes | ||
| background | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full burden and does well: it discloses caching, the exact credit model (free first clip per character on Free, 50 credits unlocking all clips, none on Maker/Studio), and the return value (a download URL). It does not say whether the call is synchronous or requires polling via wait_for_job/list_jobs, which is a real gap for a potentially heavy render.
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?
Nearly all content earns its place, but it is delivered as one long run-on sentence with nested parentheticals, so the most important facts (what it downloads, cost, return value) are buried mid-string rather than front-loaded. Structuring the format list and credit rules as separate sentences would improve scanability without adding length.
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, no-annotation, no-output-schema tool, the description covers format tradeoffs, credit implications, caching, and the return value — enough to call it correctly. The remaining gaps are 'part'/'size' semantics and whether the export is asynchronous, which given the presence of list_jobs/wait_for_job siblings is a notable omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 38%, so the description must compensate, and it largely does: it explains the clip values ('idle', 'breathing', 'sequence'), the meaning of the clips array, the optional matte colour for gif, and the background colour for mp4, plus per-format rationale. Undocumented are 'part' (full vs loop), 'size', and 'id', so a gap remains but the majority of ambiguous parameters gain meaning.
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 ("Download a clip mascot's clip") and immediately enumerates the two clip modes ('idle'/'breathing' vs 'sequence' with clips [..]), which distinguishes it from the sibling export_mascot. The format list further pins down exactly what the 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?
It gives use-case context ("for Slack, email or slides" for the sequence mode; Safari/Apple for hevc; apps and games for stacked-mp4), which implicitly guides format selection. However, it never states when to use this versus export_mascot, nor any prerequisites, so routing between siblings 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.
Render a mascot to a file. Animated: lottie (true vector), animated-svg, gif, mp4, webm, webp, apng, sprite (needs animation: an animation name/id or a preset). Stills: png, svg, sticker (die-cut), logo (vector badge), logo-png. No credits on Maker and Studio; on Free, png and gif (plus lottie and animated-svg for the free animation, with a small mark): the first animation downloaded of a character is free, and anything else of it costs 50 credits once and unlocks all its downloads. Returns a download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| fps | No | ||
| size | No | ||
| format | Yes | ||
| animation | No | ||
| background | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does meaningful work: it discloses the tier-based credit/paywall rules, the 'first animation free per character' unlock behavior, and that a download URL is returned. It does not say whether rendering is synchronous or a background job requiring wait_for_job (a sibling exists), nor what defaults apply to size/fps.
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 then groups formats into animated and still categories, which is an efficient structure. The pricing sentence is long and dense but every clause carries distinct information the agent cannot get elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter export tool with no annotations and no output schema, the description covers formats, the conditional requirement, cost gating, and the return value. The remaining gaps are the meaning of `id`/`size`/`fps`/`background` and whether the call is async, which would matter for an agent orchestrating via list_jobs/wait_for_job.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does so well for `format` (explaining lottie as true vector, sticker as die-cut, logo as vector badge) and for `animation` (a name/id or preset, required for sprite). However `id`, `size` (units?), `fps`, and `background` get no explanation, leaving half the parameters to be guessed from types and ranges.
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 a mascot to a file') and immediately enumerates the full set of output formats, so the agent knows exactly what the tool produces. The 'mascot' object also naturally separates it from the sibling export_clip 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 concrete selection guidance among formats (animated vs still, and that 'sprite' requires an `animation` value) plus the credit cost implications that would steer a choice. It stops short of naming alternatives such as export_clip or get_mascot, so the when-not guidance is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code to embed a live, animated mascot in a website or app ( web component, React, or Lottie). For private mascots a signed, expiring link is created.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| look | No | Show this look (get_mascot lists them) instead of the current one | |
| props | No | Show or hide props in this embed only, by id or name: { mug: false } | |
| canvas | No | Run a canvas (create_canvas) by name instead of one animation; the app then drives it with setInput/fire | |
| public | No | Make the mascot public so the embed never expires | |
| trigger | No | auto | |
| animation | No | idle | |
| framework | No | html |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that private mascots receive a signed, expiring link and that embeds are live and animated, but it omits permissions, whether calling creates persistent state, expiration details, and any safety or rate-limit context.
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 tight sentences with no filler, and the core purpose is front-loaded before the private-link caveat. Every sentence contributes useful 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 an 8-parameter tool with no annotations and no output schema, the description is too thin. It does not explain the return structure, most parameter behavior, prerequisites, or how the generated embed code should be used.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, and the description adds meaning mainly for the framework formats and the private/public link behavior. It does not clarify id, look, props, canvas, trigger, or animation, so several parameters remain under-explained relative to the schema gap.
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: getting code to embed a live, animated mascot. It also names supported output formats, which helps distinguish it from broader export tools, but it does not explicitly contrast it with siblings such as export_mascot or export_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?
The description implies the tool is for obtaining embed code, but it gives no explicit when-to-use guidance, no exclusions, and no alternatives. It does not explain when to choose get_embed_code versus export_mascot or export_clip.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Details and a preview image of one mascot.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares this is a non-mutating read, so the bar is lower. The description adds useful return context by saying the response includes details plus a preview image, which the annotations do not convey. It says nothing about error behavior for unknown ids or whether the preview is a URL or embedded data.
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?
One short sentence with zero filler, and the key noun (preview image) is front-loaded alongside the resource. It is efficient, though its brevity borders on under-specification rather than tightness.
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 one-parameter read tool with no output schema, the description covers the essential shape of the return (details plus preview image) and the singular scope. However, the undefined identifier semantics leave a genuine gap an agent must guess at. No annotations beyond readOnlyHint need supplementing.
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 0% for the single required 'id' parameter, so the description carries the full burden and does not meet it. It never clarifies whether 'id' is a mascot identifier, a slug, or a name, nor what format is expected. 'One mascot' hints that the argument selects a single entity, but adds no real semantic detail.
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 and scope: 'Details and a preview image of one mascot,' which distinguishes it from the plural listing sibling list_mascots by emphasizing a single mascot. The verb is implicit ('details ... of one mascot') rather than an explicit 'retrieve', but an agent can still infer the operation. It stops short of naming any sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this versus list_mascots, edit_mascot, or the other mascot-related siblings. No prerequisites or exclusions are stated; the agent must infer that this is the read path for a known mascot id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The motion library of a clip mascot (an uploaded mascot animated as video): each clip's name, status, length and size.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this as a safe read, and the description adds useful disclosure of what is returned (name, status, length, size). It does not say whether results are paginated, ordered, or what happens when the id is invalid or the mascot has no clips.
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?
One sentence with no wasted words, but it is a sentence fragment focused on output contents rather than on the action, which makes the opening less immediately actionable than a verb-first statement would be.
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, listing the returned fields is genuinely valuable and mostly covers the return side. However, for a one-parameter lookup tool the ambiguity around what 'id' identifies, plus the absence of pagination or empty-result behavior, leaves meaningful gaps.
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 single parameter 'id' has 0% schema description coverage, so the description carries the full burden. It only weakly implies the id refers to a clip mascot via the phrase 'of a clip mascot'; it never states that explicitly, nor whether it accepts a mascot id versus a clip id.
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 the resource (the motion library of a clip mascot) and enumerates returned fields, but it is a noun phrase with no verb — the agent must infer 'list' from the title and name. It does implicitly distinguish itself from list_mascots by scoping to clips of a single mascot, but that differentiation is left implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_mascot or create_clip. The agent is not told what condition selects this tool over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent jobs and their status.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the description is not carrying the safety burden. Beyond that it only says "recent," which vaguely implies a bounded window but never states how recent, whether results are paginated, or whether ordering is newest-first.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler, so nothing is wasted. However, the brevity comes from under-specification rather than disciplined editing, so it is only minimally adequate for a job-listing tool.
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 should describe the shape of returned jobs, the recency window, and pagination or limits; it does none of these. For a tool whose main use is polling alongside wait_for_job, that leaves key operational details 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 0%, and the single parameter is an optional status enum whose filtering behavior the description never explains. It does not say whether omitting status returns all jobs or only active ones, so the one free knob on this tool is undocumented in both structured fields and prose.
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?
"Recent jobs and their status." essentially restates the name and title (list_jobs / List recent jobs) without a verb or resource scope. It adds only the hint that results carry status, and gives no signal that distinguishes it from siblings such as wait_for_job or list_clips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of how this relates to wait_for_job (the obvious polling alternative), and no statement of when to filter by status versus listing everything. The agent must infer all routing decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the mascots in this workspace.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the description's only added behavior is that results are scoped to the current workspace. It does not say whether results are paginated, truncated, or returned as summaries versus full mascot objects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-formed sentence with the scope qualifier front-loaded after the verb; nothing is redundant. It is terse to the point of omitting anything beyond the bare action.
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 parameterless read tool with no output schema and readOnly annotation coverage, the definition is adequate but says nothing about result shape or volume. An agent still has to call it to learn whether it returns full mascots, IDs, or a paginated page.
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 there is nothing for the description to disambiguate beyond confirming the workspace-level scope. Baseline 4 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 ("List") and resource ("mascots") with a scope qualifier ("in this workspace"), which cleanly separates it from get_mascot or create_mascot. It does not explicitly name a sibling, so it stops short of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the verb: use this to enumerate mascots rather than fetch one. There is no explicit statement of when to prefer it over get_mascot or how it relates to list_clips/list_jobs, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Instantly change palette colors by token name (see get_mascot for the palette), e.g. { fur: '#3b82f6' }.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| palette | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Instantly change' implies a mutation with immediate effect, but it never says whether the palette argument replaces the whole palette or merges into existing tokens, whether unlisted tokens are preserved, or whether the change is reversible — all critical for a mutation 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?
A single sentence with the core action front-loaded, a pointer to the prerequisite tool, and an inline example — no wasted words.
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 mutation tool with no annotations and no output schema, the definition covers the palette shape adequately but omits the identity parameter's meaning and the merge/replace semantics of the update. An agent could call it, but might silently wipe tokens it did not intend to change.
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 0%, so the description must compensate. It does well for 'palette' by explaining token-name keys and giving a hex-value example, but 'id' is never described (presumably a mascot identifier) and the schema's hex pattern constraint is only implied by the example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('change') and resource ('palette colors by token name') with a concrete example, so an agent knows exactly what the tool does. It does not distinguish itself from the sibling 'edit_mascot', leaving ambiguity about which tool to reach for when changing colors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical '(see get_mascot for the palette)' usefully implies a prerequisite discovery step before calling. However, there is no guidance on when to use this versus 'edit_mascot', 'switch_look', or 'create_mascot', and no statement about whether the mascot must already exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A reaction plays once (rest → motion → rest). A state enters its pose, loops the held part for as long as it is playing, then exits (talk, think, sleep). Switching to state needs a clean held loop in the clip; free.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| clip | Yes | The clip's name or id | |
| kind | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint annotation, the description discloses meaningful playback semantics: reactions play once through rest-motion-rest, while states enter a pose, loop the held portion, and exit. It also notes the held-loop requirement for state, though it does not explain failure behavior or side effects on existing animation.
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 short and front-loads the key definitions of reaction and state. The trailing word 'free' is cryptic and slightly undermines clarity, but the overall structure is efficient.
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 three-parameter mutation with no output schema, the description covers the core behavioral distinction and the state prerequisite. However, it leaves the id parameter unexplained and does not describe what happens when the clean held loop requirement is not met.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, with the clip parameter documented and kind represented by an enum. The description adds substantial meaning for the kind values by explaining reaction versus state behavior, but it does not clarify what the id parameter refers to, leaving part of the low-coverage schema uncompensated.
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 defines what a reaction and a state are in this system, making the tool's classification purpose clear when combined with the name and title. It does not explicitly differentiate from siblings, but no sibling tool appears to perform this classification.
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 gives one important prerequisite: switching to state requires a clean held loop in the clip. It does not explicitly state when to choose this tool over alternatives or what to do if the prerequisite is unmet, leaving usage largely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show or hide the mascot's props (things it holds or wears, see get_mascot), by id or name: { mug: false, crown: true }. Free and instant; a hidden prop leaves the mascot as it was, and exports and embeds follow.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| props | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does add real behavioral context: 'free and instant' discloses cost/latency, 'a hidden prop leaves the mascot as it was' signals the change is non-destructive and reversible, and 'exports and embeds follow' discloses propagation to downstream artifacts. It does not cover error cases or whether a nonexistent prop name is silently ignored.
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?
Compact and front-loaded: the action and resource come first, followed by the example, then the cost and side-effect facts. Every clause carries information, with only mild density cost from packing several behaviors 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?
For a tool with a nested object parameter, no annotations, and no output schema, the description covers the essential ground: what props are, the input shape, the cost, and the effect on mascot state and exports. The main residual gap is clarifying the required mascot id/name argument.
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 0%, so the description must compensate, and it partly does by clarifying that props is a map of prop identifier to boolean, with the example { mug: false, crown: true }. However, 'by id or name' is ambiguous about whether it applies to the mascot identifier or the prop keys, and the required top-level 'id' parameter is never explicitly explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair (show/hide) and resource (the mascot's props), with a parenthetical defining what props are ('things it holds or wears') and a concrete example. It is distinguishable from most siblings, though it never explicitly contrasts with add_prop, the tool that adds new props.
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 points to get_mascot for discovering props and shows the expected input shape, which implies the workflow, but it gives no explicit when-to-use vs when-not guidance and does not name add_prop as the alternative for introducing props the mascot doesn't already have.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ideas for animations that fit this character and the product moments it will live in (onboarding, waiting, success, errors…). Feed any idea's prompt to animate_mascot.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| use_case | No | What the product is and where the mascot appears |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true is consistent with a brainstorming tool, so the safety profile is already covered by annotations. The description adds the meaningful detail that the result is a set of idea/prompt pairs meant to be reused downstream. It does not say how many ideas come back or how they're structured.
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 what the tool produces and ending on the actionable handoff. 'Product moments it will live in' is slightly oblique phrasing that could simply be 'where the mascot appears', but nothing is 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?
For a read-only generator with no output schema, the description should convey the shape of what comes back; it only gestures at 'ideas' with prompts. The identity of the required id (a mascot or character) is left to inference. Adequate to call correctly, but thin for the tool's role as the entry point of the animation workflow.
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 50%: use_case is documented in the schema, while id is not. The description partially compensates by implying id identifies 'this character' and that use_case should describe the product and moments. With half the parameters undocumented and only a loose gloss provided, this is baseline rather than a gain.
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 the output (animation ideas) and the axis they're generated along (the character plus the product moments it appears in), and explicitly routes to animate_mascot as the consumer of an idea's prompt. That distinguishes it from the sibling mutation tools, though the generating verb is implied by the name rather than stated ('Ideas for…' instead of 'Suggests…').
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 establishes a clear pipeline position: call this first, then feed an idea's prompt into animate_mascot. The enumerated moments (onboarding, waiting, success, errors) hint at the use case to supply. It stops short of stating exclusions or prerequisites, e.g. that an existing character id is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make one of the mascot's looks current by name: 'Original' or a variant made with edit_mascot variant_name (get_mascot lists them). Free and instant; each look keeps its own edits, colours and props, and every animation works on all of them.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| look | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose meaningful traits: the operation is free and instant, edits/colours/props are preserved per look, and all animations remain valid. It does not cover permissions, error behavior for an unknown look name, or whether switching affects anything else.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with the action and accepted values front-loaded; the trailing clauses about per-look state and animations earn their place. Slightly dense with parenthetical nesting, but no wasted text.
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 two-parameter switch with no output schema and no annotations, the description covers values, effects and cost well, but omits the meaning of 'id' and what happens on an invalid look name, leaving gaps an agent may need to discover by trial.
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 0%, so the description must compensate. It adds real meaning for 'look' (its accepted values and where they come from) but says nothing about 'id', leaving the agent to infer it is the mascot identifier.
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 ('make one of the mascot's looks current by name') and immediately enumerates the valid values ('Original' or a variant). An agent can distinguish this from edit_mascot, recolor_mascot and get_mascot 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 clear context for use (switching the active look) and routes the agent to siblings: get_mascot to list looks and edit_mascot to create a variant by variant_name. It never states an explicit when-not-to-use case, which keeps it 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.
Wait for a long-running job (creation, edit, custom animation, export) and return its result.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read. The description adds real value by disclosing that the call blocks and returns the job's result. It omits critical behavior for a wait tool: timeout, whether it polls or blocks, and what happens on job failure — gaps that matter a lot here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the core action first and the scope parenthetical second. Every clause carries information; nothing is padded.
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 only says 'return its result,' giving no sense of the result shape. Combined with the silence on timeouts and failure modes for a blocking operation, it is minimally adequate but leaves meaningful gaps.
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?
There is one parameter with 0% schema description coverage, so the description must compensate and does not. It never says where a job_id comes from (presumably list_jobs or a creation tool) or what form it takes, leaving the only required input underspecified in both places.
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?
Uses a specific verb ('wait for') plus a specific resource ('long-running job') and enumerates the job kinds it covers (creation, edit, custom animation, export). This distinguishes it reasonably from the sibling list_jobs, though it does not explicitly name that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'long-running job' implies this is the follow-up to some async operation, so usage is inferable. However, it never says which tool starts a job, nor explicitly contrasts blocking here versus polling with list_jobs, leaving the agent to infer the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_propanalyze_websiteanimate_mascotcreate_canvascreate_clipcreate_mascotcreate_sceneedit_mascotexport_clipexport_mascotget_embed_codeget_mascotlist_clipslist_jobslist_mascotsrecolor_mascotset_clip_kindset_propssuggest_animationsswitch_lookwait_for_job
Add one secure layer between your agents and this server.