Time.Graphics

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, and the description adds a real constraint: the timeline must be owned by the user. However it does not disclose whether added events are appended to or replace existing ones, nor what happens on invalid timeline ids, which matters for a bulk 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?

Three short sentences, front-loaded with the action and scope, then the id-discovery step, then the format hint. 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?

Given a write tool with nested array items and no output schema, the description covers ownership and id discovery, and return values need not be explained. It still omits append-vs-replace behavior and ordering semantics, which an agent needs before committing a bulk write.

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?

Top-level coverage is effectively 0% in the schema, but 'Same item format as create_timeline' gives a usable pointer for the events and periods structures and the description explains where timeline_id comes from. That compensates partially, but the agent must open a sibling tool's schema to learn the item shape.

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 (add) and resources (events and periods) scoped to a timeline the user owns. An agent can distinguish it from create_timeline (new timeline) and delete_events (removal), though update_event is never mentioned as a contrast. Clear, but the sibling differentiation is partial.

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

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

Explicitly routes the agent to list_my_timelines to obtain the required timeline_id, which is a concrete prerequisite step. It also points at create_timeline for the item format. It does not say when to use update_event instead, so it lacks exclusions.

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

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

Annotations declare readOnly=false and destructive=false; the description goes beyond them by disclosing the premium gating and the resulting error (with a plans-page link), plus ownership constraints on the source and the visibility of the output. It doesn't describe what happens to events/access settings on the copy.

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

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

Two tight sentences, with the core action front-loaded and the premium caveat following. 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?

Handles the premium/error path well, but with no output schema and two undocumented parameters, the agent doesn't know what the tool returns (e.g. the new timeline's ID) — information it would need to chain into update or add_events calls.

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 carry parameter meaning and it doesn't. 'timeline_id' is only weakly implied as the source timeline, while the 'title' parameter — presumably the new timeline's title — is never mentioned, leaving the agent to guess whether it renames the copy.

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?

Specific verb+resource ('Copy a public timeline ... to the user's account as a private timeline'), and it clarifies the source scope (public or the user's own) and the result (private, editable). It doesn't explicitly distinguish itself from create_timeline, but the copy semantics are clear enough that an agent won't confuse the two.

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?

Implied usage: copy an existing timeline rather than build one from scratch. It states the Premium prerequisite and what happens without it, which is useful routing context, but it never names an alternative tool or an explicit 'use this when' condition.

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

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

Annotations only say it is a non-read-only, non-destructive write; the description adds the consequential facts an agent must relay: the timeline is saved publicly on the user's page, anyone on the internet can see it, and the agent must tell the user the title and link. It also discloses a behavior the caller cannot control — Time.Graphics picks the text color — and describes what is returned (view, edit and embed links) despite there being no output 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?

