MascotLab

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

Annotations already cover read-only, idempotent and non-destructive, so the bar is lower, yet the description still adds meaningful behavior: server-side waiting that returns as soon as the render settles, and the fact that download URLs are short-lived. It does not mention what a failed or expired generation looks like or any rate limits.

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 short sentences, front-loaded with what the tool is, then the waiting strategy, then the return nuance. Every sentence carries information an agent needs; 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 an output schema present, return values need not be spelled out, and the ephemeral-URL caveat covers the one thing the schema likely won't convey. The remaining gap is failure handling — what to do if the generation never settles or errors out.

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 schema already explains wait_seconds ('0 checks instantly', max 50), so the baseline is 3. The description goes beyond it by recommending 45 as the practical value and explaining the payoff in terms of expected call counts, which is genuine added 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?

States a specific resource and scope: 'Status of a generation_id from any create_* tool.' This clearly ties it to the create_* siblings as the follow-up call and implicitly separates it from download_artifact by noting completed results carry a download URL. It falls short of 5 only because it never names the sibling an agent might confuse it with.

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

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

Gives real operational guidance: set wait_seconds (recommended 45) and one or two calls usually cover an image while a few cover an animation. That tells the agent how to poll in practice. It does not state when to stop checking or when to reach for download_artifact instead.

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 real behavior beyond the annotations: cost per call, an account-level prerequisite that can block invocation, 1-3 minute latency, and the returned generation_id plus the polling cadence needed. Annotations only say it is a non-idempotent, non-destructive, open-world write; the description supplies the operational facts an agent actually 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?

Three sentences, each carrying distinct payload: purpose plus cost and prerequisite, then clip-shaping options, then what is returned and how to poll. Front-loaded with the action and 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 5-parameter generative write tool, the description covers cost, eligibility, latency, return value and the exact polling recipe. An output schema exists so return-shape detail is not required, yet the description still names generation_id, which is the key needed to proceed.

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 explains loop, motion, pose_id, mascot_id and end_pose_id, including precedence rules. The description restates the end_pose_id/loop framing as 'pinned at both ends' but adds no syntax or constraints beyond what the schema provides; 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 output artifact: animates a pose or mascot into a short silent MP4 clip. The pose-vs-mascot subject choice is named up front, which cleanly separates it from create_pose and 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?

Gives concrete operating context: 5 credits, an account prerequisite (must have bought credits at least once), and an explicit follow-up loop naming check_generation with wait_seconds 50. It stops short of saying when NOT to use this instead of create_pose or create_mascot, so it misses the top band.

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 write/non-idempotent/open-world; the description adds the concrete cost model ('2 credits, charged only on success'), the asynchronous contract (returns generation_id immediately), and expected latency of 10-40 seconds. It also flags the downstream consequence that the mascot anchors every later pose and animation, which matters for a non-idempotent create.

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

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

Three sentences, zero filler, ordered purpose → cost/async contract → design advice. The most decision-critical facts (what it makes, what it costs, how to get the result) come first.

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 write tool with an output schema and full schema coverage, the description supplies exactly the missing behavioural layer: billing, sync-vs-async, latency, and the reuse consequence. No return-value explanation is needed since an output schema exists.

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 adds real guidance for the required description field ('describe species, personality and look in one sentence') and hints at the reference_mascot_id behaviour by warning that the description is reused for every later pose. Not full credit because style, name and reference_pose_id get no mention 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 and resource ('Generates a new mascot character from a description') and scopes the output as a generation job. The 'anchors every later pose and animation' line makes clear how it differs from create_pose and create_animation without naming them.

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

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

Explicitly says to poll the returned generation_id with check_generation and gives a rough wait window, so the workflow is unambiguous. It also advises on how to write the description input. It stops short of stating when to use create_pose or reference_mascot_id instead, leaving that routing to the schema.

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 the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower, yet the description adds genuinely new behavior: a 2-credit charge billed only on success, and identity anchoring to each mascot's reference sheet so output stays on-model. Both are things an agent cannot learn from the structured fields and directly affect whether it retries or how it forecasts cost.

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

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

Three sentences, front-loaded with the core action, then cost, then the return contract. Every clause carries information an agent needs; nothing is padding.

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

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

