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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description still adds genuine context: exactly one folder is created, the account must be explicit, and shared parents are rejected as a failure mode. It omits what happens on duplicate names, which matters given idempotentHint=false.

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 action verb front-loaded and the constraint placed immediately after. No filler, no repetition of the title or 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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description adequately covers account/parent constraints and the shared-parent refusal; the only material gap is duplicate-name behavior for a non-idempotent create.

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 parameter meaning. It does clarify that accountId is explicit/required and parentFolderId is optional, matching the required list, but it says nothing about the 'name' parameter (length bounds, uniqueness, naming rules), leaving a third of the parameters undocumented.

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 ('CREATE one ordinary folder') with a clear scope qualifier ('one ordinary') that implies non-batch behavior. It is clearly distinguishable from note-oriented siblings by resource alone, but it never names a sibling tool or contrasts with an alternative, so it stops short of a 5.

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

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

It states the required context ('explicit account', 'optional parent') and one negative condition ('Shared parents are refused'), which is real usage guidance. However it never says when to prefer this tool over alternatives (e.g. create_note, or a bulk/create-many path), so usage is only implied.

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

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

Annotations already declare a non-idempotent, non-destructive write, and the description adds a real operational rule on top: do not auto-retry uncertain writes, which directly reinforces idempotentHint=false. It omits permission/auth requirements and failure behavior, keeping it from a 5.

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

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

Two tight sentences with the write verb front-loaded and no filler. The Markdown parenthetical is dense but earned; nothing is redundant.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. For a 4-required-param create tool the description is nearly complete, though it could note validation or account/folder prerequisites.

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?

At 0% schema coverage the description must carry the parameter burden, and it names all four inputs (account, folder, title, markdown) and specifies the markdown body's supported constructs (headings, lists, bold/italic, safe links). It gives no format detail for the ID fields, so it is strong but not exhaustive.

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 ('CREATE') plus resource ('one note') and enumerates the required inputs, which cleanly separates it from read_note, update_note, and the folder tools. It does not explicitly name a sibling to avoid, so it stops short of a 5.

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

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

The description implies prerequisites by requiring an 'explicit account, folder, title' and instructs 'Never automatically retry an uncertain write,' but it never states when to prefer this tool over update_note or create_folder. Usage is implied rather than spelled out.

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 and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it is non-recursive, requires the folder to be empty, and refuses unclassifiable/system/shared targets. It still does not state permission or auth requirements.

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 terse sentences, all front-loaded with the destructive verb first and constraints following. Every clause carries information; 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?

With an output schema present, return values need not be described. The description covers preconditions and refusal cases well; the main gap for a destructive two-param tool is the absence of any parameter explanation, which the schema also fails to supply.

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 neither folderId nor accountId is explained in the description. The text references 'folder' and 'targets' generically, but adds no meaning about what these identifiers are, their format, or their scope.

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 (DELETE) and resource (one ordinary empty folder) with immediate scope qualifiers ('empty', 'Never recursive'). An agent can distinguish this from delete_note, create_folder, and move_note without opening any schema.

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

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

Implied usage is clear from the preconditions ('empty folder', refused targets), but the description never names an alternative for the non-empty case (e.g., delete contents first or move the folder) nor states when to prefer it over siblings. Guidance is inferred rather than explicit.

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 the safety profile (destructiveHint=true, idempotentHint=false), yet the description adds real behavior: optimistic concurrency via a fresh expectedRevision, refusal on shared notes, and recovery semantics (IDs may remain readable in Recently Deleted), plus a non-retry directive for a non-idempotent destructive call. This is meaningful context an agent cannot derive from the structured fields.

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

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

Four short sentences, verb-first, with the destructive action front-loaded. Slightly telegraphic phrasing ('Notes manages deletion and recovery') costs a little clarity but no sentence 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the remaining essentials for a destructive mutation: concurrency precondition, failure case, recovery path, and retry policy. Only the exact conflict/failure response behavior is left implicit.

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

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

