Posy

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: that inputs are auto-detected from links, emails, owner/repos, or notes. It does not describe the result of a successful add or how ordering interacts with 'after'.

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 tightly packed sentence with the verb front-loaded and the parameter guidance following immediately. Every clause carries information and 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?

For a 6-parameter mutation tool with a nested tile object and no output schema, the description covers only the content-input parameters. It says nothing about size, color, or after placement, and does not indicate what is returned, leaving several parameters unaddressed in both description and schema.

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

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

Schema coverage is 67% and the description meaningfully complements it, clarifying that inputs (plural) takes several values, input takes one, and both are auto-detected while tile expects a full object. This resolves the mutually-exclusive input modes better than the schema alone.

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 ('Add tiles'), which clearly distinguishes it from move_tile, remove_tile, and update_tile in the sibling set. It stops short of explicitly framing itself as the creation counterpart to those tools, so it is clear but not maximally differentiated.

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 explains the three ways to supply content (inputs, input, or a tile object), which is actionable invocation guidance, but never says when to reach for add_tile versus siblings like import_page or update_tile. Usage is implied rather than scoped.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=false, so the safety profile is covered. The description adds real behavioral context beyond that: the one-page-per-account uniqueness constraint and the default-to-starter-template behavior when style is omitted. It stops short of covering permissions or what happens on a username collision.

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 the core action front-loaded and no filler. The style/template clause earns its place, though it is partly duplicative of the schema.

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

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

For a creation tool with six parameters, four enums, and no output schema, the description is thin: it does not explain what the caller gets back, how style, preset, template, and layout interact or conflict, or the outcome of a failed username claim. An agent can call it, but must infer a lot.

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 67%, and the description only elaborates on `style`, whose schema entry already says "Omit to use a starter template" — so it is largely redundant. The undocumented gaps (`layout`, `template`, `empty`, and the relationship between style/preset/template) are not filled in by the description.

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

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

The description names a specific verb ("create") and resource ("the user's page") and adds a scoping constraint ("one per account") that clarifies the operation's nature. It does not, however, explicitly distinguish itself from the closely related sibling import_page, which an agent could plausibly 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?

The parenthetical "(one per account)" implies a precondition — you cannot call this twice for the same account — which is useful usage context. But there is no explicit when-to-use guidance and no routing to alternatives like import_page for bringing in an existing page.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context that the payload is the 'current draft' and includes unpublished changes, but says nothing about auth requirements, error/empty states, or 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?

A single short, front-loaded clause with no wasted words. It is efficient, though the lack of a verb makes it slightly less self-explanatory than a full sentence 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 parameters, no output schema, and no nested objects, this is a low-complexity read tool whose return contents are spelled out in the description. The main omission is behavior when no page exists or when errors occur.

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 document; the 4 baseline for a parameterless tool applies. No parameter-related gaps exist.

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 and enumerates its contents (draft, profile, theme, tiles, URL, version, unpublished changes), but it is a noun-phrase fragment with no verb — the retrieval action is only implied by the name/title. Among siblings it reads as the only read/get operation, but that distinction is inferred 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 guidance on when to call this versus siblings such as create_page, import_page, or publish, and no prerequisites or exclusions are mentioned. The agent must infer usage entirely from the name.

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

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=false, so the safety profile is partly covered. The description adds a genuinely useful nuance the annotations cannot express: an existing page is left alone unless replace is true, and only the draft is affected. It still omits auth requirements and any error/response behavior.

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

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

Two dense sentences, zero filler, with the bulk-import scope stated first and the conditional creation/replacement rules second. Every clause carries information an agent needs.

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 annotations covering safety, the description covers both operating modes (create-if-absent, replace-draft-if-flagged) plus the accepted input shapes. It lacks any statement about return value or failure modes, which is a minor gap rather than a blocking one.

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 67% and username has no schema description at all; the description compensates by explaining username's role (creation path) and clarifying replace's exact effect on an existing page. file's dual string/object nature is echoed from the schema rather than extended, but the added meaning for the other two params is solid.

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

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