Covers the action, the optional variations, the pricing model, the on-model guarantee, and the handoff to check_generation. With an output schema present and 100% parameter coverage, no further explanation of return values or argument formats is required.

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 parameter docs are unusually thorough, including the mascot_id fallback chain and the rationale for a two-character maximum. The description only restates the prop and second-mascot options already in the schema, adding no parameter-level meaning of its own — 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?

Opens with a specific verb and resource — renders a mascot performing an action — plus the optional prop and second-mascot variations, which separates it from create_mascot and create_prop. It doesn't explicitly contrast itself with create_animation, the nearest ambiguous sibling, so an agent must infer the static-vs-animated boundary.

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?

Names the follow-up action precisely ('Returns a generation_id for check_generation'), which is concrete routing guidance, and states the cost up front so the agent can weigh it. There is no explicit when-not-to-use clause versus create_animation, so the puzzle of pose-vs-animation selection is left implicit.

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

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

Beyond the annotations, the description discloses a meaningful behavioral trait: creating the project changes the active project context. That is a key state mutation not captured by readOnlyHint, destructiveHint, or idempotentHint. It does not describe error behavior or what happens to a previously active project, but the main side effect is clearly communicated.

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 a single, front-loaded sentence with no wasted language. It states the creation action and the active-project side effect efficiently.

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

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

Given the simple one-parameter schema, available annotations, and output schema, the description provides enough context to call the tool correctly. The main omission is an explicit comparison to select_project, but the active-project side effect covers the critical workflow distinction.

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 name parameter is already fully documented in the schema. The description does not add syntax, formatting, or semantic details beyond what the schema provides, 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?

The description states a specific verb and resource: it creates a new project. It also adds the important side effect that the project becomes active, which distinguishes this from simply selecting an existing project, though it does not explicitly name the sibling select_project.

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 usage context by explaining that following create_* calls will land in the newly created active project. It does not describe exclusions or explicitly say when to use select_project instead, but the intended workflow is clear.

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

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

Annotations already declare non-readonly, non-idempotent, open-world, non-destructive behavior, so the bar is lower. The description still adds real value beyond them: a 2-credit cost charged only on success, and the fact that the result is asynchronous (a generation_id to poll). It does not mention failure modes or latency expectations.

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 short sentences, front-loaded with what is created, followed by cost and the follow-up tool. Nothing redundant; the cost disclosure is placed where an agent evaluating the call will see it.

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

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

An output schema exists, yet the description still names the key return field the agent needs (generation_id) and the tool to use next. Combined with cost and reusability notes, an agent has everything required to call it correctly and handle 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 coverage is 100%, so both parameters (name, description) are already documented in the schema. The description's examples ('a wrench or a coffee cup', 'a red pipe wrench') illustrate the intended granularity of the description parameter but add no constraints or format detail beyond the schema. Baseline 3.

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 ('Generates') and resource ('a standalone object the mascot can hold or use') with concrete examples (wrench, coffee cup). This clearly separates it from create_pose, create_mascot, and create_animation in the sibling list.

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 provides clear downstream context — the returned generation_id feeds check_generation — and notes props are reusable across poses, which tells the agent not to regenerate per pose. It does not explicitly exclude or compare against siblings (e.g. when to make a prop vs. build it into a pose), so not 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?

Beyond the annotations, the description discloses the 10-minute URL lifetime, the first-transparent-request cutout delay, subsequent instant requests, and a concrete wait-rather-than-retry instruction. These are meaningful behavioral details for an agent invoking the tool.

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

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

The description is front-loaded with the core action and URL expiration, then moves through usage, background selection, and latency guidance. Every sentence contributes useful information with no repetition or 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 download tool with rich schema coverage and an output schema, the description covers the essential invocation context: URL expiry, fetching promptly, transparent PNG behavior, and first-request latency. Nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already explains id, kind, and background thoroughly. The description mostly restates those parameter meanings and adds a latency note that is behavioral rather than parameter-specific, 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?