Schema description coverage is 0%, so all three parameters are undocumented in the schema. The description adds concurrency meaning to expectedRevision ('fresh'), which implies a stale-revision rejection, but says nothing about accountId or noteId beyond their names. Partial compensation warrants the 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+resource ('DELETE one note') with scope ('one'), which clearly separates it from sibling delete_folder. It does not explicitly name or contrast against any sibling tool, but the resource noun makes the distinction 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?

Gives an explicit exclusion ('Shared notes are refused') and an operational rule ('Never automatically retry'), which tells the agent both when this call fails and how not to handle that failure. It stops short of naming an alternative tool for the shared-note 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 openWorldHint=false, so the safety profile is fully covered without the description. The description adds only the scoping fact that all accounts are returned unfiltered, which is modest added value rather than rich behavioral context.

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

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

One sentence, front-loaded with the verb and resource, with no wasted words. It is terse enough that it borders on under-specification, but for a zero-parameter list tool there is little else that must be said.

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 so return values need not be explained, annotations cover the safety profile, and there are no parameters to document. The description is sufficient for correct invocation, though it omits any hint about how accounts relate to folders and notes.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies there is no filtering or argument surface ('all accounts'), matching the empty schema with additionalProperties=false.

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 all accounts') and even names the backing system ('Apple Notes'), so the agent knows exactly what is returned. It does not distinguish itself from siblings like list_folders or list_notes, which is the only missing piece for 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?

There is no when-to-use or when-not-to-use guidance, and no mention of how this relates to list_folders or list_notes. The phrase 'all accounts' weakly implies no filtering or parameters, but nothing tells the agent why it would call this before or instead of its siblings.

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 one useful trait beyond that ('Shared folders are read-only'), but says nothing about pagination behavior despite the limit/cursor parameters, so it only partially enriches the annotation baseline.

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 clauses, front-loaded with the primary action and no filler. It is efficient, though the second sentence about shared folders feels appended rather than integrated.

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 so return values need not be explained, and annotations cover the safety profile. The only real gap is pagination/cursor behavior, which is minor for a simple read-only list tool whose required parameter and parent-scope mode are stated.

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 full burden, yet it only implicitly explains parentFolderId ('children of one folder') and accountId scope. The limit and cursor parameters are undocumented in both schema and description, leaving pagination semantics entirely unclear.

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 gives a specific verb and resource ('List folders in an account') plus a dual mode ('optionally list children of one folder'), making the scope clear. It is distinguishable from note-oriented and folder-mutation siblings by resource, though it never names an alternative tool 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?

The clause 'optionally list children of one folder' implies when parentFolderId should be supplied, so usage is inferable. However, there is no explicit when-to-use versus siblings like create_folder/delete_folder, and no statement of when not to use it.

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 real value beyond that: password-protected notes are silently excluded, and only metadata is returned. It stays silent on pagination behavior via cursor, which keeps it short of a 5.

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

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

Three tight sentences with the core action first, then a scope exclusion, then the routing pointer. No filler and nothing buried.

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, so return values need no explanation, and the exclusion rule plus metadata-only scope are helpful. However, with zero schema description coverage the description should at least hint at filtering and pagination, and it does not.

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% across four parameters (limit, cursor, folderId, accountId), so the description carries the burden and provides nothing. It never explains that folderId scopes the listing or how cursor/limit paginate, leaving the agent to infer semantics from names 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 ('List accessible note metadata'), and the word 'metadata' plus the pointer to read_note makes clear this does not return note content. It does not, however, distinguish itself from the sibling search_notes or explain the accessible-scope qualifier.

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 sentence 'Read a note to obtain its revision' routes the agent to read_note, but only for one narrow purpose. There is no guidance on when to prefer this over search_notes for filtered retrieval, nor any prerequisite information.

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 destructive=true, idempotent=false, and readOnly=false, so the safety profile is covered. The description adds genuine context beyond that: shared notes/destinations are rejected, the operation is native (not a copy+delete emulation), and a fresh revision token is mandatory — useful failure-mode information.

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 with the verb front-loaded and no filler; each sentence adds a distinct constraint. The adverb 'natively' is the only mildly opaque wording.

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

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