States a specific verb+resource ('Load a whole page at once') and enumerates the accepted source formats (Posy brief with name/bio/look/theme/links, or full page JSON). This implicitly separates it from per-element siblings like add_tile or update_tile, though it never names an alternative explicitly, so it falls just short of a 5.

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

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

Gives two concrete conditional rules: pass username when no page exists, and replace=true is required to overwrite an existing draft. That is real when-to-use guidance, but it never contrasts this tool with create_page or add_tile for the 'I just want one tile' case.

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, destructiveHint=false and a closed world, so safety is covered. The description adds genuine value beyond them by disclosing return shape with no output schema present: looks come 'with a note and the palettes each offers,' telling the agent the result is structured rather than a flat list. Other categories' result shapes remain unspecified.

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 primary category (looks) and compresses the remaining ones into a tight enumeration. No filler, no repetition of the title, and the parenthetical detail is the only added information that earns its place.

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

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

For a zero-parameter, read-only enumeration tool with no output schema, the description covers the domain of returned values adequately. It is slightly thin on the structure of the non-'looks' categories, but nothing prevents a correct 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No misleading or spurious parameter hints are given.

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 — allowed values for looks, themes, fonts, backgrounds, tile styles, sizes, colours and social platforms — so an agent knows the resource precisely. It omits an explicit verb (e.g. 'returns the allowed values'), but the scope is unambiguous. It does not name any sibling, though the enumerated categories clearly complement the setters like set_theme and set_profile.

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 explicit when-to-use statement, no prerequisites, and no named alternative. Usage is only implied: listing allowed values for themes/fonts/backgrounds maps onto siblings such as set_theme and set_profile, so an agent can infer this is the discovery call to make first. That inference is reasonable but never stated.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds the useful behavioral detail that positions are 0-based, but says nothing about how the remaining tiles reflow, what happens with an out-of-range position, or any permission requirement.

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 the essential scope front-loaded and no filler. It is efficiently sized, though terse enough that it trades away some necessary detail.

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 reorder tool with no output schema, the description covers the core action but omits reflow behavior, out-of-range handling, and the meaning of 'id'. It is minimally viable rather than complete.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that 'position' is a 0-based index into the tile list, which the schema (integer, min 0) cannot convey, but leaves 'id' undocumented and gives no guidance on bounds or invalid values.

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 (move) and resource (tile) plus the target semantics (0-based position in the tile list), which separates it from add_tile/remove_tile/update_tile. It does not explicitly name a sibling or contrast itself with update_tile, which is the nearest ambiguous neighbor.

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 statement of when to use this instead of update_tile (which may also change ordering) or any precondition such as the tile needing to already exist. Usage is only inferable from the name and the word 'position'.

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, open-world, idempotent, non-destructive write, so the safety profile is covered. The description adds the meaningful behavioral detail that the result is publicly reachable at a URL. It does not say whether the action can be reversed (unpublish), what permissions are required, or what is returned.

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 no wasted clauses; the core effect is stated immediately.

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 and no parameters, the description carries the return-value burden and stays silent on it - notably the public URL itself, which is the key artifact of publishing. It covers the core effect adequately but leaves the outcome details unstated.

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 per the baseline there is nothing for the description to disambiguate. Schema coverage is 100% and the description introduces no parameter confusion.

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 action and outcome: turning a draft into a live page at a public URL. It is clear enough to distinguish from purely structural siblings, though it never names the resource ('page') and relies on the reader inferring it from context.

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 explicit guidance on when to use this versus alternatives, nor any prerequisites (e.g., must a draft exist first). Usage is only implied by the word 'draft'.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that – it doesn't say whether deletion cascades to child elements, whether it requires ownership, or whether the parent page is affected.

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 no filler, which is appropriate for a one-parameter tool. It is terse to the point of omitting needed context, but it wastes no 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 destructive mutation tool, the description leaves out what actually gets removed, side effects on related tiles, and any permission requirements. Annotations cover the safety hints and there is no output schema, but the description still leaves the agent under-informed about the consequences of 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 coverage is 0% and the single 'id' parameter is undocumented in the schema. The phrase 'by id' identifies which parameter is the lookup key but adds no detail on format, scope, or where the id comes from, so it only marginally compensates.

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 ('Delete a tile') and identifies the lookup key ('by id'), so the operation is immediately clear. It does not distinguish itself from siblings like update_tile or move_tile, which also operate on tiles, so it falls short of a 5.

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

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