Front-loaded with the action and the one-call workflow, then formatting rules, then the disclosure obligation. Every sentence carries information the agent needs and none repeat the name or 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 five-parameter write tool with deeply nested event/period objects and no output schema, the description covers what the caller must supply (dates, style book reference), what it cannot control (text color), what happens as a side effect (public visibility) and what comes back (view/edit/embed links). The remaining limits and defaults live in the 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 only 20%, so the description has to carry weight; it does explain the tricky part — ISO date strings with negative years for BC ('-0044-03-15' is 15 March 44 BC) — and points to timegraphics://guide for icon types, sizes and colors. It says nothing about the access enum (public/link/private, Premium-gated), the periods date_from/date_to semantics, or the 300-event / 100-period limits, which the schema only partly covers.

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 ('Create an interactive timeline on the user's Time.Graphics account') and frames it as a one-shot operation, which implicitly separates it from add_events / update_event that mutate an existing timeline. An agent can distinguish this from all ten siblings without opening a schema.

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

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

Explicitly scopes usage ('any request to make, build or draw a timeline, chronology, roadmap or history') and gives a workflow instruction: compose all events and periods first, then call once. It does not name the alternative sibling (e.g., add_events for extending an existing timeline), so the exclusion side 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?

Annotations already carry destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description adds non-obvious behavior on top: the timeline must be user-owned and the agent must confirm with the user before executing. It does not describe what happens to the remaining timeline after removal or whether partial failures are possible, which a destructive tool would ideally mention.

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 the action and scope, followed by the input source and the confirmation gate. No sentence is redundant or 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 two-parameter destructive tool with annotations covering safety and no output schema, the description supplies the essential preconditions: ownership, id provenance, and user confirmation. Only the post-deletion outcome and partial-failure behavior are left 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?

Schema description coverage is 0%, so the description must compensate; it partially does by explaining where event_ids originate (get_timeline). However, it never clarifies that event_ids is an array supporting batch deletion, nor that timeline_id is a numeric identifier, leaving half the semantics to type inspection 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 ('Remove events or periods') scoped to a timeline the user owns, which cleanly separates it from add_events and update_event. It stops short of naming a sibling explicitly, so the differentiation is implied by scope 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?

Gives the prerequisite source for ids ('Ids come from get_timeline') and a gating rule ('Ask the user before calling'), which tells the agent both when it has valid input and when it must pause. There is no explicit statement of when not to use it, but the confirmation rule covers the main misuse risk.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses the returned download link and the free-tier limitation that the file is watermarked and missing some events.

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, no waste. The core action and return value come first, with the premium caveat as a distinct second sentence that adds information rather than padding.

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

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

With only two parameters and no output schema, the description covers what to pass and what comes back (download link) plus a meaningful fidelity caveat. Minor gap: no mention of whether export is synchronous or how long it takes, or whether access permissions on the timeline are 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 0%, so the description must compensate. It does partly: it names the two output formats (matching the enum) and states that timeline_id may be the user's own or a public timeline. It gives no detail on the default format or what identifier form is accepted, so the gap is only partially filled.

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+outputs: render a timeline as PNG or PDF and return a download link. No sibling tool (get_timeline, list_my_timelines, search_timelines) does rendering or export, so the purpose is unambiguous.

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 — no 'when to use' or exclusions, and no sibling is named as an alternative. The description does clarify the input scope ('the user's own or a public one'), which helps an agent decide which timeline_id is valid.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the returned account fields but does not disclose auth requirements, rate limits, or response format details beyond those fields.

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

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

The description is a single compact sentence that front-loads the returned data. It is appropriately sized for a simple zero-parameter read tool, though the fragment lacks an explicit verb and reads slightly telegraphically.

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 zero-parameter read tool with no output schema, the description usefully enumerates the returned account fields. It is nearly complete, though it could clarify that this returns the authenticated user's account rather than an arbitrary account.

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 are no parameter semantics to explain. The baseline for a zero-parameter tool applies, and the description correctly avoids introducing unnecessary parameter discussion.

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 account information is retrieved: user name, plan, plan end date, and timeline count. This clearly distinguishes it from the timeline/event siblings, though it lacks an explicit verb such as 'retrieves'.

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 guidance or comparison to alternatives. The usage is implied by the returned account fields, and there are no account-focused sibling tools, so the agent can infer its role but receives no direct routing instruction.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the non-obvious authorization model (public vs owner-only) beyond that. It does not describe size/volume of the returned event set or any pagination, which is the main remaining behavioral gap.

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

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

Two tight sentences, front-loaded with what the tool returns and why (ids for follow-up calls), then the access constraint. No filler, though the second sentence's compressed phrasing takes a moment to parse.

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

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

With no output schema, the description carries the burden of describing returns and does so adequately — events, periods, and reusable ids. The only shortfall is where timeline_id comes from, which an agent must guess before it can invoke the tool.

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

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

Schema description coverage is 0% and the single parameter timeline_id is bare integer with no explanation. The description never says whether the id comes from list_my_timelines/search_timelines or what form it takes, so the agent gets no help on the one input it must supply.

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?

Specific verb plus resource ('Read a timeline with all its events and periods') and even names the downstream tools the returned ids feed into (update_event, delete_events). This clearly separates it from list_my_timelines and search_timelines, which return collections rather than one timeline's full contents.

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 access rule ('Public timelines are readable without sign-in, other timelines only by their owner') tells the agent when this call will succeed versus fail, which is real usage context. It stops short of explicitly routing the agent to search_timelines/list_my_timelines when it doesn't yet have an id.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that with ordering ('newest first') and a return-field projection, but says nothing about pagination behavior, total counts, or what happens when limit is exceeded.

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 zero waste, front-loading the action, ordering, and return shape before the filter detail. Nothing could be removed without losing 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 no output schema, the description usefully enumerates returned fields and sort order. The remaining gap is limit semantics (default 20, max 100) and pagination, which an agent needs to call it well, but overall it is close to sufficient for a simple list tool.

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

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

Schema description coverage is 0%, so the description carries the burden: it does explain that query filters by title, which the schema does not. However, limit is left completely unexplained in both places, so only half the 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?

States a specific verb and resource ('List the user's timelines') plus what each row contains ('id, title, access and events count'). It implicitly separates itself from the singular sibling get_timeline, though it never names a sibling outright.

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 'query filters by title' hints at search behavior but the description never says when to pick this over search_timelines or get_timeline. Usage is implied rather than stated, leaving the agent to infer the selection rule.

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/non-destructive/closed-world, so the bar is lower. The description adds genuinely new context — 'Works without sign-in' (auth requirements) and that matching is by title — which annotations do not cover.

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 the core action, with no filler. Each sentence contributes something (what, auth, when).

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

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

For a simple read-only, no-output-schema tool, the description covers purpose, auth, and a usage trigger. The notable gap is the undocumented limit/pagination, but safety and scope needs are 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 0%, so the description must compensate. 'By title' usefully clarifies that the required query matches titles, but the limit parameter (default 10, max 50, pagination behavior) is left entirely undocumented in both schema and 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?

Uses a specific verb (Search) and resource (public timelines on Time.Graphics), and narrows scope to matching by title. 'Public' implicitly distinguishes it from list_my_timelines, but no sibling is named 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?

'A good start before creating a new one' gives one clear usage scenario (dedupe check before create_timeline). However, it never states when NOT to use it or contrasts it with list_my_timelines for private timelines, leaving the main routing decision to inference.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world mutation. The description adds genuine value beyond them by disclosing the Premium paywall and the concrete failure behavior (error plus plans-page link). It still omits what a successful call returns and whether access can be reverted by calling the tool again.

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

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

Two tight sentences: the action and its three outcome states come first, and the paywall caveat follows. Nothing is redundant and 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 two-parameter mutation with no output schema, the description covers action, ownership precondition, premium gating, and failure mode. The remaining gap is the success response shape and whether non-owned or invalid timeline_id produces a distinct error.

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 carry parameter meaning; it partially does by glossing 'link' as 'visible by link only' and 'private', which map to the enum, but timeline_id is never described beyond the implied ownership. The enum values are self-explanatory, which limits the residual 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?

States a precise verb (make ... public/link/private), the resource (a timeline), and enumerates all three resulting states. No sibling tool touches access settings, so the definition is unambiguously distinct from create_timeline, copy_timeline, and the event tools.

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

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

Gives the ownership precondition ('a timeline the user owns') and the premium gating condition that determines success or failure. It does not name alternatives, but no sibling offers a comparable capability, so there is little left to route between.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: partial-update semantics, an ownership constraint, and the source of required ids. It does not mention error behavior for an invalid event_id or whether type must match event-vs-period kind.

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 compact sentences, front-loaded with the mutation verb and a field list that earns its length by mapping to the schema. The long enumeration is dense but purposeful; only the jargon ("side of the line") costs a little clarity.

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 12-param mutating tool with a sparse schema and no output schema, the definition supplies the missing essentials: ownership scope, id provenance, and patch semantics, while annotations handle reversibility and world-boundary. Nothing critical to invoking it correctly is absent.

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

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

Schema coverage is only 42%, so the description must carry weight — and it largely does, giving plain-language mappings for otherwise undocumented params (link=url, size=scale, side of the line=over_line, icon type=type) and covering title/date/color/description. It does not address date_to or the timeline_id/event_id pairing beyond "Ids come from get_timeline".

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 a precisely scoped resource ("one event or period of a timeline the user owns"), then enumerates the mutable fields. It is clearly distinguishable from add_events/delete_events, though it never names those siblings 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?

"Ids come from get_timeline" gives a concrete prerequisite and names the tool that supplies the required identifiers. "Only the fields you send are changed" clarifies the patch semantics so an agent knows it need not resend the whole object. No explicit when-not-to-use guidance versus add_events, but the 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.