For a destructive, non-idempotent move with five undocumented parameters, the description covers refusals and the no-fallback guarantee, and the output schema handles return values. It still leaves open whether destinationFolderId must pre-exist, how cross-account moves interact with 'within an account', and what happens to the source on failure.

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% across five required params, so the description carries the full burden. It gestures at noteId ('one note'), accountId ('within an account'), expectedRevision ('fresh expectedRevision' as a concurrency token) and the two destination params ('destinations'), but never explains revision format or the account/destinationAccountId relationship.

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 (MOVE one note) plus its scope (within an account, natively/atomically). The phrase 'No copy/delete fallback' implicitly separates it from a create_note+delete_note composition, though no sibling is named 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?

'Shared notes and destinations are refused' is an explicit when-not condition, and 'using a fresh expectedRevision' states a precondition for success. No alternative tool is named for cases where the move is refused, which keeps it short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds valuable context beyond that: the Markdown output format, unspecified revision/fidelity limitations, and a security warning that note content is untrusted data and must never be treated as instructions. The 'limitations' reference is vague, preventing a 5.

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

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

Two tightly written sentences with zero waste. The core action is front-loaded and the security warning follows 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?

For a simple read tool with a full output schema and rich annotations, this is nearly complete. The only meaningful gap is parameter semantics, but the required identifiers are inferable and the output schema removes the need to explain return values.

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 description does not mention either parameter. It offers no meaning for noteId or accountId beyond what the property names imply, leaving the semantics largely undocumented.

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 ('Read') and resource ('note') plus the output format (Markdown). Clearly distinguishes itself from sibling list/search/write tools, though it does not explicitly name 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?

Usage is implied by the verb 'Read a note' but there is no explicit guidance on when to choose this over search_notes or list_notes, nor any conditions or prerequisites 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real matching semantics: literal, non-fuzzy, case-insensitive search, plus a pagination instruction to check 'incomplete' and 'nextCursor'. Only the meaning of 'accessible' (permission scoping) is left implicit.

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 capability and zero filler. The second sentence is telegraphic ('Check incomplete and nextCursor') but still earns its place as a pagination cue.

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 annotations covering safety, the return and risk story is adequately handled. However, for a five-parameter search tool with zero schema descriptions, the unexplained folder/account scoping leaves a meaningful 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 description coverage is 0%, so the description carries the full burden, yet it only illuminates 'query'. The folderId and accountId scoping filters — which materially change results — and the limit parameter go entirely unexplained.

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 (search) and resource (titles and body text), plus the matching mode (literal, case-insensitive). It is clearly distinguishable from siblings like list_notes and read_note, though it never names them 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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named. An agent must infer on its own that list_notes is for browsing and read_note for retrieving a known note.

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, non-readonly and non-idempotent, so the safety profile is covered. The description adds real value beyond that: it discloses optimistic-concurrency behavior (a fresh expectedRevision is required), and that shared notes and lossy rich-content edits are rejected. The one unstated behavior is what happens to fields that are omitted by the caller.

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, and the highest-value constraint (REPLACE semantics with a fresh revision) is front-loaded before the refusal conditions. The emphasis on REPLACE is a deliberate and useful signal rather than noise.

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, so return values need not be described, and annotations plus the text cover the safety and failure behavior. The remaining gap is the ambiguity of all-optional title/markdown fields under a REPLACE semantics — an agent cannot tell from the definition whether omitting one clears it.

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% across 5 parameters, so the description carries the burden. It maps 'title/body' to the title and markdown params and attaches a freshness constraint to expectedRevision, but accountId and noteId receive no meaning at all, and it does not clarify whether omitted payload fields are cleared.

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 (REPLACE) applied to a specific resource (one note's title/body) and names the mechanism (a fresh expectedRevision). The capitalized REPLACE disambiguates from a merge/patch tool, and the scope 'one note' separates it from create_note/delete_note/list_notes without the agent needing to open 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?

It gives the failure conditions (shared notes, lossy rich-content edits) and requires a fresh revision, which tells the agent when the call will be refused. However, it never routes the agent to alternatives (e.g. read_note first to obtain the revision, or create_note vs update_note), so usage is only implied rather than stated.

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