The description offers no when-to-use context, no prerequisites, and no guidance on how it differs from update_tile or add_tile. An agent must infer the use case entirely.

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 safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description need not restate it. It does add useful behavior: that avatarFocus/avatarZoom act as crop controls rather than raw coordinates. However, it never says whether unspecified fields are preserved (partial update) or cleared, which is the key behavioral question for a 0-required-param mutation.

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

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

Two sentences, zero filler. The primary field list is front-loaded and the avatar crop detail follows as a subordinate clause, which mirrors the nesting in the schema.

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

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

For a mutation tool whose annotations already cover reversibility and idempotency, with no output schema to explain, this is nearly complete on parameters and purpose. The remaining gap is partial-update semantics and auth/permission requirements.

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 carry the load, and it does cover all six parameters by name plus the nested avatarFocus x/y. It also supplies meaning the schema lacks: 'avatar URL' (type hint) and the semantics of the ranges (0–100 percent focus, 1–3 zoom) as crop values.

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') plus the exact resource fields it mutates (name, bio, avatar URL, location), and extends to the avatar crop sub-fields. It is unambiguous what the tool does, though it makes no attempt to differentiate from siblings (set_theme, update_tile) since those operate on different resources anyway.

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 or when-not-to-use guidance, no statement that this edits the caller's own profile, and no prerequisites (e.g. authentication or avatar upload requirements). Usage is only inferable from the verb 'Change'.

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=true, destructiveHint=false), so safety is covered. The description adds the partial-update contract in "only pass what should change", which is genuine behavioral context not in the annotations, but says nothing about scope of effect (account-wide vs. page), reversibility, or whether omitted fields reset.

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

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

Three tight sentences with the primary purpose front-loaded and the partial-update rule stated early. The parenthetical restating the `style` enum values duplicates schema content, which is minor waste but the passage stays short overall.

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

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

For a 14-parameter, zero-required, nested-object configuration tool with no output schema, the description covers purpose and update semantics but leaves the bulk of the parameter surface undocumented. An agent would be guessing at most fields from bare enum names.

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 only 7% and the description explains just 2 of 14 parameters (style, preset), including the useful style-to-preset dependency. With twelve parameters, a nested background object, and no required fields, the description fails to compensate for the coverage 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?

Names a specific verb (Change) and its resources (colours, fonts, layout and other theme settings), so the agent knows exactly what domain this covers. It does not differentiate itself from set_profile, the nearest sibling, which also mutates user-level configuration.

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?

"Only pass what should change" is a real usage instruction for partial updates and is useful. However, there is no when-to-use vs. alternative guidance, no prerequisites, and no statement of when this tool is inappropriate relative to siblings like set_profile.

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, idempotent, non-destructive behavior, so the safety profile is covered. The description adds useful behavioral detail (arbitrary field patches plus a focus/zoom crop mode that alters what the tile displays), but says nothing about permissions or what happens to fields not included in the patch.

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

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

Front-loaded with the core operation, then the crop special case; every clause earns its place. Slightly terse JSON-in-prose formatting, but no wasted sentences.

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 2-param mutation tool with no output schema and a vague patch schema, the description covers the main patch surface and the crop mode, but leaves open whether the patch merges with or replaces existing tile fields and what the returned tile looks like.

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% and the patch object is untyped additionalProperties, so the description carries the load. It does this well by enumerating patch keys (size, title, color, text) and fully specifying the crop object including the 0–100 focus range and 1–3 zoom range; only the 'id' parameter is undocumented (reasonably obvious).

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

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

States a specific verb+resource ('Change fields of a tile') and immediately demonstrates the shape of the change with concrete examples. It is distinguishable from siblings like move_tile or add_tile by implication, but sibling differentiation is not made 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?

Usage is implied rather than stated: the examples show what can be patched, but there is no guidance on when to use this versus move_tile (also a field change) or add_tile, and no prerequisites are mentioned.

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