The description states a specific verb and resource: minting a fresh download URL for an artifact on the board, and it enumerates the artifact kinds. It also points to get_board as the source of ids, which implicitly distinguishes it from the create_* 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 clear operational guidance: use ids from get_board, fetch the URL promptly, and use background:none for transparent PNGs when placing a mascot on an app screen. It does not explicitly state when not to use the tool or name alternatives, but the usage context is otherwise clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds real domain behavior beyond that: a prior credit purchase is the gate that unlocks animation, and it exposes the credit price of each generation type — non-obvious business rules an agent cannot get from the schema.

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 that front-loads the three returned facts and parenthesizes the unlock rule, then closes with the operational reason to call it. No filler, no repetition of schema or annotation content.

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 no-arg, read-only status tool with an output schema already defined, the description covers everything needed: what is returned, the gating rule for animation, and the cost model. Nothing required 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?

Zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies no arguments are needed, consistent with an empty properties object.

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 enumerates exactly what the tool returns: credit balance, whether the account has ever purchased credits, and the per-generation cost table (mascot 2, prop 2, pose 2, animation 5). That grounds it clearly against generation siblings like create_animation/create_mascot, though it never explicitly says 'this is a read-only account-info call, not a generation action.'

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?

'Call this before expensive work to know what the balance allows' gives an explicit invocation condition tied to the costly sibling tools. There is no stated when-not or alternative (e.g. no other balance-checking tool exists), but the positive guidance is concrete.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds real context beyond them: it discloses that in-flight (incomplete) generations are included in the result and that the returned ids are the handles other tools consume. It does not discuss result size or per-project scoping costs, but the output schema covers the return 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?

A single dense sentence that front-loads the payload contents, then the id-routing value, then the default behavior. No filler, no 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?

With an output schema present and rich annotations, the description only needs to establish scope and result character; it does that by naming the included entity types and the in-flight state. The only meaningful omission is any sense of result volume or whether the board can be large enough to warrant care, which for a single-project read tool is a minor gap.

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

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

Schema coverage is 100% and the single optional project_id is fully described in the schema as 'omitted, the active project.' The description restates the same default behavior without adding format or lookup guidance, so the schema is doing the heavy lifting and 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?

Enumerates the concrete resources returned (mascots, props, poses, animations, in-flight generations) and frames the output as an id source for other tools, which clearly separates it from siblings like list_projects or check_generation. The read verb itself is carried by the name/title rather than the description, so it stops just short of a fully self-contained purpose statement.

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 clause 'Defaults to the active project' implies when this tool is the right call (the passive default read) and hints at select_project as the alternative for switching context, but neither is stated explicitly. No when-not-to-use guidance or named sibling alternative is given, so usage must be inferred.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the returned set includes the active project, and generations are routed to that active project, which is a downstream-effect fact 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?

Two short sentences with no waste, and the returned-content statement is front-loaded ahead of the active-project behavior. Every sentence carries information.

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

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

With an output schema present, full annotation coverage and no parameters, the description only needs to frame the tool's role, which it does. A small gap remains: it does not say whether this is the prerequisite step for select_project, which matters given the sibling set.

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; baseline 4 applies. Schema coverage is 100% and no parameter meaning is missing.

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

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

States the specific resource (the user's MascotLab projects) and what the response carries (ids and which project is active). It is distinguishable from create_project and select_project by implication of being a read/list, though it never uses an explicit list verb or names the siblings it contrasts with.

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: the note that 'generations always land on the active project' hints you may need this before generating or before select_project. There is no explicit statement of when to call this versus select_project or get_account.

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive mutation. The description adds valuable context beyond that: the selection is global state that affects where all create_* tools write. It does not clarify scope persistence (session vs account) or failure behavior for invalid IDs, but the key side effect is disclosed.

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 core action and followed by the most important operational consequence. Every sentence 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?

For a single-parameter state-setting tool with annotations and an output schema, the description covers the essential effect on downstream tools. Minor gaps remain around persistence scope and error behavior but are not critical for correct invocation.

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

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

Schema description coverage is 100% and the single project_id parameter is documented in the schema as 'A project id from list_projects.' The description adds no additional parameter semantics beyond what the schema already provides.

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

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

States a specific verb and resource ('Makes a project the active one') and implicitly distinguishes itself from create_project by referring to existing projects. An agent can tell exactly what state change this tool performs 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?

Provides a concrete usage rule: 'switch first when working across projects' because create_* tools target the active project. It lacks explicit when-not guidance or a named alternative (e.g., instructing to call list_projects first), but the conditional trigger is clear.

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